spring-authorization-server/docs/modules/ROOT/pages/guides/how-to-userinfo.adoc

[[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.