feat: Improve support for custom domains with Management SDK (#554)

Author: evansims

src/API/Management.php

@@ -166,7 +166,7 @@ public function getHttpClient(
         // If no token was provided or available from cache, try to get one.
         if ($managementToken === null && $this->configuration->hasClientSecret()) {
             $authentication = $authentication ?? new Authentication($this->configuration);
-            $response = $authentication->clientCredentials(['audience' => $this->configuration->formatDomain() . '/api/v2/']);
+            $response = $authentication->clientCredentials(['audience' => $this->configuration->formatDomain(true) . '/api/v2/']);
 
             if (HttpResponse::wasSuccessful($response)) {
                 $response = HttpResponse::decodeContent($response);

src/Configuration/SdkConfiguration.php

@@ -32,6 +32,7 @@
  * @method SdkConfiguration setClientId(?string $clientId = null)
  * @method SdkConfiguration setClientSecret(?string $clientSecret = null)
  * @method SdkConfiguration setDomain(?string $domain = null)
+ * @method SdkConfiguration setCustomDomain(?string $customDomain = null)
  * @method SdkConfiguration setEventListenerProvider(?ListenerProviderInterface $eventListenerProvider = null)
  * @method SdkConfiguration setHttpClient(?ClientInterface $httpClient = null)
  * @method SdkConfiguration setHttpMaxRetries(int $httpMaxRetires = 3)
@@ -73,6 +74,7 @@
  * @method string|null getClientId(?\Throwable $exceptionIfNull = null)
  * @method string|null getClientSecret(?\Throwable $exceptionIfNull = null)
  * @method string|string getDomain(?\Throwable $exceptionIfNull = null)
+ * @method string|string getCustomDomain(?\Throwable $exceptionIfNull = null)
  * @method ListenerProviderInterface|null getEventListenerProvider(?\Throwable $exceptionIfNull = null)
  * @method ClientInterface|null getHttpClient(?\Throwable $exceptionIfNull = null)
  * @method int getHttpMaxRetries()
@@ -114,6 +116,7 @@
  * @method bool hasClientId()
  * @method bool hasClientSecret()
  * @method bool hasDomain()
+ * @method bool hasCustomDomain()
  * @method bool hasEventListenerProvider()
  * @method bool hasHttpClient()
  * @method bool hasHttpMaxRetries()
@@ -163,7 +166,8 @@ final class SdkConfiguration implements ConfigurableContract
      *
      * @param array<mixed>|null              $configuration         An key-value array matching this constructor's arguments. Overrides any other passed arguments with the same key name.
      * @param string|null                    $strategy              Defaults to 'webapp'. Should be assigned either 'api', 'management', or 'webapp' to specify the type of application the SDK is being applied to. Determines what configuration options will be required at initialization.
-     * @param string|null                    $domain                Auth0 domain for your tenant.
+     * @param string|null                    $domain                Auth0 domain for your tenant, found in your Auth0 Application settings.
+     * @param string|null                    $customDomain          If you have configured Auth0 to use a custom domain, configure it here.
      * @param string|null                    $clientId              Client ID, found in the Auth0 Application settings.
      * @param string|null                    $redirectUri           Authentication callback URI, as defined in your Auth0 Application settings.
      * @param string|null                    $clientSecret          Client Secret, found in the Auth0 Application settings.
@@ -209,6 +213,7 @@ public function __construct(
         ?array $configuration = null,
         ?string $strategy = 'webapp',
         ?string $domain = null,
+        ?string $customDomain = null,
         ?string $clientId = null,
         ?string $redirectUri = null,
         ?string $clientSecret = null,
@@ -257,12 +262,31 @@ public function __construct(
         $this->validateState();
     }
 
+    /**
+     * Return the configured custom or tenant domain, formatted with protocol.
+     *
+     * @param bool $forceTenantDomain Force the return of the tenant domain even if a custom domain is configured.
+     */
+    public function formatDomain(
+        bool $forceTenantDomain = false
+    ): string {
+        if ($this->hasCustomDomain() && ! $forceTenantDomain) {
+            return 'https://' . $this->getCustomDomain();
+        }
+
+        return 'https://' . $this->getDomain();
+    }
+
     /**
      * Return the configured domain with protocol.
      */
-    public function formatDomain(): string
+    public function formatCustomDomain(): ?string
     {
-        return 'https://' . $this->getDomain();
+        if ($this->hasCustomDomain()) {
+            return 'https://' . $this->getCustomDomain();
+        }
+
+        return null;
     }
 
     /**

src/Token.php

@@ -133,7 +133,7 @@ public function validate(
         ?int $tokenLeeway = null,
         ?int $tokenNow = null
     ): self {
-        $tokenIssuer = $tokenIssuer ?? 'https://' . $this->configuration->getDomain() . '/';
+        $tokenIssuer = $tokenIssuer ?? $this->configuration->formatDomain() . '/';
         $tokenAudience = $tokenAudience ?? $this->configuration->getAudience() ?? [];
         $tokenOrganization = $tokenOrganization ?? $this->configuration->getOrganization() ?? null;
         $tokenNonce = $tokenNonce ?? null;

tests/Unit/Configuration/SdkConfigurationTest.php

@@ -271,6 +271,68 @@
     expect($sdk->formatDomain())->toEqual('https://' . $domain);
 });
 
+test('formatDomain() returns the custom domain when a custom domain is configured', function(): void
+{
+    $domain = uniqid();
+    $customDomain = uniqid();
+
+    $sdk = new SdkConfiguration([
+        'domain' => $domain,
+        'customDomain' => $customDomain,
+        'cookieSecret' => uniqid(),
+        'clientId' => uniqid(),
+        'redirectUri' => uniqid(),
+    ]);
+
+    expect($sdk->formatDomain())->toEqual('https://' . $customDomain);
+});
+
+test('formatDomain() returns the tenant domain even when a custom domain is configured if `forceTenantDomain` argument is `true`', function(): void
+{
+    $domain = uniqid();
+    $customDomain = uniqid();
+
+    $sdk = new SdkConfiguration([
+        'domain' => $domain,
+        'customDomain' => $customDomain,
+        'cookieSecret' => uniqid(),
+        'clientId' => uniqid(),
+        'redirectUri' => uniqid(),
+    ]);
+
+    expect($sdk->formatDomain(true))->toEqual('https://' . $domain);
+});
+
+test('formatCustomDomain() returns a properly formatted uri', function(): void
+{
+    $domain = uniqid();
+    $customDomain = uniqid();
+
+    $sdk = new SdkConfiguration([
+        'domain' => $domain,
+        'customDomain' => $customDomain,
+        'cookieSecret' => uniqid(),
+        'clientId' => uniqid(),
+        'redirectUri' => uniqid(),
+    ]);
+
+    expect($sdk->formatCustomDomain())->toEqual('https://' . $customDomain);
+});
+
+test('formatCustomDomain() returns null when a custom domain is not configured', function(): void
+{
+    $domain = uniqid();
+
+    $sdk = new SdkConfiguration([
+        'domain' => $domain,
+        'cookieSecret' => uniqid(),
+        'clientId' => uniqid(),
+        'redirectUri' => uniqid(),
+    ]);
+
+    expect($sdk->formatCustomDomain())->toBeNull();
+});
+
 test('formatScope() returns an empty string when there are no scopes defined', function(): void
 {
     $sdk = new SdkConfiguration([