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 and 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 claimsOnly 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://
orhttps://
.Alternatively, you can also use URN-based namespace identifiers. In that case, the Auth0 URN
urn:auth0
is reserved and cannot be used as a namespace identifier.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 ofe_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?