Migrate Custom Claims

As of 28 July 2022, Auth0 will allow private, non-namespaced custom claims to be added to access and ID tokens. These same claims will also be added to the response of the /userinfo endpoint. To learn more about the types of JWT claims, read JSON Web Token Claims.

Despite allowing the use of private, non-namespaced custom claims, Auth0 strongly recommends the use of public, namespaced custom claims whenever possible. Public, namespaced custom claims are the best way to avoid any collision with future claims added to the standard.

Example

Previously, Auth0 allowed only namespaced claims on access and ID tokens. With the migration to custom claims, non-namespaced claims can be used on access tokens, ID tokens, and the /userinfo endpoint of Auth0's Authentication API.

// an Auth0 action 
exports.onExecutePostLogin = async (event, api) => {

  // public namespaced custom claims 
  api.accessToken.setCustomClaim('https://myDomain.com/myClaim', 'this is a public, namespaced claim');
  api.idToken.setCustomClaim('https://myDomain.com/myClaim', 'this is a public, namespaced claim');

  // non-namespaced custom claims
  api.accessToken.setCustomClaim('myClaim', 'this is a private, non namespaced claim');
  api.idToken.setCustomClaim('myClaim', 'this is a private, non namespaced claim');
};

Was this helpful?

Affected flows

All OpenID Connect (OIDC) flows that Auth0 supports are affected by this migration. To review the list of flows, read Authentication and Authorization Flows.

The following features are also affected:

The following features are affected only when used along with Auth0 Rules and attribute mapping:

Restrictions

Maximum token size

Auth0 will restrict the custom claims payload to a maximum of 100KB. It is important to make sure the payload does not exceed this limit, otherwise the authentication transaction will fail with an error. We recommend you review your use of extensibility code (i.e. Rules, Hooks, or Actions). In particular, review large payloads from external APIs.

To avoid errors, Auth0 recommends using the smallest token payload necessary for your application to operate. You may need to strip any properties that are not crucial before you set the custom claim value.

This restriction is applied to the total payload size of all your custom claims. This includes the custom claims names as well as the associated values, whether they are public namespaced or private non namespaced.

The limit of 100KB is applied to access tokens and ID tokens separately. For example, an access token of 100KB and an ID token of 100KB can be returned in the same transaction.

Examples

// an Auth0 action 
exports.onExecutePostLogin = async (event, api) => {

  // fetching a payload that is superior to 100KB
  const aHeavyPayload = getHeavyPayload();

  // this will fail the authentication
  api.idToken.setCustomClaim('myclaim', aHeavyPayload);

};

Was this helpful?

// an Auth0 action 
exports.onExecutePostLogin = async (event, api) => {

  // fetching a payload that is 50KB
  const a50KBPayload = getHeavyPayload();

  // fetching another payload that is 50KB
  const another50KBPayload = getHeavyPayload();

  // this will fail the authentication
  api.idToken.setCustomClaim('myclaim', a50KBPayload);
  api.idToken.setCustomClaim('https://myDomain.com/myClaim', another50KBPayload);

};

Was this helpful?

// an Auth0 action 
exports.onExecutePostLogin = async (event, api) => {

  // fetching a payload that is 50KB
  const a50KBPayload = getHeavyPayload();

  // fetching another payload that is 50KB
  const another50KBPayload = getHeavyPayload();

  // this will succeed
  api.accessToken.setCustomClaim('myclaim', a50KBPayload);
  api.idToken.setCustomClaim('https://myDomain.com/myClaim', another50KBPayload);

};

Was this helpful?

Restricted claims

Auth0 will restrict the customization of claims used in the OIDC or OAuth2 standards or claims for internal use. Any attempt to modify one of these claims will be ignored. The transaction won't fail, but the claim will not be added to tokens. Auth0 recommends using a public, namespaced claim.

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

Example

// an Auth0 action 
exports.onExecutePostLogin = async (event, api) => {

  // this will be ignored
  api.accessToken.setCustomClaim('roles', 'this is a role, but Auth0 will ignore it');

  // this will succeed, and appear in the token
  api.idToken.setCustomClaim('https://myDomain.com/roles', 'this is a role');

};

Was this helpful?

Restricted token audience

Auth0 will restrict the creation of private, non-namespaced custom claims on access tokens in which the audience is an Auth0 API. Any attempt to set a private, non-namespaced custom claim on an access token where the audience is an Auth0 API will be ignored. The transaction will not fail, but the claim will not be added to your token. Auth0 recommends not setting custom claims on tokens that are to be consumed by Auth0’s APIs.

ID tokens are not concerned by this restriction.
Public namespaced custom claims are not concerned by this restriction.

The following audience will restrict the creation of private, non-namespaced custom claims:

https://YOUR_TENANT.auth0.com/api or https://YOUR_TENANT.auth0app.com/api
https://YOUR_TENANT.auth0.com/api/v2 or https://YOUR_TENANT.auth0app.com/api/v2
https://YOUR_TENANT.auth0.com/mfa or https://YOUR_TENANT.auth0app.com/mfa

The exception to this restriction is the Auth0 /userinfo audience. Private, non-namespaced custom claims are allowed on the following audience:

https://YOUR_TENANT.auth0.com/userinfo
https://YOUR_TENANT.auth0app.com/userinfo

Examples

// an Auth0 action 
exports.onExecutePostLogin = async (event, api) => {

  // these will be ignored if the audience is an Auth0 audience
  api.accessToken.setCustomClaim('myATclaim', 'this is a claim');
  api.accessToken.setCustomClaim('https://myDomain.com/myATclaim', 'this is a claim');

  // these will succeed, they are not concerned by the audience restriction
  api.idToken.setCustomClaim('myIdTclaim', 'this is a claim');
  api.idToken.setCustomClaim('https://myDomain.com/myIdTclaim', 'this is a claim');

};

Was this helpful?

The example below demonstrates the returned response with custom claims if the audience is not an Auth0 API:

-- A resource owner password flow 
POST https://{yourTenant}.auth0.com/oauth/token

grant_type:password
username:***
password:***
client_id:***
client_secret:***
audience:https://{yourApi}.com -- Note the audience, that is a custom API
scope:openid profile

Was this helpful?

// The Access token returned by Auth0
{
  "iss": "https://{yourTenant}.auth0.com/",
  "sub": ***,
  "aud": [
    "https://{yourApi}.com",
    "https://{yourTenant}.auth0.com/userinfo"
  ],
  "iat": 1655283444,
  "exp": 1655369844,
  "azp": ***,
  "scope": "openid profile",
  "gty": "password",

  // The custom claims were added, because the Audience is not an Auth0 audience
  "myATclaim": "this is a claim",
  "https://{yourDomain}.com/{myATclaim}": "this is a claim"
}

Was this helpful?

The example below demonstrates the returned response with custom claims not added with an Auth0 API audience:

-- A resource owner password flow 
POST https://{yourTenant}.auth0.com/oauth/token

grant_type:password
username:***
password:***
client_id:***
client_secret:***
audience:https://{yourTenant}.auth0.com/api/v2/ -- This is an Auth0 audience 
scope:openid profile

Was this helpful?

// The Access token returned by Auth0
{
  "iss": "https://{yourTenant}.auth0.com/",
  "sub": ***,
  "aud": [
    "https://{yourTenant}.auth0.com/api/v2/",
    "https://{yourTenant}.auth0.com/userinfo"
  ],
  "iat": 1655283444,
  "exp": 1655369844,
  "azp": ***,
  "scope": "openid profile",
  "gty": "password",

  // The public namespaced custom claims was added, because it is not concerned by this restriction
  // However, the private non-namespaced custom claim {myATclaim} was ignored
  "https://mydomain.com/{myATclaim}": "this is a claim"
}

Was this helpful?

Restriction on Auth0 and Webtask namespaces

Auth0 will restrict the creation of namespaced custom claims with an Auth0 domain as namespace identifier. Auth0 domains are:

auth0.com
webtask.io
webtask.run

Any attempt to set a namespaced custom claim on a token with one of the domains above as an identifier will be ignored. The transaction will not fail, but the claim will not be added to your token.

Before this migration, setting a namespaced custom claim with an Auth0 domain identifier would result in the claim showing up in the /userinfo response. This behavior disappears after the migration and such custom claims are completely ignored.

// an Auth0 action 
exports.onExecutePostLogin = async (event, api) => {

  // none of these will be added to tokens nor to /userinfo response
  api.idToken.setCustomClaim('https://example.auth0.com', 'this is a claim');
  api.idToken.setCustomClaim('https://example.webtask.io', 'this is a claim');
  api.idToken.setCustomClaim('https://example.webtask.run', 'this is a claim');

};

Was this helpful?

OIDC user profile claims

Auth0 will now allow OIDC user profile claims to be added to access tokens.

Attempts to add OIDC user profile claims to the access token were silently ignored prior to this migration. With the updated behavior, access tokens will contain these OIDC user profile claims.

If you add OIDC user profile claims to access tokens, the same scope restrictions apply as are applicable to ID tokens. For example, to add email claim to access tokens, the flow must be triggered with a scope that contains email.

You can add the following OIDC user profile claims to access tokens:

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

Example

// an Auth0 action 
exports.onExecutePostLogin = async (event, api) => {

  // this was ignored so far. From this migration on, the claim will be added to access tokens 
  // if the scope contains 'email'
  api.accessToken.setCustomClaim('email', 'myemail@domin.com');

  // this was ignored so far. From this migration on, the claim will be added to access tokens 
  // if the scope contains 'profile'
  api.accessToken.setCustomClaim('family_name', 'A family name');

};

Was this helpful?

SAML2 add-on and Web Service Federation Protocol (WS-Fed) attribute mapping with Auth0 Rules

Similar to using Auth0 Rules to make changes to the user object, app_metadata or user_metadata pre-migration claims also merge contents when the claim is set on the context.idToken object and the names conflict. To learn more about the object properties, read User Object Properties In Rules.

Using custom claims, however, Auth0 gives precedence to the claim that was set on the context.idToken object.

This change impacts Auth0 Rules that set app_metadata and user_metadata via context.id_token (assigning objects to them) and, at the same time, uses these fields in attribute mapping for SAML add-on or Web Service Federation Protocol (WS-Fed).

Example 1: Auth0 ignores attribute mapping when context.idToken.app_metadata is set with an empty object.

// an Auth0 Rule
function (user, context, callback) {

  user.app_metadata.a_claim = 'This is a claim';
  user.app_metadata.another_claim = 'This is a another claim';

  context.samlConfiguration = context.samlConfiguration || {};

  context.samlConfiguration.mappings = {
    "a_claim": "app_metadata.a_claim",
    "another_claim": "app_metadata.another_claim"
  };

  context.idToken.app_metadata = {};

  return callback(null, user, context);
}

Was this helpful?

SAML response prior to this migration:

<samlp:Response>
    (...)
    <saml:Assertion>
        (...)
        <saml:AttributeStatement xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
            <saml:Attribute Name="a_claim" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
                <saml:AttributeValue xsi:type="xs:string">
                    This is a claim
                </saml:AttributeValue>
            </saml:Attribute>
            <saml:Attribute Name="another_claim" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
                <saml:AttributeValue xsi:type="xs:string">
                    This is a another claim
                </saml:AttributeValue>
            </saml:Attribute>
        </saml:AttributeStatement>
    </saml:Assertion>
</samlp:Response>

Was this helpful?

SAML response with the upgraded behavior:

<samlp:Response>
    (...)
    <saml:Assertion>
        (...)
        <saml:AttributeStatement xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
    </saml:Assertion>
</samlp:Response>

Was this helpful?

Example 2: The version of app_metadata in context.id_token takes precedence.

// an Auth0 Rule
function (user, context, callback) {

  user.app_metadata.a_claim = 'This is a claim';
  user.app_metadata.another_claim = 'This is a another claim';

  context.samlConfiguration = context.samlConfiguration || {};

  context.samlConfiguration.mappings = {
    "a_claim": "app_metadata.a_claim",
    "another_claim": "app_metadata.another_claim",
    "claim_set_via_id_token": "app_metadata.claim_set_via_id_token"
  };

  context.idToken.app_metadata = {
  	claim_set_via_id_token: "This is a claim which was set via context.idToken"
  };

  return callback(null, user, context);
}

Was this helpful?

SAML Response prior to this migration:

<samlp:Response>
    (...)
    <saml:Assertion>
        (...)
        <saml:AttributeStatement xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
            <saml:Attribute Name="a_claim">
                <saml:AttributeValue xsi:type="xs:anyType">
                    This is a claim
                </saml:AttributeValue>
            </saml:Attribute>
            <saml:Attribute Name="another_claim">
                <saml:AttributeValue xsi:type="xs:anyType">
                    This is a another claim
                </saml:AttributeValue>
            </saml:Attribute>
            <saml:Attribute Name="claim_set_via_id_token">
                <saml:AttributeValue xsi:type="xs:anyType">
                    This is a claim which was set via context.idToken
                </saml:AttributeValue>
            </saml:Attribute>
        </saml:AttributeStatement>
    </saml:Assertion>
</samlp:Response>

Was this helpful?

SAML response with the upgraded behavior:

<samlp:Response>
    (...)
    <saml:Assertion>
        (...)
        <saml:AttributeStatement xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
            <saml:Attribute Name="claim_set_via_id_token" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
                <saml:AttributeValue xsi:type="xs:string">
                    This is a claim which was set via context.idToken
                </saml:AttributeValue>
            </saml:Attribute>
        </saml:AttributeStatement>
    </saml:Assertion>
</samlp:Response>

Was this helpful?

Add private, non-namespace claims to tokens

Custom claims behavior will not change for members of the custom claims beta program. This feature is already enabled.

You can now add private, non-namespaced custom claims to the payload of access and ID tokens.

Example

// an Auth0 action 
exports.onExecutePostLogin = async (event, api) => {

  // previously ignored
  // From this migration on, the claim will be added to access tokens
  api.accessToken.setCustomClaim('myATclaim', 'this is a claim');

  // previously ignored
  // From this migration on, the claim will be added to ID tokens
  api.idToken.setCustomClaim('myIdTclaim', 'this is a claim');

};

Was this helpful?

Private, non-namespace claims to /userinfo

Auth0 now returns private, non-namespaced custom claims in the /userinfo response when set on ID tokens.

Example

// an Auth0 action 
exports.onExecutePostLogin = async (event, api) => {

  // this was ignored so far. 
  // From this migration on, this claim will be returned in /userinfo
  api.idToken.setCustomClaim('myIdTclaim', 'this is a claim');

};

Was this helpful?

-- a call to /userinfo 
GET https://{yourTenant}.auth0.com/userinfo
Authorization: Bearer {yourAccessToken}

Was this helpful?

// the response from /userinfo
{
    "sub": ***,
    (...)
    "myIdTclaim": "this is a claim"
}

Was this helpful?

Actions

Review tenant logs

First, check your tenant logs for deprecation notices to determine whether your tenant is affected by the migration.

Navigate to Auth0 Dashboard > Monitoring > Logs.
Search the logs for type: depnote AND description: *Custom*claims*.

Example

Provided below is an example deprecation log that is generated whenever extensibility code triggers.

{
  "date": "2022-06-28T08:12:52.084Z",
  "type": "depnote",
  "description": "Custom claims must be namespaced: This feature is being deprecated. Please see details.feature of this log for more information.",
  "connection_id": "",
  "client_id": ****,
  "client_name": ****,
  "details": {
    "feature": {
      "grant": "password",
      "access_token_claims_to_be_allowed": [
        "myclaim"
      ],
      "access_token_claims_to_be_disallowed": [
        "gty"
      ],
      "id_token_claims_to_be_allowed": [
        "myclaim"
      ],
      "id_token_claims_to_be_disallowed": [
        "gty"
      ],
      "id": "legacy_custom_claims",
      "name": "Custom claims must be namespaced when they are added through rules / actions / hooks."
    }
  },
  "log_id": ****,
  "_id": ****,
  "isMobile": false,
  "user_agent": "Other 0.0.0 / Other 0.0.0",
  "id": ****
}

Was this helpful?

Fix Auth0 rules for SAML2 add-on and Web Service Federation Protocol (Ws-Fed)

If you set app_metadata or user_metadata claims on the context.idToken object using SAML2 add-on or Web Service Federation Protocol (Ws-Fed) with Auth0 Rules along with attribute mapping, you will need to update your configuration to adjust for how Auth0 evaluates conflicting claim names between these objects. There are several possible fixes:

Make sure that the code of your Auth0 Rule always gives precedence to the content of objects set on context.id_token:
```
// my_claim will be ignored, this line of code is not relevant anymore,
// prefer setting my_claim on `context.idToken`
user.app_metadata.my_claim = 'a value'; 

// this version of app_metadata will take precedence over any other change 
context.idToken.app_metadata = {
  another_claim: 'another value'
};

// Only `another_claim` will appear in SAML/WsFed responses
```
Was this helpful?
/
If you are using SAML2 add-on or Web Service Federation Protocol (Ws-Fed) attribute mapping, Avoid setting app_metadata or user_metadata claims on the context.idToken object. Replace these claims with name-spaced claims when possible:
```
context.idToken['https://mydomain.com/app_metadata'] = {
  my_claim: 'my claim'
};
```
Was this helpful?
/
Use a condition on the current protocol or on the current client to exclude statements setting app_metadata or user_metadata when the protocol is samlp or wsfed.
```
if (!['samlp', 'wsfed'].includes(context.protocol)) {
    context.idToken.app_metadata = {
      claim_set_via_id_token: "This is a claim which was set via context.idToken"
    };
}
```
Was this helpful?
/

Disable legacy behavior

Before you disable legacy behavior, we recommend you review the list of changes and verify your applications and integrations are compatible.

If your tenant does not have the toggle option, your tenant is not impacted and no other action is needed.

Navigate to Auth0 Dashboard > Tenant Settings > Advanced and search for Migrations.
Use the toggle to disable Custom claims must be namespaced.

Troubleshoot

Migrate Custom Claims

Example

Affected flows

Restrictions

Maximum token size

Examples

Restricted claims

Example

Restricted token audience

Examples

Restriction on Auth0 and Webtask namespaces

OIDC user profile claims

Example

SAML2 add-on and Web Service Federation Protocol (WS-Fed) attribute mapping with Auth0 Rules

Add private, non-namespace claims to tokens

Example

Private, non-namespace claims to /userinfo

Example

Actions

Review tenant logs

Example

Fix Auth0 rules for SAML2 add-on and Web Service Federation Protocol (Ws-Fed)

Disable legacy behavior