User profile claims and scope
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
The OIDC specification defines a set of standard claims about users that can be returned in ID Tokens or in the response from /userinfo.
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:
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:
Note that the
user_id property is sent as
sub in the ID Token, and that
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:
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.
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.
Token refresh flow and custom claims
When an application requests new tokens using a Refresh Token, the new tokens will not automatically inherit any custom claims previously added. But since rules run on a token refresh flow as well, the same claim customization code will be executed in these cases. This gives the flexibility of adding or changing claims in newly issued tokens without forcing applications to obtain a new refresh token.
- Calling your APIs with Auth0 tokens
- User consent and third-party applications
- Custom user profile claims and
- Single sign-on (SSO)
- Initiating authentication flows:
- Refresh Tokens
- Passwordless authentication
- List of breaking changes for OIDC-conformant applications