[[how-to-userinfo]] = How-to: Customize the OpenID Connect 1.0 UserInfo response :index-link: ../how-to.html :docs-dir: .. This guide shows how to customize the xref:protocol-endpoints.adoc#oidc-user-info-endpoint[UserInfo endpoint] of the xref:index.adoc[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. * xref:guides/how-to-userinfo.adoc#enable-user-info[Enable the User Info Endpoint] * xref:guides/how-to-userinfo.adoc#customize-user-info[Customize the User Info response] [[enable-user-info]] == Enable the User Info Endpoint The xref:protocol-endpoints.adoc#oidc-user-info-endpoint[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 https://openid.net/specs/openid-connect-core-1_0.html#UserInfoRequest[UserInfo request]. > The Access Token obtained from an OpenID Connect Authentication Request MUST be sent as a Bearer Token, per Section 2 of https://openid.net/specs/openid-connect-core-1_0.html#RFC6750[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]. [[sample.userinfo]] [source,java] ---- include::{examples-dir}/main/java/sample/userinfo/EnableUserInfoSecurityConfig.java[] ---- TIP: Click on the "Expand folded text" icon in the code sample above to display the full example. This configuration provides the following: <1> A Spring Security filter chain for the xref:{docs-dir}/protocol-endpoints.adoc[Protocol Endpoints]. <2> Resource server support that allows User Info requests to be authenticated with access tokens. <3> An instance of `JwtDecoder` used to validate access tokens. [[customize-user-info]] == Customize the User Info response The following sections describe some options for customizing the user info response. * xref:guides/how-to-userinfo.adoc#customize-id-token[Customize the ID Token] * xref:guides/how-to-userinfo.adoc#customize-user-info-mapper[Customize the User Info Mapper] [[customize-id-token]] === Customize the ID Token By default, the user info response is generated by using claims from the `id_token` that are returned with the xref:protocol-endpoints.adoc#oauth2-token-endpoint[token response]. Using the default strategy, https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims[standard claims] are returned only with the user info response based on the https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims[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`. [[sample.userinfo.idtoken]] [source,java] ---- include::{examples-dir}/main/java/sample/userinfo/idtoken/IdTokenCustomizerConfig.java[] ---- This configuration provides the following: <1> An instance of xref:core-model-components.adoc#oauth2-token-customizer[`OAuth2TokenCustomizer`] for customizing the `id_token`. <2> 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: [source,java] ---- include::{examples-dir}/main/java/sample/userinfo/idtoken/OidcUserInfoService.java[] ---- [[customize-user-info-mapper]] === Customize the User Info Mapper 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 xref:core-model-components.adoc#oauth2-authorization[`OAuth2Authorization`]. The following listing shows how to use the customization option that is available while working directly with the `OAuth2AuthorizationServerConfigurer`. [[sample.userinfo.jwt]] [source,java] ---- include::{examples-dir}/main/java/sample/userinfo/jwt/JwtUserInfoMapperSecurityConfig.java[] ---- This configuration maps claims from the access token (which is a JWT when using the xref:getting-started.adoc#sample.gettingStarted[Getting Started config]) to populate the user info response and provides the following: <1> A Spring Security filter chain for the xref:{docs-dir}/protocol-endpoints.adoc[Protocol Endpoints]. <2> A user info mapper that maps claims in a domain-specific way. <3> An example showing the configuration option for customizing the user info mapper. <4> Resource server support that allows User Info requests to be authenticated with access tokens. <5> An example showing how to apply the `OAuth2AuthorizationServerConfigurer` to the Spring Security configuration. 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 xref:guides/how-to-userinfo.adoc#customize-id-token[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: [source,java] ---- include::{examples-dir}/main/java/sample/userinfo/jwt/JwtTokenCustomizerConfig.java[] ---- 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.