diff --git a/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/InMemoryOAuth2AuthorizedClientService.java b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/InMemoryOAuth2AuthorizedClientService.java index c05af7bcc2..3876fc4f35 100644 --- a/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/InMemoryOAuth2AuthorizedClientService.java +++ b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/InMemoryOAuth2AuthorizedClientService.java @@ -26,7 +26,7 @@ import java.util.concurrent.ConcurrentHashMap; /** * An {@link OAuth2AuthorizedClientService} that stores - * {@link OAuth2AuthorizedClient Authorized Client(s)} in-memory. + * {@link OAuth2AuthorizedClient Authorized Client(s)} in-memory. * * @author Joe Grandja * @since 5.0 @@ -39,6 +39,11 @@ public final class InMemoryOAuth2AuthorizedClientService implements OAuth2Author private final Map authorizedClients = new ConcurrentHashMap<>(); private final ClientRegistrationRepository clientRegistrationRepository; + /** + * Constructs an {@code InMemoryOAuth2AuthorizedClientService} using the provided parameters. + * + * @param clientRegistrationRepository the repository of client registrations + */ public InMemoryOAuth2AuthorizedClientService(ClientRegistrationRepository clientRegistrationRepository) { Assert.notNull(clientRegistrationRepository, "clientRegistrationRepository cannot be null"); this.clientRegistrationRepository = clientRegistrationRepository; diff --git a/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/OAuth2AuthorizedClient.java b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/OAuth2AuthorizedClient.java index 5297416331..392a947705 100644 --- a/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/OAuth2AuthorizedClient.java +++ b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/OAuth2AuthorizedClient.java @@ -20,10 +20,10 @@ import org.springframework.security.oauth2.core.OAuth2AccessToken; import org.springframework.util.Assert; /** - * A representation of an OAuth 2.0 "Authorized Client". + * A representation of an OAuth 2.0 "Authorized Client". *

- * A client is considered "authorized" when the End-User (Resource Owner) - * grants authorization to the Client to access its protected resources. + * A client is considered "authorized" when the End-User (Resource Owner) + * has granted authorization to the client to access it's protected resources. *

* This class associates the {@link #getClientRegistration() Client} * to the {@link #getAccessToken() Access Token} @@ -39,6 +39,13 @@ public class OAuth2AuthorizedClient { private final String principalName; private final OAuth2AccessToken accessToken; + /** + * Constructs an {@code OAuth2AuthorizedClient} using the provided parameters. + * + * @param clientRegistration the authorized client's registration + * @param principalName the name of the End-User {@code Principal} (Resource Owner) + * @param accessToken the access token credential granted + */ public OAuth2AuthorizedClient(ClientRegistration clientRegistration, String principalName, OAuth2AccessToken accessToken) { Assert.notNull(clientRegistration, "clientRegistration cannot be null"); Assert.hasText(principalName, "principalName cannot be empty"); @@ -48,14 +55,29 @@ public class OAuth2AuthorizedClient { this.accessToken = accessToken; } + /** + * Returns the authorized client's {@link ClientRegistration registration}. + * + * @return the {@link ClientRegistration} + */ public ClientRegistration getClientRegistration() { return this.clientRegistration; } + /** + * Returns the End-User's {@code Principal} name. + * + * @return the End-User's {@code Principal} name + */ public String getPrincipalName() { return this.principalName; } + /** + * Returns the {@link OAuth2AccessToken access token} credential granted. + * + * @return the {@link OAuth2AccessToken} + */ public OAuth2AccessToken getAccessToken() { return this.accessToken; } diff --git a/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/OAuth2AuthorizedClientService.java b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/OAuth2AuthorizedClientService.java index 137e10a344..17b3313065 100644 --- a/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/OAuth2AuthorizedClientService.java +++ b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/OAuth2AuthorizedClientService.java @@ -22,8 +22,8 @@ import org.springframework.security.oauth2.core.OAuth2AccessToken; /** * Implementations of this interface are responsible for the management * of {@link OAuth2AuthorizedClient Authorized Client(s)}, which provide the purpose - * of associating an {@link OAuth2AuthorizedClient#getAccessToken() Access Token} to a - * {@link OAuth2AuthorizedClient#getClientRegistration() Client} and Resource Owner, + * of associating an {@link OAuth2AuthorizedClient#getAccessToken() Access Token} credential + * to a {@link OAuth2AuthorizedClient#getClientRegistration() Client} and Resource Owner, * who is the {@link OAuth2AuthorizedClient#getPrincipalName() Principal} * that originally granted the authorization. * @@ -36,10 +36,34 @@ import org.springframework.security.oauth2.core.OAuth2AccessToken; */ public interface OAuth2AuthorizedClientService { + /** + * Returns the {@link OAuth2AuthorizedClient} associated to the + * provided client registration identifier and End-User's {@code Principal} name + * or {@code null} if not available. + * + * @param clientRegistrationId the identifier for the client's registration + * @param principalName the name of the End-User {@code Principal} (Resource Owner) + * @param a type of OAuth2AuthorizedClient + * @return the {@link OAuth2AuthorizedClient} or {@code null} if not available + */ T loadAuthorizedClient(String clientRegistrationId, String principalName); + /** + * Saves the {@link OAuth2AuthorizedClient} associating it to + * the provided End-User {@link Authentication} (Resource Owner). + * + * @param authorizedClient the authorized client + * @param principal the End-User {@link Authentication} (Resource Owner) + */ void saveAuthorizedClient(OAuth2AuthorizedClient authorizedClient, Authentication principal); + /** + * Removes the {@link OAuth2AuthorizedClient} associated to the + * provided client registration identifier and End-User's {@code Principal} name. + * + * @param clientRegistrationId the identifier for the client's registration + * @param principalName the name of the End-User {@code Principal} (Resource Owner) + */ void removeAuthorizedClient(String clientRegistrationId, String principalName); } diff --git a/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/authentication/OAuth2AuthenticationToken.java b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/authentication/OAuth2AuthenticationToken.java index 3885e19c65..52bd092e59 100644 --- a/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/authentication/OAuth2AuthenticationToken.java +++ b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/authentication/OAuth2AuthenticationToken.java @@ -19,6 +19,7 @@ import org.springframework.security.authentication.AbstractAuthenticationToken; import org.springframework.security.core.Authentication; import org.springframework.security.core.GrantedAuthority; import org.springframework.security.core.SpringSecurityCoreVersion; +import org.springframework.security.oauth2.client.OAuth2AuthorizedClient; import org.springframework.security.oauth2.core.user.OAuth2User; import org.springframework.util.Assert; @@ -26,23 +27,31 @@ import java.util.Collection; /** * An implementation of an {@link AbstractAuthenticationToken} - * that represents an OAuth 2.0 {@link Authentication}. + * that represents an OAuth 2.0 {@link Authentication}. *

- * This {@link Authentication} associates an {@link OAuth2User} Principal + * The {@link Authentication} associates an {@link OAuth2User} {@code Principal} * to the identifier of the {@link #getAuthorizedClientRegistrationId() Authorized Client}, - * which the End-User (Principal) granted authorization to - * so that it can access its protected resource(s) at the UserInfo Endpoint. + * which the End-User ({@code Principal}) granted authorization to + * so that it can access it's protected resources at the UserInfo Endpoint. * * @author Joe Grandja * @since 5.0 * @see AbstractAuthenticationToken * @see OAuth2User + * @see OAuth2AuthorizedClient */ public class OAuth2AuthenticationToken extends AbstractAuthenticationToken { private static final long serialVersionUID = SpringSecurityCoreVersion.SERIAL_VERSION_UID; private final OAuth2User principal; private final String authorizedClientRegistrationId; + /** + * Constructs an {@code OAuth2AuthenticationToken} using the provided parameters. + * + * @param principal the user {@code Principal} registered with the OAuth 2.0 Provider + * @param authorities the authorities granted to the user + * @param authorizedClientRegistrationId the registration identifier of the {@link OAuth2AuthorizedClient Authorized Client} + */ public OAuth2AuthenticationToken(OAuth2User principal, Collection authorities, String authorizedClientRegistrationId) { @@ -65,6 +74,11 @@ public class OAuth2AuthenticationToken extends AbstractAuthenticationToken { return ""; } + /** + * Returns the registration identifier of the {@link OAuth2AuthorizedClient Authorized Client}. + * + * @return the registration identifier of the Authorized Client. + */ public String getAuthorizedClientRegistrationId() { return this.authorizedClientRegistrationId; } diff --git a/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/authentication/OAuth2LoginAuthenticationProvider.java b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/authentication/OAuth2LoginAuthenticationProvider.java index 2c63904729..ab453f7c59 100644 --- a/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/authentication/OAuth2LoginAuthenticationProvider.java +++ b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/authentication/OAuth2LoginAuthenticationProvider.java @@ -36,16 +36,18 @@ import org.springframework.util.Assert; import java.util.Collection; /** - * An implementation of an {@link AuthenticationProvider} for OAuth 2.0 Login, - * which leverages the OAuth 2.0 Authorization Code Grant Flow. + * An implementation of an {@link AuthenticationProvider} for OAuth 2.0 Login, + * which leverages the OAuth 2.0 Authorization Code Grant Flow. * * This {@link AuthenticationProvider} is responsible for authenticating - * an Authorization Code credential with the Authorization Server's Token Endpoint - * and if valid, exchanging it for an Access Token credential. + * an Authorization Code credential with the Authorization Server's Token Endpoint + * and if valid, exchanging it for an Access Token credential. *

- * It will also obtain the user attributes of the End-User (Resource Owner) - * from the UserInfo Endpoint using an {@link OAuth2UserService} - * which will create a Principal in the form of an {@link OAuth2User}. + * It will also obtain the user attributes of the End-User (Resource Owner) + * from the UserInfo Endpoint using an {@link OAuth2UserService}, + * which will create a {@code Principal} in the form of an {@link OAuth2User}. + * The {@code OAuth2User} is then associated to the {@link OAuth2LoginAuthenticationToken} + * to complete the authentication. * * @author Joe Grandja * @since 5.0 @@ -64,6 +66,12 @@ public class OAuth2LoginAuthenticationProvider implements AuthenticationProvider private final OAuth2UserService userService; private GrantedAuthoritiesMapper authoritiesMapper = (authorities -> authorities); + /** + * Constructs an {@code OAuth2LoginAuthenticationProvider} using the provided parameters. + * + * @param accessTokenResponseClient the client used for requesting the access token credential from the Token Endpoint + * @param userService the service used for obtaining the user attributes of the End-User from the UserInfo Endpoint + */ public OAuth2LoginAuthenticationProvider( OAuth2AccessTokenResponseClient accessTokenResponseClient, OAuth2UserService userService) { @@ -134,6 +142,12 @@ public class OAuth2LoginAuthenticationProvider implements AuthenticationProvider return authenticationResult; } + /** + * Sets the {@link GrantedAuthoritiesMapper} used for mapping {@link OAuth2User#getAuthorities()} + * to a new set of authorities which will be associated to the {@link OAuth2LoginAuthenticationToken}. + * + * @param authoritiesMapper the {@link GrantedAuthoritiesMapper} used for mapping the user's authorities + */ public final void setAuthoritiesMapper(GrantedAuthoritiesMapper authoritiesMapper) { Assert.notNull(authoritiesMapper, "authoritiesMapper cannot be null"); this.authoritiesMapper = authoritiesMapper; diff --git a/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/authentication/OAuth2LoginAuthenticationToken.java b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/authentication/OAuth2LoginAuthenticationToken.java index f20e3c1856..0709ac7cd1 100644 --- a/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/authentication/OAuth2LoginAuthenticationToken.java +++ b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/authentication/OAuth2LoginAuthenticationToken.java @@ -28,8 +28,8 @@ import java.util.Collection; import java.util.Collections; /** - * An {@link AbstractAuthenticationToken} for OAuth 2.0 Login, - * which leverages the OAuth 2.0 Authorization Code Grant Flow. + * An {@link AbstractAuthenticationToken} for OAuth 2.0 Login, + * which leverages the OAuth 2.0 Authorization Code Grant Flow. * * @author Joe Grandja * @since 5.0 @@ -50,8 +50,8 @@ public class OAuth2LoginAuthenticationToken extends AbstractAuthenticationToken /** * This constructor should be used when the Authorization Request/Response is complete. * - * @param clientRegistration - * @param authorizationExchange + * @param clientRegistration the client registration + * @param authorizationExchange the authorization exchange */ public OAuth2LoginAuthenticationToken(ClientRegistration clientRegistration, OAuth2AuthorizationExchange authorizationExchange) { @@ -69,11 +69,11 @@ public class OAuth2LoginAuthenticationToken extends AbstractAuthenticationToken * which indicates that the Authorization Code Grant flow has fully completed * and OAuth 2.0 Login has been achieved. * - * @param clientRegistration - * @param authorizationExchange - * @param principal - * @param authorities - * @param accessToken + * @param clientRegistration the client registration + * @param authorizationExchange the authorization exchange + * @param principal the user {@code Principal} registered with the OAuth 2.0 Provider + * @param authorities the authorities granted to the user + * @param accessToken the access token credential */ public OAuth2LoginAuthenticationToken(ClientRegistration clientRegistration, OAuth2AuthorizationExchange authorizationExchange, @@ -102,14 +102,29 @@ public class OAuth2LoginAuthenticationToken extends AbstractAuthenticationToken return ""; } + /** + * Returns the {@link ClientRegistration client registration}. + * + * @return the {@link ClientRegistration} + */ public ClientRegistration getClientRegistration() { return this.clientRegistration; } + /** + * Returns the {@link OAuth2AuthorizationExchange authorization exchange}. + * + * @return the {@link OAuth2AuthorizationExchange} + */ public OAuth2AuthorizationExchange getAuthorizationExchange() { return this.authorizationExchange; } + /** + * Returns the {@link OAuth2AccessToken access token}. + * + * @return the {@link OAuth2AccessToken} + */ public OAuth2AccessToken getAccessToken() { return this.accessToken; } diff --git a/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/authentication/package-info.java b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/authentication/package-info.java index 200fd1465f..e6a0c7f236 100644 --- a/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/authentication/package-info.java +++ b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/authentication/package-info.java @@ -14,7 +14,7 @@ * limitations under the License. */ /** - * Support classes/interfaces for authenticating an end-user - * with an authorization server using a specific authorization grant flow. + * Support classes and interfaces for authenticating and authorizing a client + * with an OAuth 2.0 Authorization Server using a specific authorization grant flow. */ package org.springframework.security.oauth2.client.authentication; diff --git a/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/endpoint/AbstractOAuth2AuthorizationGrantRequest.java b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/endpoint/AbstractOAuth2AuthorizationGrantRequest.java index fe61579eb5..c3a6e862fe 100644 --- a/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/endpoint/AbstractOAuth2AuthorizationGrantRequest.java +++ b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/endpoint/AbstractOAuth2AuthorizationGrantRequest.java @@ -19,9 +19,9 @@ import org.springframework.security.oauth2.core.AuthorizationGrantType; import org.springframework.util.Assert; /** - * Base implementation of an OAuth 2.0 Authorization Grant request - * that holds an authorization grant credential and is used when - * initiating a HTTP request to the Authorization Server's Token Endpoint. + * Base implementation of an OAuth 2.0 Authorization Grant request + * that holds an authorization grant credential and is used when + * initiating a request to the Authorization Server's Token Endpoint. * * @author Joe Grandja * @since 5.0 @@ -31,11 +31,21 @@ import org.springframework.util.Assert; public abstract class AbstractOAuth2AuthorizationGrantRequest { private final AuthorizationGrantType authorizationGrantType; + /** + * Sub-class constructor. + * + * @param authorizationGrantType the authorization grant type + */ protected AbstractOAuth2AuthorizationGrantRequest(AuthorizationGrantType authorizationGrantType) { Assert.notNull(authorizationGrantType, "authorizationGrantType cannot be null"); this.authorizationGrantType = authorizationGrantType; } + /** + * Returns the authorization grant type. + * + * @return the authorization grant type + */ public AuthorizationGrantType getGrantType() { return this.authorizationGrantType; } diff --git a/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/endpoint/NimbusAuthorizationCodeTokenResponseClient.java b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/endpoint/NimbusAuthorizationCodeTokenResponseClient.java index 75539caf3f..ba791b7316 100644 --- a/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/endpoint/NimbusAuthorizationCodeTokenResponseClient.java +++ b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/endpoint/NimbusAuthorizationCodeTokenResponseClient.java @@ -48,12 +48,12 @@ import java.util.Map; import java.util.Set; /** - * An implementation of an {@link OAuth2AccessTokenResponseClient} that "exchanges" - * an Authorization Code credential for an Access Token credential - * at the Authorization Server's Token Endpoint. + * An implementation of an {@link OAuth2AccessTokenResponseClient} that "exchanges" + * an authorization code credential for an access token credential + * at the Authorization Server's Token Endpoint. * *

- * NOTE: This implementation uses the Nimbus OAuth 2.0 SDK internally. + * NOTE: This implementation uses the Nimbus OAuth 2.0 SDK internally. * * @author Joe Grandja * @since 5.0 diff --git a/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/endpoint/OAuth2AccessTokenResponseClient.java b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/endpoint/OAuth2AccessTokenResponseClient.java index 75277834c5..23fb503682 100644 --- a/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/endpoint/OAuth2AccessTokenResponseClient.java +++ b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/endpoint/OAuth2AccessTokenResponseClient.java @@ -21,9 +21,9 @@ import org.springframework.security.oauth2.core.OAuth2AuthenticationException; import org.springframework.security.oauth2.core.endpoint.OAuth2AccessTokenResponse; /** - * A strategy for "exchanging" an Authorization Grant credential - * (e.g. an Authorization Code) for an Access Token credential - * at the Authorization Server's Token Endpoint. + * A strategy for "exchanging" an authorization grant credential + * (e.g. an Authorization Code) for an access token credential + * at the Authorization Server's Token Endpoint. * * @author Joe Grandja * @since 5.0 @@ -36,6 +36,14 @@ import org.springframework.security.oauth2.core.endpoint.OAuth2AccessTokenRespon */ public interface OAuth2AccessTokenResponseClient { + /** + * Exchanges the authorization grant credential, provided in the authorization grant request, + * for an access token credential at the Authorization Server's Token Endpoint. + * + * @param authorizationGrantRequest the authorization grant request that contains the authorization grant credential + * @return an {@link OAuth2AccessTokenResponse} that contains the {@link OAuth2AccessTokenResponse#getAccessToken() access token} credential + * @throws OAuth2AuthenticationException if an error occurs while attempting to exchange for the access token credential + */ OAuth2AccessTokenResponse getTokenResponse(T authorizationGrantRequest) throws OAuth2AuthenticationException; } diff --git a/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/endpoint/OAuth2AuthorizationCodeGrantRequest.java b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/endpoint/OAuth2AuthorizationCodeGrantRequest.java index 3423894078..0cbd4586b8 100644 --- a/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/endpoint/OAuth2AuthorizationCodeGrantRequest.java +++ b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/endpoint/OAuth2AuthorizationCodeGrantRequest.java @@ -21,8 +21,8 @@ import org.springframework.security.oauth2.core.endpoint.OAuth2AuthorizationExch import org.springframework.util.Assert; /** - * An OAuth 2.0 Authorization Code Grant request that holds an Authorization Code credential, - * which was granted by the Resource Owner to the specified {@link #getClientRegistration() Client}. + * An OAuth 2.0 Authorization Code Grant request that holds an Authorization Code credential, + * which was granted by the Resource Owner to the {@link #getClientRegistration() Client}. * * @author Joe Grandja * @since 5.0 @@ -35,6 +35,12 @@ public class OAuth2AuthorizationCodeGrantRequest extends AbstractOAuth2Authoriza private final ClientRegistration clientRegistration; private final OAuth2AuthorizationExchange authorizationExchange; + /** + * Constructs an {@code OAuth2AuthorizationCodeGrantRequest} using the provided parameters. + * + * @param clientRegistration the client registration + * @param authorizationExchange the authorization exchange + */ public OAuth2AuthorizationCodeGrantRequest(ClientRegistration clientRegistration, OAuth2AuthorizationExchange authorizationExchange) { super(AuthorizationGrantType.AUTHORIZATION_CODE); @@ -44,10 +50,20 @@ public class OAuth2AuthorizationCodeGrantRequest extends AbstractOAuth2Authoriza this.authorizationExchange = authorizationExchange; } + /** + * Returns the {@link ClientRegistration client registration}. + * + * @return the {@link ClientRegistration} + */ public ClientRegistration getClientRegistration() { return this.clientRegistration; } + /** + * Returns the {@link OAuth2AuthorizationExchange authorization exchange}. + * + * @return the {@link OAuth2AuthorizationExchange} + */ public OAuth2AuthorizationExchange getAuthorizationExchange() { return this.authorizationExchange; } diff --git a/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/endpoint/package-info.java b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/endpoint/package-info.java new file mode 100644 index 0000000000..c2e1f8c5f7 --- /dev/null +++ b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/endpoint/package-info.java @@ -0,0 +1,20 @@ +/* + * Copyright 2002-2017 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 + * + * http://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. + */ +/** + * Classes and interfaces providing support to the client + * for initiating requests to the Authorization Server's Protocol Endpoints. + */ +package org.springframework.security.oauth2.client.endpoint; diff --git a/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/oidc/authentication/OidcAuthorizationCodeAuthenticationProvider.java b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/oidc/authentication/OidcAuthorizationCodeAuthenticationProvider.java index 736d5637af..33f2be8840 100644 --- a/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/oidc/authentication/OidcAuthorizationCodeAuthenticationProvider.java +++ b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/oidc/authentication/OidcAuthorizationCodeAuthenticationProvider.java @@ -53,15 +53,17 @@ import java.util.concurrent.ConcurrentHashMap; /** * An implementation of an {@link AuthenticationProvider} - * for the OpenID Connect Core 1.0 Authorization Code Grant Flow. + * for the OpenID Connect Core 1.0 Authorization Code Grant Flow. *

* This {@link AuthenticationProvider} is responsible for authenticating - * an Authorization Code credential with the Authorization Server's Token Endpoint - * and if valid, exchanging it for an Access Token credential. + * an Authorization Code credential with the Authorization Server's Token Endpoint + * and if valid, exchanging it for an Access Token credential. *

- * It will also obtain the user attributes of the End-User (Resource Owner) - * from the UserInfo Endpoint using an {@link OAuth2UserService} - * which will create a Principal in the form of an {@link OidcUser}. + * It will also obtain the user attributes of the End-User (Resource Owner) + * from the UserInfo Endpoint using an {@link OAuth2UserService}, + * which will create a {@code Principal} in the form of an {@link OidcUser}. + * The {@code OidcUser} is then associated to the {@link OAuth2LoginAuthenticationToken} + * to complete the authentication. * * @author Joe Grandja * @since 5.0 @@ -83,6 +85,12 @@ public class OidcAuthorizationCodeAuthenticationProvider implements Authenticati private final Map jwtDecoders = new ConcurrentHashMap<>(); private GrantedAuthoritiesMapper authoritiesMapper = (authorities -> authorities); + /** + * Constructs an {@code OidcAuthorizationCodeAuthenticationProvider} using the provided parameters. + * + * @param accessTokenResponseClient the client used for requesting the access token credential from the Token Endpoint + * @param userService the service used for obtaining the user attributes of the End-User from the UserInfo Endpoint + */ public OidcAuthorizationCodeAuthenticationProvider( OAuth2AccessTokenResponseClient accessTokenResponseClient, OAuth2UserService userService) { @@ -169,6 +177,12 @@ public class OidcAuthorizationCodeAuthenticationProvider implements Authenticati return authenticationResult; } + /** + * Sets the {@link GrantedAuthoritiesMapper} used for mapping {@link OidcUser#getAuthorities()}} + * to a new set of authorities which will be associated to the {@link OAuth2LoginAuthenticationToken}. + * + * @param authoritiesMapper the {@link GrantedAuthoritiesMapper} used for mapping the user's authorities + */ public final void setAuthoritiesMapper(GrantedAuthoritiesMapper authoritiesMapper) { Assert.notNull(authoritiesMapper, "authoritiesMapper cannot be null"); this.authoritiesMapper = authoritiesMapper; diff --git a/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/oidc/authentication/package-info.java b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/oidc/authentication/package-info.java new file mode 100644 index 0000000000..b570350c9f --- /dev/null +++ b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/oidc/authentication/package-info.java @@ -0,0 +1,20 @@ +/* + * Copyright 2002-2017 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 + * + * http://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. + */ +/** + * Support classes and interfaces for authenticating and authorizing a client + * with an OpenID Connect 1.0 Provider using a specific authorization grant flow. + */ +package org.springframework.security.oauth2.client.oidc.authentication; diff --git a/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/oidc/userinfo/OidcUserRequest.java b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/oidc/userinfo/OidcUserRequest.java index 992d0950aa..201ba577e2 100644 --- a/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/oidc/userinfo/OidcUserRequest.java +++ b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/oidc/userinfo/OidcUserRequest.java @@ -23,7 +23,7 @@ import org.springframework.util.Assert; /** * Represents a request the {@link OidcUserService} uses - * when initiating a HTTP request to the UserInfo Endpoint. + * when initiating a request to the UserInfo Endpoint. * * @author Joe Grandja * @since 5.0 @@ -35,6 +35,13 @@ import org.springframework.util.Assert; public class OidcUserRequest extends OAuth2UserRequest { private final OidcIdToken idToken; + /** + * Constructs an {@code OidcUserRequest} using the provided parameters. + * + * @param clientRegistration the client registration + * @param accessToken the access token credential + * @param idToken the ID Token + */ public OidcUserRequest(ClientRegistration clientRegistration, OAuth2AccessToken accessToken, OidcIdToken idToken) { @@ -43,6 +50,11 @@ public class OidcUserRequest extends OAuth2UserRequest { this.idToken = idToken; } + /** + * Returns the {@link OidcIdToken ID Token} containing claims about the user. + * + * @return the {@link OidcIdToken} containing claims about the user. + */ public OidcIdToken getIdToken() { return this.idToken; } diff --git a/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/oidc/userinfo/OidcUserService.java b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/oidc/userinfo/OidcUserService.java index adc0513b62..e354608c3d 100644 --- a/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/oidc/userinfo/OidcUserService.java +++ b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/oidc/userinfo/OidcUserService.java @@ -35,7 +35,7 @@ import java.util.Map; import java.util.Set; /** - * An implementation of an {@link OAuth2UserService} that supports OpenID Connect 1.0 Provider's. + * An implementation of an {@link OAuth2UserService} that supports OpenID Connect 1.0 Provider's. * * @author Joe Grandja * @since 5.0 diff --git a/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/oidc/userinfo/package-info.java b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/oidc/userinfo/package-info.java new file mode 100644 index 0000000000..09b793e808 --- /dev/null +++ b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/oidc/userinfo/package-info.java @@ -0,0 +1,20 @@ +/* + * Copyright 2002-2017 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 + * + * http://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. + */ +/** + * Classes and interfaces providing support to the client for initiating requests + * to the OpenID Connect 1.0 Provider's UserInfo Endpoint. + */ +package org.springframework.security.oauth2.client.oidc.userinfo; diff --git a/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/package-info.java b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/package-info.java new file mode 100644 index 0000000000..25eb790dcc --- /dev/null +++ b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/package-info.java @@ -0,0 +1,19 @@ +/* + * Copyright 2002-2017 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 + * + * http://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. + */ +/** + * Core classes and interfaces providing support for OAuth 2.0 Client. + */ +package org.springframework.security.oauth2.client; diff --git a/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/registration/ClientRegistration.java b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/registration/ClientRegistration.java index 94718ada26..137b9e696f 100644 --- a/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/registration/ClientRegistration.java +++ b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/registration/ClientRegistration.java @@ -26,7 +26,7 @@ import java.util.LinkedHashSet; import java.util.Set; /** - * A representation of a client registration with an OAuth 2.0 / OpenID Connect 1.0 Authorization Server. + * A representation of a client registration with an OAuth 2.0 or OpenID Connect 1.0 Provider. * * @author Joe Grandja * @since 5.0 @@ -46,38 +46,84 @@ public final class ClientRegistration { private ClientRegistration() { } + /** + * Returns the identifier for the registration. + * + * @return the identifier for the registration + */ public String getRegistrationId() { return this.registrationId; } + /** + * Returns the client identifier. + * + * @return the client identifier + */ public String getClientId() { return this.clientId; } + /** + * Returns the client secret. + * + * @return the client secret + */ public String getClientSecret() { return this.clientSecret; } + /** + * Returns the {@link ClientAuthenticationMethod authentication method} used + * when authenticating the client with the authorization server. + * + * @return the {@link ClientAuthenticationMethod} + */ public ClientAuthenticationMethod getClientAuthenticationMethod() { return this.clientAuthenticationMethod; } + /** + * Returns the {@link AuthorizationGrantType authorization grant type} used for the client. + * + * @return the {@link AuthorizationGrantType} + */ public AuthorizationGrantType getAuthorizationGrantType() { return this.authorizationGrantType; } + /** + * Returns the uri (or uri template) for the redirection endpoint. + * + * @return the uri for the redirection endpoint + */ public String getRedirectUriTemplate() { return this.redirectUriTemplate; } + /** + * Returns the scope(s) used for the client. + * + * @return the {@code Set} of scope(s) + */ public Set getScopes() { return this.scopes; } + /** + * Returns the details of the provider. + * + * @return the {@link ProviderDetails} + */ public ProviderDetails getProviderDetails() { return this.providerDetails; } + /** + * Returns the logical name of the client or registration. + * + * @return the client or registration name + */ public String getClientName() { return this.clientName; } @@ -97,6 +143,9 @@ public final class ClientRegistration { + '\'' + '}'; } + /** + * Details of the Provider. + */ public class ProviderDetails { private String authorizationUri; private String tokenUri; @@ -106,22 +155,45 @@ public final class ClientRegistration { private ProviderDetails() { } + /** + * Returns the uri for the authorization endpoint. + * + * @return the uri for the authorization endpoint + */ public String getAuthorizationUri() { return this.authorizationUri; } + /** + * Returns the uri for the token endpoint. + * + * @return the uri for the token endpoint + */ public String getTokenUri() { return this.tokenUri; } + /** + * Returns the details of the {@link UserInfoEndpoint UserInfo Endpoint}. + * + * @return the {@link UserInfoEndpoint} + */ public UserInfoEndpoint getUserInfoEndpoint() { return this.userInfoEndpoint; } + /** + * Returns the uri for the JSON Web Key (JWK) Set endpoint. + * + * @return the uri for the JSON Web Key (JWK) Set endpoint + */ public String getJwkSetUri() { return this.jwkSetUri; } + /** + * Details of the UserInfo Endpoint. + */ public class UserInfoEndpoint { private String uri; private String userNameAttributeName; @@ -129,21 +201,40 @@ public final class ClientRegistration { private UserInfoEndpoint() { } + /** + * Returns the uri for the user info endpoint. + * + * @return the uri for the user info endpoint + */ public String getUri() { return this.uri; } + /** + * Returns the attribute name used to access the user's name from the user info response. + * + * @return the attribute name used to access the user's name from the user info response + */ public String getUserNameAttributeName() { return this.userNameAttributeName; } } } + /** + * Returns a new {@link Builder}, initialized with the provided registration identifier. + * + * @param registrationId the identifier for the registration + * @return the {@link Builder} + */ public static Builder withRegistrationId(String registrationId) { Assert.hasText(registrationId, "registrationId cannot be empty"); return new Builder(registrationId); } + /** + * A builder for {@link ClientRegistration}. + */ public static class Builder { private String registrationId; private String clientId; @@ -163,31 +254,68 @@ public final class ClientRegistration { this.registrationId = registrationId; } + /** + * Sets the client identifier. + * + * @param clientId the client identifier + * @return the {@link Builder} + */ public Builder clientId(String clientId) { this.clientId = clientId; return this; } + /** + * Sets the client secret. + * + * @param clientSecret the client secret + * @return the {@link Builder} + */ public Builder clientSecret(String clientSecret) { this.clientSecret = clientSecret; return this; } + /** + * Sets the {@link ClientAuthenticationMethod authentication method} used + * when authenticating the client with the authorization server. + * + * @param clientAuthenticationMethod the authentication method used for the client + * @return the {@link Builder} + */ public Builder clientAuthenticationMethod(ClientAuthenticationMethod clientAuthenticationMethod) { this.clientAuthenticationMethod = clientAuthenticationMethod; return this; } + /** + * Sets the {@link AuthorizationGrantType authorization grant type} used for the client. + * + * @param authorizationGrantType the authorization grant type used for the client + * @return the {@link Builder} + */ public Builder authorizationGrantType(AuthorizationGrantType authorizationGrantType) { this.authorizationGrantType = authorizationGrantType; return this; } + /** + * Sets the uri (or uri template) for the redirection endpoint. + * + * @param redirectUriTemplate the uri for the redirection endpoint + * @return the {@link Builder} + */ public Builder redirectUriTemplate(String redirectUriTemplate) { this.redirectUriTemplate = redirectUriTemplate; return this; } + /** + * Sets the scope(s) used for the client. + * + * @param scope the scope(s) used for the client + * @return the {@link Builder} + */ public Builder scope(String... scope) { if (scope != null && scope.length > 0) { this.scopes = Collections.unmodifiableSet( @@ -196,36 +324,77 @@ public final class ClientRegistration { return this; } + /** + * Sets the uri for the authorization endpoint. + * + * @param authorizationUri the uri for the authorization endpoint + * @return the {@link Builder} + */ public Builder authorizationUri(String authorizationUri) { this.authorizationUri = authorizationUri; return this; } + /** + * Sets the uri for the token endpoint. + * + * @param tokenUri the uri for the token endpoint + * @return the {@link Builder} + */ public Builder tokenUri(String tokenUri) { this.tokenUri = tokenUri; return this; } + /** + * Sets the uri for the user info endpoint. + * + * @param userInfoUri the uri for the user info endpoint + * @return the {@link Builder} + */ public Builder userInfoUri(String userInfoUri) { this.userInfoUri = userInfoUri; return this; } + /** + * Sets the attribute name used to access the user's name from the user info response. + * + * @param userNameAttributeName the attribute name used to access the user's name from the user info response + * @return the {@link Builder} + */ public Builder userNameAttributeName(String userNameAttributeName) { this.userNameAttributeName = userNameAttributeName; return this; } + /** + * Sets the uri for the JSON Web Key (JWK) Set endpoint. + * + * @param jwkSetUri the uri for the JSON Web Key (JWK) Set endpoint + * @return the {@link Builder} + */ public Builder jwkSetUri(String jwkSetUri) { this.jwkSetUri = jwkSetUri; return this; } + /** + * Sets the logical name of the client or registration. + * + * @param clientName the client or registration name + * @return the {@link Builder} + */ public Builder clientName(String clientName) { this.clientName = clientName; return this; } + /** + * Builds a new {@link ClientRegistration}. + * + * @return a {@link ClientRegistration} + */ public ClientRegistration build() { Assert.notNull(this.authorizationGrantType, "authorizationGrantType cannot be null"); if (AuthorizationGrantType.IMPLICIT.equals(this.authorizationGrantType)) { diff --git a/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/registration/ClientRegistrationRepository.java b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/registration/ClientRegistrationRepository.java index 1350a10e60..2beef6fdc7 100644 --- a/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/registration/ClientRegistrationRepository.java +++ b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/registration/ClientRegistrationRepository.java @@ -16,14 +16,14 @@ package org.springframework.security.oauth2.client.registration; /** - * A repository for OAuth 2.0 / OpenID Connect 1.0 {@link ClientRegistration}'s. + * A repository for OAuth 2.0 / OpenID Connect 1.0 {@link ClientRegistration}(s). * *

- * NOTE: The client registration information is ultimately stored and owned - * by the associated Authorization Server. + * NOTE: Client registration information is ultimately stored and owned + * by the associated Authorization Server. * Therefore, this repository provides the capability to store a sub-set copy * of the primary client registration information - * externally from the Authorization Server. + * externally from the Authorization Server. * * @author Joe Grandja * @since 5.0 @@ -31,6 +31,12 @@ package org.springframework.security.oauth2.client.registration; */ public interface ClientRegistrationRepository { + /** + * Returns the client registration identified by the provided {@code registrationId}, or {@code null} if not found. + * + * @param registrationId the registration identifier + * @return the {@link ClientRegistration} if found, otherwise {@code null} + */ ClientRegistration findByRegistrationId(String registrationId); } diff --git a/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/registration/InMemoryClientRegistrationRepository.java b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/registration/InMemoryClientRegistrationRepository.java index dfbae7c15b..fa810e432b 100644 --- a/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/registration/InMemoryClientRegistrationRepository.java +++ b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/registration/InMemoryClientRegistrationRepository.java @@ -30,7 +30,7 @@ import static java.util.stream.Collectors.collectingAndThen; import static java.util.stream.Collectors.toConcurrentMap; /** - * A {@link ClientRegistrationRepository} that stores {@link ClientRegistration}(s) in-memory. + * A {@link ClientRegistrationRepository} that stores {@link ClientRegistration}(s) in-memory. * * @author Joe Grandja * @author Rob Winch @@ -41,10 +41,20 @@ import static java.util.stream.Collectors.toConcurrentMap; public final class InMemoryClientRegistrationRepository implements ClientRegistrationRepository, Iterable { private final Map registrations; + /** + * Constructs an {@code InMemoryClientRegistrationRepository} using the provided parameters. + * + * @param registrations the client registration(s) + */ public InMemoryClientRegistrationRepository(ClientRegistration... registrations) { this(Arrays.asList(registrations)); } + /** + * Constructs an {@code InMemoryClientRegistrationRepository} using the provided parameters. + * + * @param registrations the client registration(s) + */ public InMemoryClientRegistrationRepository(List registrations) { Assert.notEmpty(registrations, "registrations cannot be empty"); Collector> collector = @@ -59,6 +69,11 @@ public final class InMemoryClientRegistrationRepository implements ClientRegistr return this.registrations.get(registrationId); } + /** + * Returns an {@code Iterator} of {@link ClientRegistration}. + * + * @return an {@code Iterator} + */ @Override public Iterator iterator() { return this.registrations.values().iterator(); diff --git a/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/registration/package-info.java b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/registration/package-info.java index d8fb8470d3..858241880e 100644 --- a/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/registration/package-info.java +++ b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/registration/package-info.java @@ -14,6 +14,6 @@ * limitations under the License. */ /** - * Classes and interfaces related to {@link org.springframework.security.oauth2.client.registration.ClientRegistration}. + * Classes and interfaces that provide support for {@link org.springframework.security.oauth2.client.registration.ClientRegistration}. */ package org.springframework.security.oauth2.client.registration; diff --git a/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/userinfo/CustomUserTypesOAuth2UserService.java b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/userinfo/CustomUserTypesOAuth2UserService.java index 67e330afbe..7322fa36f4 100644 --- a/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/userinfo/CustomUserTypesOAuth2UserService.java +++ b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/userinfo/CustomUserTypesOAuth2UserService.java @@ -28,7 +28,7 @@ import java.util.Map; * An implementation of an {@link OAuth2UserService} that supports custom {@link OAuth2User} types. *

* The custom user type(s) is supplied via the constructor, - * using a Map of {@link OAuth2User} type keyed by String, + * using a {@code Map} of {@link OAuth2User} type(s) keyed by {@code String}, * which represents the {@link ClientRegistration#getRegistrationId() Registration Id} of the Client. * * @author Joe Grandja @@ -42,6 +42,11 @@ public class CustomUserTypesOAuth2UserService implements OAuth2UserService> customUserTypes; private NimbusUserInfoResponseClient userInfoResponseClient = new NimbusUserInfoResponseClient(); + /** + * Constructs a {@code CustomUserTypesOAuth2UserService} using the provided parameters. + * + * @param customUserTypes a {@code Map} of {@link OAuth2User} type(s) keyed by {@link ClientRegistration#getRegistrationId() Registration Id} + */ public CustomUserTypesOAuth2UserService(Map> customUserTypes) { Assert.notEmpty(customUserTypes, "customUserTypes cannot be empty"); this.customUserTypes = Collections.unmodifiableMap(new LinkedHashMap<>(customUserTypes)); diff --git a/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/userinfo/DefaultOAuth2UserService.java b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/userinfo/DefaultOAuth2UserService.java index a74026f688..54b938868c 100644 --- a/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/userinfo/DefaultOAuth2UserService.java +++ b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/userinfo/DefaultOAuth2UserService.java @@ -30,13 +30,13 @@ import java.util.Map; import java.util.Set; /** - * An implementation of an {@link OAuth2UserService} that supports standard OAuth 2.0 Provider's. + * An implementation of an {@link OAuth2UserService} that supports standard OAuth 2.0 Provider's. *

- * For standard OAuth 2.0 Provider's, the attribute name (from the UserInfo Response) - * for the "user's name" is required and therefore must be supplied via - * {@link org.springframework.security.oauth2.client.registration.ClientRegistration.ProviderDetails.UserInfoEndpoint#getUserNameAttributeName()}. + * For standard OAuth 2.0 Provider's, the attribute name used to access the user's name + * from the UserInfo response is required and therefore must be available via + * {@link org.springframework.security.oauth2.client.registration.ClientRegistration.ProviderDetails.UserInfoEndpoint#getUserNameAttributeName() UserInfoEndpoint.getUserNameAttributeName()}. *

- * NOTE: Attribute names are not standardized between providers and therefore will vary. + * NOTE: Attribute names are not standardized between providers and therefore will vary. * Please consult the provider's API documentation for the set of supported user attribute names. * * @author Joe Grandja diff --git a/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/userinfo/DelegatingOAuth2UserService.java b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/userinfo/DelegatingOAuth2UserService.java index e495a4ee5b..3d7c1ce908 100644 --- a/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/userinfo/DelegatingOAuth2UserService.java +++ b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/userinfo/DelegatingOAuth2UserService.java @@ -26,11 +26,11 @@ import java.util.Objects; /** * An implementation of an {@link OAuth2UserService} that simply delegates - * to it's internal List of {@link OAuth2UserService}'s. + * to it's internal {@code List} of {@link OAuth2UserService}(s). *

* Each {@link OAuth2UserService} is given a chance to * {@link OAuth2UserService#loadUser(OAuth2UserRequest) load} an {@link OAuth2User} - * with the first non-null {@link OAuth2User} being returned. + * with the first {@code non-null} {@link OAuth2User} being returned. * * @author Joe Grandja * @since 5.0 @@ -38,12 +38,17 @@ import java.util.Objects; * @see OAuth2UserRequest * @see OAuth2User * - * @param The type of OAuth 2.0 User Request - * @param The type of OAuth 2.0 User + * @param The type of OAuth 2.0 User Request + * @param The type of OAuth 2.0 User */ public class DelegatingOAuth2UserService implements OAuth2UserService { private final List> userServices; + /** + * Constructs a {@code DelegatingOAuth2UserService} using the provided parameters. + * + * @param userServices a {@code List} of {@link OAuth2UserService}(s) + */ public DelegatingOAuth2UserService(List> userServices) { Assert.notEmpty(userServices, "userServices cannot be empty"); this.userServices = Collections.unmodifiableList(new ArrayList<>(userServices)); diff --git a/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/userinfo/OAuth2UserRequest.java b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/userinfo/OAuth2UserRequest.java index 038ae1e977..949fb7699b 100644 --- a/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/userinfo/OAuth2UserRequest.java +++ b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/userinfo/OAuth2UserRequest.java @@ -21,7 +21,7 @@ import org.springframework.util.Assert; /** * Represents a request the {@link OAuth2UserService} uses - * when initiating a HTTP request to the UserInfo Endpoint. + * when initiating a request to the UserInfo Endpoint. * * @author Joe Grandja * @since 5.0 @@ -33,6 +33,12 @@ public class OAuth2UserRequest { private final ClientRegistration clientRegistration; private final OAuth2AccessToken accessToken; + /** + * Constructs an {@code OAuth2UserRequest} using the provided parameters. + * + * @param clientRegistration the client registration + * @param accessToken the access token + */ public OAuth2UserRequest(ClientRegistration clientRegistration, OAuth2AccessToken accessToken) { Assert.notNull(clientRegistration, "clientRegistration cannot be null"); Assert.notNull(accessToken, "accessToken cannot be null"); @@ -40,10 +46,20 @@ public class OAuth2UserRequest { this.accessToken = accessToken; } + /** + * Returns the {@link ClientRegistration client registration}. + * + * @return the {@link ClientRegistration} + */ public ClientRegistration getClientRegistration() { return this.clientRegistration; } + /** + * Returns the {@link OAuth2AccessToken access token}. + * + * @return the {@link OAuth2AccessToken} + */ public OAuth2AccessToken getAccessToken() { return this.accessToken; } diff --git a/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/userinfo/OAuth2UserService.java b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/userinfo/OAuth2UserService.java index 8057568808..8cb0cbb3b7 100644 --- a/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/userinfo/OAuth2UserService.java +++ b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/userinfo/OAuth2UserService.java @@ -21,7 +21,7 @@ import org.springframework.security.oauth2.core.user.OAuth2User; /** * Implementations of this interface are responsible for obtaining the user attributes - * of the End-User (Resource Owner) from the UserInfo Endpoint + * of the End-User (Resource Owner) from the UserInfo Endpoint * using the {@link OAuth2UserRequest#getAccessToken() Access Token} * granted to the {@link OAuth2UserRequest#getClientRegistration() Client} * and returning an {@link AuthenticatedPrincipal} in the form of an {@link OAuth2User}. @@ -32,11 +32,18 @@ import org.springframework.security.oauth2.core.user.OAuth2User; * @see OAuth2User * @see AuthenticatedPrincipal * - * @param The type of OAuth 2.0 User Request - * @param The type of OAuth 2.0 User + * @param The type of OAuth 2.0 User Request + * @param The type of OAuth 2.0 User */ public interface OAuth2UserService { + /** + * Returns an {@link OAuth2User} after obtaining the user attributes of the End-User from the UserInfo Endpoint. + * + * @param userRequest the user request + * @return an {@link OAuth2User} + * @throws OAuth2AuthenticationException if an error occurs while attempting to obtain the user attributes from the UserInfo Endpoint + */ U loadUser(R userRequest) throws OAuth2AuthenticationException; } diff --git a/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/userinfo/package-info.java b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/userinfo/package-info.java index 0dcd38cc5c..8522031e0f 100644 --- a/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/userinfo/package-info.java +++ b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/userinfo/package-info.java @@ -14,6 +14,7 @@ * limitations under the License. */ /** - * Support classes and interfaces related to an OAuth 2.0 User. + * Classes and interfaces providing support to the client for initiating requests + * to the OAuth 2.0 Authorization Server's UserInfo Endpoint. */ package org.springframework.security.oauth2.client.userinfo; diff --git a/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/web/AuthorizationRequestRepository.java b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/web/AuthorizationRequestRepository.java index 03694e7307..9e316f0fa7 100644 --- a/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/web/AuthorizationRequestRepository.java +++ b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/web/AuthorizationRequestRepository.java @@ -25,25 +25,47 @@ import javax.servlet.http.HttpServletResponse; * of {@link OAuth2AuthorizationRequest} between requests. * *

- * Used by the {@link OAuth2AuthorizationRequestRedirectFilter} for persisting the Authorization Request + * Used by the {@link OAuth2AuthorizationRequestRedirectFilter} for persisting the Authorization Request * before it initiates the authorization code grant flow. * As well, used by the {@link OAuth2LoginAuthenticationFilter} for resolving - * the associated Authorization Request when handling the Authorization Response. + * the associated Authorization Request when handling the callback of the Authorization Response. * * @author Joe Grandja * @since 5.0 * @see OAuth2AuthorizationRequest * @see HttpSessionOAuth2AuthorizationRequestRepository * - * @param The type of OAuth 2.0 Authorization Request + * @param The type of OAuth 2.0 Authorization Request */ public interface AuthorizationRequestRepository { + /** + * Returns the {@link OAuth2AuthorizationRequest} associated to the provided {@code HttpServletRequest} + * or {@code null} if not available. + * + * @param request the {@code HttpServletRequest} + * @return the {@link OAuth2AuthorizationRequest} or {@code null} if not available + */ T loadAuthorizationRequest(HttpServletRequest request); + /** + * Persists the {@link OAuth2AuthorizationRequest} associating it to + * the provided {@code HttpServletRequest} and/or {@code HttpServletResponse}. + * + * @param authorizationRequest the {@link OAuth2AuthorizationRequest} + * @param request the {@code HttpServletRequest} + * @param response the {@code HttpServletResponse} + */ void saveAuthorizationRequest(T authorizationRequest, HttpServletRequest request, HttpServletResponse response); + /** + * Removes and returns the {@link OAuth2AuthorizationRequest} associated to the + * provided {@code HttpServletRequest} or if not available returns {@code null}. + * + * @param request the {@code HttpServletRequest} + * @return the removed {@link OAuth2AuthorizationRequest} or {@code null} if not available + */ T removeAuthorizationRequest(HttpServletRequest request); } diff --git a/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/web/HttpSessionOAuth2AuthorizationRequestRepository.java b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/web/HttpSessionOAuth2AuthorizationRequestRepository.java index 2d35fe4650..4019dba56e 100644 --- a/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/web/HttpSessionOAuth2AuthorizationRequestRepository.java +++ b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/web/HttpSessionOAuth2AuthorizationRequestRepository.java @@ -24,10 +24,11 @@ import javax.servlet.http.HttpSession; /** * An implementation of an {@link AuthorizationRequestRepository} that stores - * {@link OAuth2AuthorizationRequest} in the {@link HttpSession}. + * {@link OAuth2AuthorizationRequest} in the {@code HttpSession}. * * @author Joe Grandja * @since 5.0 + * @see AuthorizationRequestRepository * @see OAuth2AuthorizationRequest */ public final class HttpSessionOAuth2AuthorizationRequestRepository implements AuthorizationRequestRepository { diff --git a/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/web/OAuth2AuthorizationRequestRedirectFilter.java b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/web/OAuth2AuthorizationRequestRedirectFilter.java index 7535871489..4fea8b7acb 100644 --- a/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/web/OAuth2AuthorizationRequestRedirectFilter.java +++ b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/web/OAuth2AuthorizationRequestRedirectFilter.java @@ -41,15 +41,15 @@ import java.util.HashMap; import java.util.Map; /** - * This Filter initiates the authorization code grant or implicit grant flow - * by redirecting the end-user's user-agent to the authorization server's Authorization Endpoint. + * This {@code Filter} initiates the authorization code grant or implicit grant flow + * by redirecting the End-User's user-agent to the Authorization Server's Authorization Endpoint. * *

- * It builds the OAuth 2.0 Authorization Request, - * which is used as the redirect URI to the Authorization Endpoint. - * The redirect URI will include the client identifier, requested scope(s), state, + * It builds the OAuth 2.0 Authorization Request, + * which is used as the redirect {@code URI} to the Authorization Endpoint. + * The redirect {@code URI} will include the client identifier, requested scope(s), state, * response type, and a redirection URI which the authorization server will send the user-agent back to - * once access is granted (or denied) by the end-user (resource owner). + * once access is granted (or denied) by the End-User (Resource Owner). * * @author Joe Grandja * @author Rob Winch @@ -64,6 +64,9 @@ import java.util.Map; * @see Section 4.2.1 Authorization Request (Implicit) */ public class OAuth2AuthorizationRequestRedirectFilter extends OncePerRequestFilter { + /** + * The default base {@code URI} used for authorization requests. + */ public static final String DEFAULT_AUTHORIZATION_REQUEST_BASE_URI = "/oauth2/authorization"; private static final String REGISTRATION_ID_URI_VARIABLE_NAME = "registrationId"; private final AntPathRequestMatcher authorizationRequestMatcher; @@ -74,10 +77,21 @@ public class OAuth2AuthorizationRequestRedirectFilter extends OncePerRequestFilt private AuthorizationRequestRepository authorizationRequestRepository = new HttpSessionOAuth2AuthorizationRequestRepository(); + /** + * Constructs an {@code OAuth2AuthorizationRequestRedirectFilter} using the provided parameters. + * + * @param clientRegistrationRepository the repository of client registrations + */ public OAuth2AuthorizationRequestRedirectFilter(ClientRegistrationRepository clientRegistrationRepository) { this(clientRegistrationRepository, DEFAULT_AUTHORIZATION_REQUEST_BASE_URI); } + /** + * Constructs an {@code OAuth2AuthorizationRequestRedirectFilter} using the provided parameters. + * + * @param clientRegistrationRepository the repository of client registrations + * @param authorizationRequestBaseUri the base {@code URI} used for authorization requests + */ public OAuth2AuthorizationRequestRedirectFilter( ClientRegistrationRepository clientRegistrationRepository, String authorizationRequestBaseUri) { @@ -88,6 +102,11 @@ public class OAuth2AuthorizationRequestRedirectFilter extends OncePerRequestFilt this.clientRegistrationRepository = clientRegistrationRepository; } + /** + * Sets the repository used for storing {@link OAuth2AuthorizationRequest}'s. + * + * @param authorizationRequestRepository the repository used for storing {@link OAuth2AuthorizationRequest}'s + */ public final void setAuthorizationRequestRepository(AuthorizationRequestRepository authorizationRequestRepository) { Assert.notNull(authorizationRequestRepository, "authorizationRequestRepository cannot be null"); this.authorizationRequestRepository = authorizationRequestRepository; diff --git a/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/web/OAuth2AuthorizationRequestUriBuilder.java b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/web/OAuth2AuthorizationRequestUriBuilder.java index 0d52c35611..3a9635f9e9 100644 --- a/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/web/OAuth2AuthorizationRequestUriBuilder.java +++ b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/web/OAuth2AuthorizationRequestUriBuilder.java @@ -25,7 +25,7 @@ import java.net.URI; import java.util.Set; /** - * Uses a {@link UriComponentsBuilder} to construct the OAuth 2.0 Authorization Request. + * A {@code URI} builder for an OAuth 2.0 Authorization Request. * * @author Joe Grandja * @since 5.0 diff --git a/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/web/OAuth2LoginAuthenticationFilter.java b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/web/OAuth2LoginAuthenticationFilter.java index 0230a6b593..67da59488e 100644 --- a/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/web/OAuth2LoginAuthenticationFilter.java +++ b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/web/OAuth2LoginAuthenticationFilter.java @@ -33,6 +33,7 @@ import org.springframework.security.oauth2.core.endpoint.OAuth2AuthorizationRequ import org.springframework.security.oauth2.core.endpoint.OAuth2AuthorizationResponse; import org.springframework.security.oauth2.core.endpoint.OAuth2ParameterNames; import org.springframework.security.web.authentication.AbstractAuthenticationProcessingFilter; +import org.springframework.security.web.context.SecurityContextRepository; import org.springframework.util.Assert; import org.springframework.util.StringUtils; @@ -42,23 +43,35 @@ import javax.servlet.http.HttpServletResponse; import java.io.IOException; /** - * An implementation of an {@link AbstractAuthenticationProcessingFilter} that handles - * the processing of an OAuth 2.0 Authorization Response for the authorization code grant flow. + * An implementation of an {@link AbstractAuthenticationProcessingFilter} for OAuth 2.0 Login. * *

- * This Filter processes the Authorization Response as follows: + * This authentication {@code Filter} handles the processing of an OAuth 2.0 Authorization Response + * for the authorization code grant flow and delegates an {@link OAuth2LoginAuthenticationToken} + * to the {@link AuthenticationManager} to log in the End-User. + * + *

+ * The OAuth 2.0 Authorization Response is processed as follows: * *

* @@ -73,11 +86,15 @@ import java.io.IOException; * @see AuthorizationRequestRepository * @see OAuth2AuthorizationRequestRedirectFilter * @see ClientRegistrationRepository + * @see OAuth2AuthorizedClient * @see OAuth2AuthorizedClientService * @see Section 4.1 Authorization Code Grant * @see Section 4.1.2 Authorization Response */ public class OAuth2LoginAuthenticationFilter extends AbstractAuthenticationProcessingFilter { + /** + * The default {@code URI} where this {@code Filter} processes authentication requests. + */ public static final String DEFAULT_FILTER_PROCESSES_URI = "/login/oauth2/code/*"; private static final String AUTHORIZATION_REQUEST_NOT_FOUND_ERROR_CODE = "authorization_request_not_found"; private ClientRegistrationRepository clientRegistrationRepository; @@ -85,11 +102,24 @@ public class OAuth2LoginAuthenticationFilter extends AbstractAuthenticationProce private AuthorizationRequestRepository authorizationRequestRepository = new HttpSessionOAuth2AuthorizationRequestRepository(); + /** + * Constructs an {@code OAuth2LoginAuthenticationFilter} using the provided parameters. + * + * @param clientRegistrationRepository the repository of client registrations + * @param authorizedClientService the authorized client service + */ public OAuth2LoginAuthenticationFilter(ClientRegistrationRepository clientRegistrationRepository, OAuth2AuthorizedClientService authorizedClientService) { this(clientRegistrationRepository, authorizedClientService, DEFAULT_FILTER_PROCESSES_URI); } + /** + * Constructs an {@code OAuth2LoginAuthenticationFilter} using the provided parameters. + * + * @param clientRegistrationRepository the repository of client registrations + * @param authorizedClientService the authorized client service + * @param filterProcessesUrl the {@code URI} where this {@code Filter} will process the authentication requests + */ public OAuth2LoginAuthenticationFilter(ClientRegistrationRepository clientRegistrationRepository, OAuth2AuthorizedClientService authorizedClientService, String filterProcessesUrl) { @@ -143,6 +173,11 @@ public class OAuth2LoginAuthenticationFilter extends AbstractAuthenticationProce return oauth2Authentication; } + /** + * Sets the repository for stored {@link OAuth2AuthorizationRequest}'s. + * + * @param authorizationRequestRepository the repository for stored {@link OAuth2AuthorizationRequest}'s + */ public final void setAuthorizationRequestRepository(AuthorizationRequestRepository authorizationRequestRepository) { Assert.notNull(authorizationRequestRepository, "authorizationRequestRepository cannot be null"); this.authorizationRequestRepository = authorizationRequestRepository; diff --git a/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/web/package-info.java b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/web/package-info.java new file mode 100644 index 0000000000..c70316ecee --- /dev/null +++ b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/web/package-info.java @@ -0,0 +1,19 @@ +/* + * Copyright 2002-2017 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 + * + * http://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. + */ +/** + * OAuth 2.0 Client {@code Filter}'s and supporting classes and interfaces. + */ +package org.springframework.security.oauth2.client.web; diff --git a/oauth2/oauth2-core/src/main/java/org/springframework/security/oauth2/core/endpoint/OAuth2AuthorizationRequest.java b/oauth2/oauth2-core/src/main/java/org/springframework/security/oauth2/core/endpoint/OAuth2AuthorizationRequest.java index 2a2344af97..78eaac5598 100644 --- a/oauth2/oauth2-core/src/main/java/org/springframework/security/oauth2/core/endpoint/OAuth2AuthorizationRequest.java +++ b/oauth2/oauth2-core/src/main/java/org/springframework/security/oauth2/core/endpoint/OAuth2AuthorizationRequest.java @@ -91,9 +91,9 @@ public final class OAuth2AuthorizationRequest implements Serializable { } /** - * Returns the uri for the redirect endpoint. + * Returns the uri for the redirection endpoint. * - * @return the uri for the redirect endpoint + * @return the uri for the redirection endpoint */ public String getRedirectUri() { return this.redirectUri; @@ -190,9 +190,9 @@ public final class OAuth2AuthorizationRequest implements Serializable { } /** - * Sets the uri for the redirect endpoint. + * Sets the uri for the redirection endpoint. * - * @param redirectUri the uri for the redirect endpoint + * @param redirectUri the uri for the redirection endpoint * @return the {@link Builder} */ public Builder redirectUri(String redirectUri) {