Use Organization Names in Authentication API

By default, the Authentication API uses organization IDs to identify specific organizations. If needed, you can configure your tenant to also use organization names as an identifier. However, there are usability and security implications to consider before enabling this feature. To better understand the potential impact, review the Considerations and recommendations section.

Configuring your tenant to support organization names in the Authentication API results in the following:

• The organization parameter in the /authorize and SAML endpoints can accept both organization names and IDs.

• Access and ID tokens automatically include both org_name and org_id claims.

You can enable this feature through your Auth0 Dashboard or the Management API:

• Auth0 Dashboard: Select Settings from the left-side menu and choose the Advanced tab. In the Settings section, enable the Allow Organization Names in Authentication API toggle.

• Management API: Use the PATCH /api/v2/tenants/settings endpoint to set allow_organization_name_in_authentication_api to true. For more information, review the Management API documentation.

The following example demonstrates an authorization code flow that uses organization names.

1. Call the /authorize endpoint passing your organization name for the organization parameter:

https://{yourDomain}/authorize?
    response_type=code&
    client_id={yourClientId}&
    redirect_uri={https://yourApp/callback}&
    scope={scope}&
    state={state}&
    organization={yourOrganizationName}

2. After obtaining the authorization code, call the POST /oauth/token endpoint to retrieve access and ID tokens:

curl --request POST \
  --url 'https://{yourDomain}/oauth/token' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data grant_type=authorization_code \
  --data 'client_id={yourClientId}' \
  --data 'client_secret={yourClientSecret}' \
  --data 'code=yourAuthorizationCode}' \
  --data 'redirect_uri={https://yourApp/callback}'

3. The decoded tokens returned contain both the org_id and org_name claims:

{
    "sub": "google-oauth2|10...17",
    "aud": [
        "https://yourApp"
    ],
    "iat": 1686840988,
    "exp": 1686927388,
    "azp": "Suo...qTd",
    "scope": "openid profile",
    "org_id": "{yourOrganizationId}",
    "org_name": "{yourOrganizationName}"
}

Before using organization names in the Authentication API, it is important to understand the primary differences between organization names and IDs.

Unlike organization IDs (which remain static), you can change the name of an organization at any time after initial creation. Additionally, you can reuse organization names within a single tenant as long as it's only assigned to exactly one organization at a time. In practice, this means you can change the name of one of your organizations and reuse its original name for another organization in your tenant. Organization names are only unique within a single tenant; the same name may be used for two or more organizations across multiple tenants.

In general, using organization IDs is recommended when validating tokens. However, if using organization names is more appropriate for your use case, consider the implications below when implementing the feature.

Consider the potential impacts below when using organization names to request and validate tokens:

• Organization names can be reused: Long-lived tokens do not expire when an organization changes its name, and the org_name claims in those tokens retain their original value. If the original name is later reused by a different organization, such tokens may grant users unauthorized access to data and resources managed by the new organization.

• Organization names are only unique within a single tenant: If your API does not verify iss (issuer) claims in tokens, an organization with the same name in a different tenant could generate tokens that are incorrectly accepted by your API.

• Organization names can be changed: If you change the name of an organization, your applications must provide the new organization name in Authentication API requests. As tokens can be long-lived, the org_name claim in a token may no longer match the current organization name, which could prevent applications from granting access to the appropriate organization.

Due to the possible security and usability impacts, using IDs instead of names to validate tokens is recommended when working with organizations. If you choose to use organization names, follow the best practices below for an optimal experience:

• Always validate the iss claim to ensure a token was issued by your Auth0 tenant.

• Avoid reusing organization names that previously existed in your tenant. To prevent reuse and ensure previously issued tokens cannot be used to access different organizations, maintain an accurate and up-to-date record of historic organization names.

• Avoid renaming organizations once they are in use unless absolutely necessary. If you choose to rename an organization, be aware that existing access and ID tokens do not automatically contain the new organization name. After renaming an organization, ensure you prompt users to log in again.