You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
102 lines
5.7 KiB
102 lines
5.7 KiB
|
|
[[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.
|
|
|