Work with Tokens and Organizations

Most identity (ID) tokens and access tokens returned by Auth0 are JSON Web Tokens (JWTs) containing a variety of claims, which are pieces of information asserted about a subject. For example, an ID token (which is always a JWT) can contain a claim called name that asserts that the name of the user authenticating is "John Doe".

There are two types of JWT claims:

• Registered: Claims defined by the JWT specification to ensure interoperability with third-party, or external, applications. OpenID Connect (OIDC) standard claims are reserved claims.

• Custom: Claims that you define yourself. These claims can be non-registered, collision-resistant public claims or non-registered, non-public private claims subject to collision. Name these claims carefully, such as through namespacing, to avoid collision with reserved claims or other custom claims. It can be challenging to deal with two claims of the same name that contain differing information.

To learn more about claims, read JSON Web Token Claims.

To authenticate a user through an organization, an organization parameter is added to a call to the /authorize endpoint. Examples of tokens returned when a user logs in through organizations are as follows.

In the following example, note that https://marketplace/roles and https://namespace.exampleco.com/ are custom claims that have been added to the token, while the other included claims are standard.

{
  "https://marketplace/roles": [
    "marketplace-administrator"
  ],
  "https://namespace.exampleco.com": "my custom claim",
  "nickname": "firstName.lastName",
  "name": "firstName.lastName@email.com",
  "picture": "https://s.gravatar.com/avatar/638",
  "updated_at": "2021-03-23T11:34:14.566z",
  "email": "adam.housman@auth0.com",
  "email_verified": true,
  "sub": "auth0|602c0dcab993d10073daf680",
  "org_id": "org_9ybsU1dN2dKfDkBi"
}

{
  "iss": "https://exampleco.auth0.com/",
  "sub": "auth0|602c0dcab993d10073daf680",
  "aud": [
    "https://example-api/",
    "https://exampleco.auth0.com/userinfo"  
  ],
  "iat": 1616499255,
  "exp": 1616585655,
  "azp": "ENDmmAJsbwI1hOG1KPJddQ8LHjV6kLkV",
  "scope": "openid profile email",
  "org_id": "org_9ybsU1dN2dKfDkBi",
  "permissions": [
    "delete:stuff",
    "read:stuff",
    "write:stuff"  
  ]
}

When the organization parameter is added to a call to the /authorize endpoint, Auth0 SDKs automatically validate the org_id claim, which is returned as part of any generated tokens. However, for security purposes, additional validation should be performed when tokens are received.

For web applications:

If no organization parameter was passed to the /authorize endpoint, but an org_id claim is present in the ID token, then your application should validate the claim to ensure that the value received is expected or known and that it corresponds to an entity your application trusts, such as a paying customer. If the claim cannot be validated, then the application should deem the token invalid.

For APIs:

If an org_id claim is present in the access token, then your API should validate the claim to ensure that the value received is expected or known and that it corresponds to an entity your application trusts, such as a paying customer. If the claim cannot be validated, then the API should deem the token invalid.

In particular:

• The iss (issuer) claim should be checked to ensure the token was issued by Auth0.

• The org_id claim should be checked to ensure it is a value that is already known to the application. This could be validated against a known list of organization IDs, or perhaps checked in conjunction with the current request URL. For example, the subdomain may hint at which organization should be used when validating the ID Token.

Normally, validating only the issuer would be enough to ensure that the token was issued by Auth0. In the case of organizations, however, additional checks should be made to ensure that the organization within your Auth0 tenant is expected.

• Understand How Auth0 Organizations Work
• Create Your First Organization
• Custom Development with Organizations
• Configure Organizations