102 lines
5.7 KiB
Plaintext
102 lines
5.7 KiB
Plaintext
|
|
[[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> Enabling OpenID Connect 1.0 will autoconfigure 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> Enabling OpenID Connect 1.0 will autoconfigure resource server support that allows User Info requests to be authenticated with access tokens.
|
|
<4> 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 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.
|