Subdomain URL Placeholders

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:

  • 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&…)

URLs with the {organization_name} placeholder will be evaluated in addition to exact match URLs (https://app.exampleco.com) and URLs with wildcards (https://*.exampleco.com). You must not rely on any specific order of evaluation of the URLs.

Avoid registering URLs with wildcard and Organization placeholders in the same configuration field for an application as it may lead to undesirable behavior and make troubleshooting difficult. As an example, consider an application with two Allowed Callback URLs: https://*.exampleco.com and https://{organization_name}.exampleco.com. A redirect_uri with the value of https://company-a.exampleco.com would be considered valid even if there were no Organizations with the name company-a registered in your tenant; this is due to the evaluation of the wildcard placeholder.

Wildcard URL placeholders

Wildcard placeholders in subdomains should not be used in production applications. Auth0 recommends URLs with the {organization_name} placeholder where relevant.

Manage these settings in Dashboard > Applications > Applications in the following fields:

  • Allowed Callback URLs: List of URLs to which Auth0 is allowed to redirect users after they authenticate.

  • Allowed Logout URLs: List of URLs to which you can redirect users after they log out from Auth0.

  • Allows Web Origins: List of URLs from where an authorization request using Cross-Origin Authentication, Device Flow, and web_message as the response mode can originate.

  • Allowed Origins (CORS): List of URLs that will be allowed to make requests from JavaScript to Auth0 API (typically used with CORS).

Avoid using wildcard placeholders for subdomains in production application callbacks and allowed origins as it can make your application vulnerable to attacks.

You can use the star symbol (*) as a wildcard for subdomains, but it must be used in accordance with the following rules in order to properly function:

  • The protocol of the URL must be http or https. Protocols such as com.example.app and service:jmx:rmi will not work.

  • The wildcard must be located in a subdomain within the hostname component. https://*.com will not work.

  • The wildcard must be located in the subdomain furthest from the root domain. https://sub.*.example.com will not work.

  • The URL must not contain more than one wildcard. https://*.*.example.com will not work.

  • A wildcard may be prefixed and/or suffixed with additional valid hostname characters. https://prefix-*-suffix.example.com will work.

  • A URL with a valid wildcard will not match a URL more than one subdomain level in place of the wildcard. https://*.example.com will not work with https://sub1.sub2.example.com.

Organization URL placeholders

You can use {organization_name} as a placeholder to dynamically specify a registered organization’s name in a URL (https://{organization_name}.exampleco.com). URLs with the {organization_name} placeholder should only be used on domains that you fully control (for example, https://{organization_name}.exampleco.com where you control the exampleco.com domain).

Manage these settings in Dashboard > Applications > Applications in the following fields:

  • Allowed Callback URLs: List of URLs to which Auth0 is allowed to redirect users after they authenticate.

  • Allowed Origins (CORS): List of URLs that will be allowed to make requests from JavaScript to Auth0 API (typically used with CORS).

The following restrictions apply when using the {organization_name} placeholder:

  • The protocol of the URL must be http: or https:. com.example.app://{organization_name}.exampleco.com will not work.

  • The placeholder must be located in a subdomain within the hostname component. https://{organization_name} or https://exampleco.com/{organization_name} will both not work.

  • The placeholder must be located in the subdomain furthest from the root domain. https://sub.{organization_name}.exampleco.com will not work.

  • The URL must not contain more than one placeholder. https://{organization_name}.{organization_name}.exampleco.com will not work.

  • 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.

Learn more