diff --git a/main/docs/get-started/applications/wildcards-for-subdomains.mdx b/main/docs/get-started/applications/wildcards-for-subdomains.mdx index 3ea2c6116..8d4760b10 100644 --- a/main/docs/get-started/applications/wildcards-for-subdomains.mdx +++ b/main/docs/get-started/applications/wildcards-for-subdomains.mdx @@ -14,7 +14,7 @@ You can use various placeholders to act as dynamic text entries in your URLs. ## How URL evaluation works -A URL containing an `{organization_name}` placeholder will only be evaluated when all the following the conditions are met: +A URL containing an `{organization_name}` placeholder will only be evaluated when all the following conditions are met: * The application has the `organization_usage` set to `allow` or `require` * A transaction was performed in the context of an organization (for example, initiating an authorization transaction with the organization parameter: `/authorize?organization=org_bVss9Do3994SIbiH&…`) @@ -63,8 +63,45 @@ The following restrictions apply when using the `{organization_name}` placeholde * A placeholder must not be prefixed nor suffixed with additional valid hostname characters. `https://prefix-{organization_name}-suffix.exampleco.com` will not work. * A placeholder **must not** be used in conjunction with a wildcard in the URL. `https://{organization_name}.*.exampleco.com` will not work. +## Custom domain URL placeholders + +You can use `{custom_domain.metadata.KEY}` as a placeholder to dynamically specify a URL based on metada associated with the Custom Domain used in the request. This allows you to support multiple custom domains with different application URLs within the same tenant. + +For a comprehensive overview of this feature, see [Multiple Custom Domains](/docs/customize/custom-domains/multiple-custom-domains) + +### Validation rules + +The following restrictions apply when using Custom Domain placeholders: + + * **Public prefix required**: The metadata key used in the placeholder must start with `public_` or `PUBLIC_` (for example, `{custom_domain.metadata.public_callback_subdomain}`). Keys without this prefix are ignored at runtime for security reasons. + * **Protocol**: The protocol of the URL must be `http` or `https`. + * **Location**: The placeholder must be located in the domain or subdomain component. It cannot be used in the URL path. + * Valid: `https://{custom_domain.metadata.public_app_url}.example.com/login` + * Invalid: `https://example.com/{custom_domain.metadata.public_path}` + * **Nesting**: You cannot access nested metadata properties. Only top-level keys are supported. + * **No wildcards**: A custom domain placeholder must not be used in conjunction with a wildcard (`*`) in the same URL. + * **Data type**: The value in the custom domain metadata must be a String. If the key does not exist, or the value is not a String, the URL is ignored during validation. + +### Supported fields +These placeholders can be configured for the following Application URLs: + * Allowed Callback URLs + * Allowed Logour URLs + * Allowed Web Origins + * Allowed Origins (CORS) + +For more information, see [Application Settings](https://auth0.com/docs/get-started/applications/application-settings#application-uris). + + +Custom domain placeholders are not supported for third-party applications. + + +### Using with Organization placeholders + +You can combine the Custom Domain placeholder with the `{organization_name}` placeholder, as long as your flow supports it. Both placeholders are evaluated and replaced at runtime. + + ## Learn more * [Confidential and Public Applications](/docs/get-started/applications/confidential-and-public-applications) * [First-Party and Third-Party Applications](/docs/get-started/applications/confidential-and-public-applications/first-party-and-third-party-applications) -* [Enable Third-Party Applications](/docs/get-started/applications/confidential-and-public-applications/enable-third-party-applications) \ No newline at end of file +* [Enable Third-Party Applications](/docs/get-started/applications/confidential-and-public-applications/enable-third-party-applications)