This guide shows how to customize the UserInfo endpoint of the Spring Authorization Server. The purpose of this guide is to demonstrate how to enable the endpoint and use the available customization options to produce a custom response.
The OpenID Connect 1.0 UserInfo endpoint is an OAuth2 protected resource, which REQUIRES an access token to be sent as a bearer token in the UserInfo request.
The Access Token obtained from an OpenID Connect Authentication Request MUST be sent as a Bearer Token, per Section 2 of OAuth 2.0 Bearer Token Usage [RFC6750].
Before customizing the response, you need to enable the UserInfo endpoint. The following listing shows how to enable the {spring-security-reference-base-url}/servlet/oauth2/resource-server/jwt.html[OAuth2 resource server configuration].
link:{examples-dir}/main/java/sample/userinfo/EnableUserInfoSecurityConfig.java[role=include]|
Tip
|
Click on the "Expand folded text" icon in the code sample above to display the full example. |
This configuration provides the following:
-
A Spring Security filter chain for the Protocol Endpoints.
-
Enabling OpenID Connect 1.0 will autoconfigure resource server support that allows User Info requests to be authenticated with access tokens.
-
An instance of
JwtDecoderused to validate access tokens.
The following sections describe some options for customizing the user info response.
By default, the user info response is generated by using claims from the id_token that are returned with the token response.
Using the default strategy, standard claims are returned only with the user info response based on the requested scopes during authorization.
The preferred way to customize the user info response is to add standard claims to the id_token.
The following listing shows how to add claims to the id_token.
link:{examples-dir}/main/java/sample/userinfo/idtoken/IdTokenCustomizerConfig.java[role=include]This configuration provides the following:
-
An instance of
OAuth2TokenCustomizerfor customizing theid_token. -
A custom service used to obtain user info in a domain-specific way.
The following listing shows a custom service for looking up user info in a domain-specific way:
link:{examples-dir}/main/java/sample/userinfo/idtoken/OidcUserInfoService.java[role=include]To fully customize the user info response, you can provide a custom user info mapper capable of generating the object used to render the response, which is an instance of the OidcUserInfo class from Spring Security.
The mapper implementation receives an instance of OidcUserInfoAuthenticationContext with information about the current request, including the OAuth2Authorization.
The following listing shows how to use the customization option that is available while working directly with the OAuth2AuthorizationServerConfigurer.
link:{examples-dir}/main/java/sample/userinfo/jwt/JwtUserInfoMapperSecurityConfig.java[role=include]This configuration maps claims from the access token (which is a JWT when using the Getting Started config) to populate the user info response and provides the following:
-
A Spring Security filter chain for the Protocol Endpoints.
-
A user info mapper that maps claims in a domain-specific way.
-
Enabling OpenID Connect 1.0 will autoconfigure resource server support that allows User Info requests to be authenticated with access tokens.
-
An example showing the configuration option for customizing the user info mapper.
The user info mapper is not limited to mapping claims from a JWT, but this is a simple example that demonstrates the customization option. Similar to the example shown earlier where we customize claims of the ID token, you can customize claims of the access token itself ahead of time, as in the following example:
link:{examples-dir}/main/java/sample/userinfo/jwt/JwtTokenCustomizerConfig.java[role=include]Whether you customize the user info response directly or use this example and customize the access token, you can look up information in a database, perform an LDAP query, make a request to another service, or use any other means of obtaining the information you want to be presented in the user info response.