CerberAuth
What is the OpenID Connect Userinfo Endpoint?
The Userinfo endpoint is a standard feature of the OpenID Connect (OIDC) protocol, designed to provide additional claims (user-related information) about an authenticated user. This endpoint is typically accessed via an HTTP GET request, authenticated using a valid access token issued by the OIDC provider.
The Userinfo endpoint's primary role is to complement the information contained in the ID token. While the ID token serves as proof of authentication and includes a minimal set of claims (such as the user's identifier and metadata), the Userinfo endpoint allows a client application to retrieve richer or more updated user profile data, such as:
- Full name
- Email address
- Phone number
- Locale or timezone
- Custom claims provided by the OIDC provider
When to Use the Userinfo Endpoint Instead of the ID Token?
Dynamic or Updated Information
The Userinfo endpoint is particularly useful when the client application requires dynamic or updated user information. While the ID token provides a snapshot of the user's identity at the time of authentication, the Userinfo endpoint can provide real-time or more detailed information about the user.
This behavior may depends on the OpenID Connect provider implementation. Some providers may return the same information in the ID token and the Userinfo endpoint, while others may provide additional or updated information in the Userinfo response.
Minimal ID Token
To keep the ID token size minimal and avoid bloating it with unnecessary claims, OIDC providers often include only essential user information in the ID token. Additional or less critical information can be retrieved from the Userinfo endpoint when needed.
This separation of concerns allows the ID token to remain lightweight and efficient while still providing the necessary information for client applications to authenticate and authorize users.
It can also help reduce the risk of exposing sensitive user information in the ID token, as only essential claims are included in the token itself. Sometime the ID token can not be stored securely, so it's better to keep it as small as possible.
Custom Claims
The Userinfo endpoint is also a convenient way for OIDC providers to expose custom claims or user attributes that are not part of the standard OIDC claims. By querying the Userinfo endpoint, client applications can access these additional claims and tailor their behavior or user experience based on this information.
How to Access the Userinfo Endpoint?
To access the Userinfo endpoint, a client application must include a valid access token in the Authorization header of an HTTP GET request. The access token is typically obtained during the OIDC authentication flow, either as part of the ID token response or by exchanging an authorization code for an access token.
Here is an example of how a client application can access the Userinfo endpoint using an access token:
GET /userinfo HTTP/1.1
Host: oidc-provider.com
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
Best Practices for Choosing Between ID Token and Userinfo Endpoint
When deciding whether to use the ID token or the Userinfo endpoint, consider the following best practices:
- Use ID Token for Lightweight Authentication: If the application needs to authenticate the user and access a few core claims (e.g., user ID and email), the ID token is sufficient.
- Use Userinfo Endpoint for Rich User Data: When the application requires additional or dynamic user information (e.g., full name, phone number, or custom claims), the Userinfo endpoint is the appropriate choice.
- Combine Both When Necessary: Use the ID token for immediate authentication and call the Userinfo endpoint to fetch additional or updated information as needed.
