ArticlesQuickstartsAuth0 APIsSDKs
Contact sales Log in
Custom Claims Migration
Contact sales Log in
Troubleshoot

Custom Claims Migration

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.

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.

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.

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.

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

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

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.

  1. Navigate to Auth0 Dashboard > Monitoring > Logs.

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

  1. Navigate to Auth0 Dashboard > Tenant Settings > Advanced and search for Migrations.

  2. Use the toggle to disable Custom claims must be namespaced.

Was this article helpful?

On This Page