From 1570a56911bf128b2f2e862ef1e88a2a2b003241 Mon Sep 17 00:00:00 2001 From: Joe Grandja Date: Wed, 19 Jul 2023 11:34:02 -0400 Subject: [PATCH] Polish gh-1264 --- .../how-to-custom-claims-authorities.adoc | 43 +++++++++---------- docs/modules/ROOT/pages/how-to.adoc | 2 +- .../CustomClaimsConfiguration.java | 17 +++++++- ...tomClaimsWithAuthoritiesConfiguration.java | 19 +++++++- 4 files changed, 54 insertions(+), 27 deletions(-) rename docs/src/main/java/sample/{customClaims => customclaims}/CustomClaimsConfiguration.java (53%) rename docs/src/main/java/sample/{customClaims => customclaims}/authorities/CustomClaimsWithAuthoritiesConfiguration.java (70%) diff --git a/docs/modules/ROOT/pages/guides/how-to-custom-claims-authorities.adoc b/docs/modules/ROOT/pages/guides/how-to-custom-claims-authorities.adoc index 0792906f..1e0272f8 100644 --- a/docs/modules/ROOT/pages/guides/how-to-custom-claims-authorities.adoc +++ b/docs/modules/ROOT/pages/guides/how-to-custom-claims-authorities.adoc @@ -1,13 +1,13 @@ [[how-to-custom-claims-authorities]] -= How-to: Add authorities as custom claims in JWT-based access tokens += How-to: Add authorities as custom claims in JWT access tokens :index-link: ../how-to.html :docs-dir: .. This guide demonstrates how to add resource owner authorities to a JWT access token. The term "authorities" may represent varying forms such as roles, permissions, or groups of the resource owner. -To make resource owners' authorities available to the resource server, we add custom claims to an access token issued by Spring Authorization Server. -The client using the issued token to access protected resources will then have information about the resource owner’s level of access, among other potential uses and benefits. +To make resource owner's authorities available to the resource server, we add custom claims to the access token. +When the client uses the access token to access a protected resource, the resource server will be able to obtain the information about the resource owner's level of access, among other potential uses and benefits. * xref:guides/how-to-custom-claims-authorities.adoc#custom-claims[Add custom claims to JWT access tokens] * xref:guides/how-to-custom-claims-authorities.adoc#custom-claims-authorities[Add authorities as custom claims to JWT access tokens] @@ -15,40 +15,37 @@ The client using the issued token to access protected resources will then have i [[custom-claims]] == Add custom claims to JWT access tokens -You may add your own custom claims to an access token using `OAuth2TokenCustomizer` bean. -Please note that this bean may only be defined once, and so care must be taken care of to ensure that you are customizing the appropriate token type — an access token in this case. -If you are interested in customizing the identity token, see xref:guides/how-to-userinfo.adoc#customize-user-info-mapper[the UserInfo mapper guide for more information]. +You may add your own custom claims to an access token using an `OAuth2TokenCustomizer` `@Bean`. +Please note that this `@Bean` may only be defined once, and so care must be taken to ensure that you are customizing the appropriate token type — an access token in this case. +If you are interested in customizing the ID Token, see the xref:guides/how-to-userinfo.adoc#customize-user-info-mapper[User Info Mapper guide] for more information. The following is an example of adding custom claims to an access token — in other words, every access token that is issued by the authorization server will have the custom claims populated. -[[sample.customClaims]] +[[sample.customclaims]] [source,java] ---- -include::{examples-dir}/main/java/sample/customClaims/CustomClaimsConfiguration.java[] +include::{examples-dir}/main/java/sample/customclaims/CustomClaimsConfiguration.java[] ---- [[custom-claims-authorities]] == Add authorities as custom claims to JWT access tokens -To add authorities of the resource owner to a JWT-based access token, we can refer to the custom claim mapping method above -and populate custom claims with the authorities of the `Principal`. +To add authorities of the resource owner to a JWT access token, we can refer to the custom claim mapping method above and populate a custom claim with the authorities of the `Principal`. -We define a sample user with a mix of authorities for demonstration purposes, and populate custom claims in an access token -with those authorities. +We define a sample user with a set of authorities for demonstration purposes, and populate a custom claim in the access token with those authorities. -[[sample.customClaims.authorities]] +[[sample.customclaims.authorities]] [source,java] ---- -include::{examples-dir}/main/java/sample/customClaims/authorities/CustomClaimsWithAuthoritiesConfiguration.java[] +include::{examples-dir}/main/java/sample/customclaims/authorities/CustomClaimsWithAuthoritiesConfiguration.java[] ---- -<1> Define a sample user `user1` with an in-memory user details service. -<2> Define a few roles for `user1`. -<3> Define `OAuth2TokenCustomizer` `@Bean` that allows for customizing JWT token claims. -<4> Check whether the JWT token is an access token. -<5> From the encoding context, modify the claims of the access token. -<6> Extract user roles from the `Principal` object. The role information for internal users is stored as a string prefixed with `ROLE_`, so we strip the prefix here. -<7> Set custom claim `roles` to the set of roles collected from the previous step. +<1> Define a sample user `user1` with an in-memory `UserDetailsService`. +<2> Assign the roles for `user1`. +<3> Define an `OAuth2TokenCustomizer` `@Bean` that allows for customizing the JWT claims. +<4> Check whether the JWT is an access token. +<5> Access the default claims via the `JwtEncodingContext`. +<6> Extract the roles from the `Principal` object. The role information is stored as a string prefixed with `ROLE_`, so we strip the prefix here. +<7> Set the custom claim `roles` to the set of roles collected from the previous step. -As a result of this customization, authorities information about the user will be included as a custom claim within the -access token. +As a result of this customization, authorities information about the user will be included as a custom claim in the access token. diff --git a/docs/modules/ROOT/pages/how-to.adoc b/docs/modules/ROOT/pages/how-to.adoc index 933442fd..69b6167d 100644 --- a/docs/modules/ROOT/pages/how-to.adoc +++ b/docs/modules/ROOT/pages/how-to.adoc @@ -11,4 +11,4 @@ * xref:guides/how-to-ext-grant-type.adoc[Implement an Extension Authorization Grant Type] * xref:guides/how-to-userinfo.adoc[Customize the OpenID Connect 1.0 UserInfo response] * xref:guides/how-to-jpa.adoc[Implement core services with JPA] -* xref:guides/how-to-custom-claims-authorities.adoc[Add authorities as custom claims in JWT-based access tokens] +* xref:guides/how-to-custom-claims-authorities.adoc[Add authorities as custom claims in JWT access tokens] diff --git a/docs/src/main/java/sample/customClaims/CustomClaimsConfiguration.java b/docs/src/main/java/sample/customclaims/CustomClaimsConfiguration.java similarity index 53% rename from docs/src/main/java/sample/customClaims/CustomClaimsConfiguration.java rename to docs/src/main/java/sample/customclaims/CustomClaimsConfiguration.java index 0e121bb8..150bba79 100644 --- a/docs/src/main/java/sample/customClaims/CustomClaimsConfiguration.java +++ b/docs/src/main/java/sample/customclaims/CustomClaimsConfiguration.java @@ -1,4 +1,19 @@ -package sample.customClaims; +/* + * Copyright 2020-2023 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * https://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package sample.customclaims; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; diff --git a/docs/src/main/java/sample/customClaims/authorities/CustomClaimsWithAuthoritiesConfiguration.java b/docs/src/main/java/sample/customclaims/authorities/CustomClaimsWithAuthoritiesConfiguration.java similarity index 70% rename from docs/src/main/java/sample/customClaims/authorities/CustomClaimsWithAuthoritiesConfiguration.java rename to docs/src/main/java/sample/customclaims/authorities/CustomClaimsWithAuthoritiesConfiguration.java index 8361eda7..9d02291d 100644 --- a/docs/src/main/java/sample/customClaims/authorities/CustomClaimsWithAuthoritiesConfiguration.java +++ b/docs/src/main/java/sample/customclaims/authorities/CustomClaimsWithAuthoritiesConfiguration.java @@ -1,4 +1,19 @@ -package sample.customClaims.authorities; +/* + * Copyright 2020-2023 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * https://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package sample.customclaims.authorities; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; @@ -22,7 +37,7 @@ public class CustomClaimsWithAuthoritiesConfiguration { UserDetails user = User.withDefaultPasswordEncoder() .username("user1") // <1> .password("password") - .roles(new String[] { "user", "admin" }) // <2> + .roles("user", "admin") // <2> .build(); return new InMemoryUserDetailsManager(user); }