Create Custom Claims

To read custom claims on access and ID tokens, you must use JSON Web Tokens (JWT) and pass an audience (aud) in an OIDC login flow. To learn more, read Access Tokens.

When configuring custom claims on JWTs, you want to avoid collisions. To keep your custom claims from colliding with any reserved claims or claims from other resources, give them a collision-resistant name. Auth0 recommends using a namespaced format.

General restrictions

Auth0 applies the following restrictions to custom claims:

  • Custom claims payload is set to a maximum of 100KB

  • OPENID standard claims or claims used internally by Auth0 cannot be customized or modified

  • Access tokens with an Auth0 API audience, excluding the /userinfo endpoint, cannot have private, non-namespaced custom claims 

  • Only specified OIDC user profile claims can be added to access tokens

The following claims are subject to Auth0's restrictions:

  • acr
  • act
  • active
  • amr
  • at_hash
  • ath
  • attest
  • aud
  • auth_time
  • authorization_details
  • azp
  • c_hash
  • client_id
  • cnf
  • cty
  • dest
  • entitlements
  • events
  • exp
  • groups
  • gty
  • htm
  • htu
  • iat
  • internalService
  • iss
  • jcard
  • jku
  • jti
  • jwe
  • jwk
  • kid
  • may_act
  • mky
  • nbf
  • nonce
  • object_id
  • org_id
  • org_name
  • orig
  • origid
  • permissions
  • roles
  • rph
  • s_hash
  • sid
  • sip_callid
  • sip_cseq_num
  • sip_date
  • sip_from_tag
  • sip_via_branch
  • sub
  • sub_jwk
  • toe
  • txn
  • typ
  • uuid
  • vot
  • vtm
  • x5t#S256

Non-restricted claims

You can create claims for sensitive user information to enhance the user profile and add to the user experience. These claims are consumed by your application from ID tokens. To learn more about using non-restricted claims, read ID Tokens, and keep in mind Token Best Practices if you use them.

The following claims are only subject to general restrictions:

  • address
  • birthdate
  • email
  • email_verified
  • family_name
  • gender
  • given_name
  • locale
  • middle_name
  • name
  • nickname
  • phone_number
  • phone_number_verified
  • picture
  • preferred_username
  • profile
  • updated_at
  • website
  • zoneinfo

Namespaced guidelines

Use the following guidelines for namespace identifiers:

  • Use any non-Auth0 HTTP or HTTPS URL as a namespace identifier. Auth0 domains cannot be used as namespace identifiers, and include:

    • auth0.com

    • webtask.io

    • webtask.run

  • Use a URL that you control as a namespace identifier; this allows you to avoid the risk that someone else is using the same namespace. The namespace URL does not have to point to an actual resource. It is only used as an identifier; it will not be called.

  • Begin the URL with http:// or https://.

  • Create multiple namespaces, as needed.

Once you have chosen your namespace, append the claim to it to create a namespaced claim, which can be added to a token. For example:

http://www.example.com/favorite_color

Non-namespaced guidelines

Use the following guidelines for non-namespaced custom claims:

  • Unless absolutely necessary for your application, use public, namespaced custom claims that are collision resistant.

  • Create claims with meaningful and collision resistant names. For example, use employee_id instead of e_id.

  • Keep the claim names and values as light as possible, passing only the data strictly necessary for your application.

  • Avoid assigning heavy payloads to custom claims.

For more examples of custom claims added to a token, see Sample Use Cases: Scopes and Claims.

Create custom claims

Use Auth0 Actions to create custom claims. The api object allows you to use the method setCustomClaim on access tokens or ID tokens.

Example

exports.onExecuteCredentialsExchange = async (event, api) => {
  api.accessToken.setCustomClaim('myClaim', 'this is a private, non namespaced claim');
};

Was this helpful?

/

Learn more