User profile claims and scope

Adoption Guide

This document is part of the adoption guide for OIDC-conformant authentication. If you haven't already, we strongly suggest reading the introduction before reading this document.

The behavior of the scope parameter has been changed to conform to the OIDC specification.

Instead of requesting arbitrary application-specific claims, applications can request any of the standard OIDC scopes such as profile and email, as well as any scopes supported by the API they want to access.

Standard claims

The OIDC specification defines a set of standard claims about users that can be returned in ID Tokens or in the response from /userinfo.

Custom claims

To improve compatibility for applications, Auth0 now returns profile information in a structured claim format as defined by the OIDC specification. You can still add custom claims, but they must conform to a namespaced format to avoid possible collisions with standard OIDC claims. Otherwise, it is no longer possible to add arbitrary claims to ID Tokens or Access Tokens.

For example, suppose an identity provider returns a favorite_color claim as part of the user’s profile, and that we’ve used the Auth0 management API to set application-specific information for this user.

This would be the profile stored by Auth0:

  "email": "",
  "email_verified": true,
  "user_id": "custom|123",
  "favorite_color": "blue",
  "user_metadata": {
    "preferred_contact": "email"

This is a normalized user profile, which is a protocol-agnostic representation of this user as defined by Auth0. When performing an OIDC conformant login, Auth0 would return the following ID Token claims to the application:

  "iss": "",
  "sub": "custom|123",
  "aud": "my_client_id",
  "exp": 1311281970,
  "iat": 1311280970,
  "email": "",
  "email_verified": true

Note that the user_id property is sent as sub in the ID Token, and that favorite_color and user_metadata are not present in the OIDC response from Auth0. This is because OIDC does not define standard claims to represent all the information in this user’s profile. We can, however, define a non-standard claim by namespacing it through a rule:

function (user, context, callback) {
  const namespace = '';
  context.idToken[namespace + 'favorite_color'] = user.favorite_color;
  context.idToken[namespace + 'preferred_contact'] = user.user_metadata.preferred_contact;
  callback(null, user, context);

Any non-Auth0 HTTP or HTTPS URL can be used as a namespace identifier, and any number of namespaces can be used. The namespace URL does not have to point to an actual resource, it’s only used as an identifier and will not be called by Auth0., and are Auth0 domains and therefore cannot be used as a namespace identifier.

This follows a recommendation from the OIDC specification stating that custom claim identifiers should be collision-resistant. While this is not mandatory according to the specification, Auth0 will always enforce namespacing when performing OIDC-conformant login flows, meaning that any custom claims without HTTP/HTTPS namespaces will be silently excluded from tokens.

If you need to add custom claims to the Access Token, the same applies but using context.accessToken instead.

Please note that adding custom claims to ID Tokens through this method will also let you obtain them when calling the /userinfo endpoint. However, rules run when the user is authenticating, not when /userinfo is called.

Further reading