Custom Claims Migration

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 Management 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:

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

  • 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://YOUR_TENANT.auth0.com/oauth/token

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

Was this helpful?

/

// The Access token returned by Auth0
{
  "iss": "https://YOUR_TENANT.auth0.com/",
  "sub": ***,
  "aud": [
    "https://myapi.com",
    "https://YOUR_TENANT.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://mydomain.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://YOUR_TENANT.auth0.com/oauth/token

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

Was this helpful?

/

// The Access token returned by Auth0
{
  "iss": "https://YOUR_TENANT.auth0.com/",
  "sub": ***,
  "aud": [
    "https://YOUR_TENANT.auth0.com/api/v2/",
    "https://YOUR_TENANT.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?

    /

    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://YOUR_TENANT.auth0.com/userinfo
    Authorization: Bearer YOUR_ACCESS_TOKEN

    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?

    /

    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.