Create Custom Claims

Create Custom Claims

To keep your custom claims from colliding with any reserved claims or claims from other resources, give them a globally unique 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

Auth0 also restricts the creation of private, non-namespaced custom claims on access tokens in which the audience is an Auth0 API. The exception to this restriction is the Auth0 Authentication API /userinfo endpoint. 

Other than /userinfo, any attempt to set a private, non-namespaced custom claim on an access token where the audience is an Auth0 API will be ignored to avoid collision with internal services or standards. The transaction will not fail, but the claim will not be added to your token. Non-restricted claims can be overwritten.

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, such as SSN or email, 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.

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

Example

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

Was this helpful?

/

Learn more