Add javadoc for spring-security-oauth2-client

Fixes gh-4884

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)} <i>in-memory</i>.
+ * {@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<String, OAuth2AuthorizedClient> 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;

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 <i>&quot;Authorized Client&quot;</i>.
+ * A representation of an OAuth 2.0 &quot;Authorized Client&quot;.
  * <p>
- * A client is considered <i>&quot;authorized&quot;</i> when the End-User (Resource Owner)
+ * A client is considered &quot;authorized&quot; when the End-User (Resource Owner)
- * grants authorization to the Client to access its protected resources.
+ * has granted authorization to the client to access it's protected resources.
  * <p>
  * 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;
 	}

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
+ * of associating an {@link OAuth2AuthorizedClient#getAccessToken() Access Token} credential
- * {@link OAuth2AuthorizedClient#getClientRegistration() Client} and <i>Resource Owner</i>,
+ * 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 <T> a type of OAuth2AuthorizedClient
+	 * @return the {@link OAuth2AuthorizedClient} or {@code null} if not available
+	 */
 	<T extends OAuth2AuthorizedClient> 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);
 
 }

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 <i>OAuth 2.0</i> {@link Authentication}.
+ * that represents an OAuth 2.0 {@link Authentication}.
  * <p>
- * This {@link Authentication} associates an {@link OAuth2User} <code>Principal</code>
+ * 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
+ * which the End-User ({@code Principal}) granted authorization to
- * so that it can access its protected resource(s) at the <i>UserInfo Endpoint</i>.
+ * 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<? extends GrantedAuthority> 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;
 	}

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 <i>OAuth 2.0 Login</i>,
+ * An implementation of an {@link AuthenticationProvider} for OAuth 2.0 Login,
- * which leverages the <i>OAuth 2.0 Authorization Code Grant</i> Flow.
+ * which leverages the OAuth 2.0 Authorization Code Grant Flow.
  *
  * This {@link AuthenticationProvider} is responsible for authenticating
- * an <i>Authorization Code</i> credential with the Authorization Server's <i>Token Endpoint</i>
+ * an Authorization Code credential with the Authorization Server's Token Endpoint
- * and if valid, exchanging it for an <i>Access Token</i> credential.
+ * and if valid, exchanging it for an Access Token credential.
  * <p>
- * It will also obtain the user attributes of the <i>End-User</i> (Resource Owner)
+ * It will also obtain the user attributes of the End-User (Resource Owner)
- * from the <i>UserInfo Endpoint</i> using an {@link OAuth2UserService}
+ * from the UserInfo Endpoint using an {@link OAuth2UserService},
- * which will create a <code>Principal</code> in the form of an {@link OAuth2User}.
+ * 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<OAuth2UserRequest, OAuth2User> 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<OAuth2AuthorizationCodeGrantRequest> accessTokenResponseClient,
 		OAuth2UserService<OAuth2UserRequest, OAuth2User> 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;

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 <i>OAuth 2.0 Login</i>,
+ * An {@link AbstractAuthenticationToken} for OAuth 2.0 Login,
- * which leverages the <i>OAuth 2.0 Authorization Code Grant</i> Flow.
+ * 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 clientRegistration the client registration
-	 * @param authorizationExchange
+	 * @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 clientRegistration the client registration
-	 * @param authorizationExchange
+	 * @param authorizationExchange the authorization exchange
-	 * @param principal
+	 * @param principal the user {@code Principal} registered with the OAuth 2.0 Provider
-	 * @param authorities
+	 * @param authorities the authorities granted to the user
-	 * @param accessToken
+	 * @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;
 	}

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 <i>end-user</i>
+ * Support classes and interfaces for authenticating and authorizing a client
- * with an <i>authorization server</i> using a specific <i>authorization grant flow</i>.
+ * with an OAuth 2.0 Authorization Server using a specific authorization grant flow.
  */
 package org.springframework.security.oauth2.client.authentication;

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 <i>OAuth 2.0 Authorization Grant</i> request
+ * Base implementation of an OAuth 2.0 Authorization Grant request
- * that holds an <i>authorization grant</i> credential and is used when
+ * that holds an authorization grant credential and is used when
- * initiating a HTTP request to the Authorization Server's <i>Token Endpoint</i>.
+ * 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;
 	}

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 <i>&quot;exchanges&quot;</i>
+ * An implementation of an {@link OAuth2AccessTokenResponseClient} that &quot;exchanges&quot;
- * an <i>Authorization Code</i> credential for an <i>Access Token</i> credential
+ * an authorization code credential for an access token credential
- * at the Authorization Server's <i>Token Endpoint</i>.
+ * at the Authorization Server's Token Endpoint.
  *
  * <p>
- * <b>NOTE:</b> This implementation uses the <b>Nimbus OAuth 2.0 SDK</b> internally.
+ * <b>NOTE:</b> This implementation uses the Nimbus OAuth 2.0 SDK internally.
  *
  * @author Joe Grandja
  * @since 5.0

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 <i>&quot;exchanging&quot;</i> an <i>Authorization Grant</i> credential
+ * A strategy for &quot;exchanging&quot; an authorization grant credential
- * (e.g. an Authorization Code) for an <i>Access Token</i> credential
+ * (e.g. an Authorization Code) for an access token credential
- * at the Authorization Server's <i>Token Endpoint</i>.
+ * 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<T extends AbstractOAuth2AuthorizationGrantRequest>  {
 
+	/**
+	 * 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;
 
 }

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 <i>OAuth 2.0 Authorization Code Grant</i> request that holds an <i>Authorization Code</i> credential,
+ * An OAuth 2.0 Authorization Code Grant request that holds an Authorization Code credential,
- * which was granted by the <i>Resource Owner</i> to the specified {@link #getClientRegistration() Client}.
+ * 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;
 	}

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;

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 <i>OpenID Connect Core 1.0 Authorization Code Grant Flow</i>.
+ * for the OpenID Connect Core 1.0 Authorization Code Grant Flow.
  * <p>
  * This {@link AuthenticationProvider} is responsible for authenticating
- * an <i>Authorization Code</i> credential with the Authorization Server's <i>Token Endpoint</i>
+ * an Authorization Code credential with the Authorization Server's Token Endpoint
- * and if valid, exchanging it for an <i>Access Token</i> credential.
+ * and if valid, exchanging it for an Access Token credential.
  * <p>
- * It will also obtain the user attributes of the <i>End-User</i> (Resource Owner)
+ * It will also obtain the user attributes of the End-User (Resource Owner)
- * from the <i>UserInfo Endpoint</i> using an {@link OAuth2UserService}
+ * from the UserInfo Endpoint using an {@link OAuth2UserService},
- * which will create a <code>Principal</code> in the form of an {@link OidcUser}.
+ * 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<String, JwtDecoder> 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<OAuth2AuthorizationCodeGrantRequest> accessTokenResponseClient,
 		OAuth2UserService<OidcUserRequest, OidcUser> 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;

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;

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 <i>UserInfo Endpoint</i>.
+ * 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;
 	}

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 <i>OpenID Connect 1.0 Provider's</i>.
+ * An implementation of an {@link OAuth2UserService} that supports OpenID Connect 1.0 Provider's.
  *
  * @author Joe Grandja
  * @since 5.0

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;

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;

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 <i>Authorization Server</i>.
+ * 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<String> 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)) {

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).
  *
  * <p>
- * <b>NOTE:</b> The client registration information is ultimately stored and owned
+ * <b>NOTE:</b> Client registration information is ultimately stored and owned
- * by the associated <i>Authorization Server</i>.
+ * by the associated Authorization Server.
  * Therefore, this repository provides the capability to store a sub-set copy
  * of the <i>primary</i> client registration information
- * externally from the <i>Authorization Server</i>.
+ * 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);
 
 }

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) <i>in-memory</i>.
+ * 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<ClientRegistration> {
 	private final Map<String, ClientRegistration> 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<ClientRegistration> registrations) {
 		Assert.notEmpty(registrations, "registrations cannot be empty");
 		Collector<ClientRegistration, ?, ConcurrentMap<String, ClientRegistration>> 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<ClientRegistration>}
+	 */
 	@Override
 	public Iterator<ClientRegistration> iterator() {
 		return this.registrations.values().iterator();

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;

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.
  * <p>
  * The custom user type(s) is supplied via the constructor,
- * using a <code>Map</code> of {@link OAuth2User} type <i>keyed</i> by <code>String</code>,
+ * 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<OAuth
 	private final Map<String, Class<? extends OAuth2User>> 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<String, Class<? extends OAuth2User>> customUserTypes) {
 		Assert.notEmpty(customUserTypes, "customUserTypes cannot be empty");
 		this.customUserTypes = Collections.unmodifiableMap(new LinkedHashMap<>(customUserTypes));

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 <i>OAuth 2.0 Provider's</i>.
+ * An implementation of an {@link OAuth2UserService} that supports standard OAuth 2.0 Provider's.
  * <p>
- * For standard <i>OAuth 2.0 Provider's</i>, the attribute name (from the <i>UserInfo Response</i>)
+ * For standard OAuth 2.0 Provider's, the attribute name used to access the user's name
- * for the <i>&quot;user's name&quot;</i> is required and therefore must be supplied via
+ * from the UserInfo response is required and therefore must be available via
- * {@link org.springframework.security.oauth2.client.registration.ClientRegistration.ProviderDetails.UserInfoEndpoint#getUserNameAttributeName()}.
+ * {@link org.springframework.security.oauth2.client.registration.ClientRegistration.ProviderDetails.UserInfoEndpoint#getUserNameAttributeName() UserInfoEndpoint.getUserNameAttributeName()}.
  * <p>
- * <b>NOTE:</b> Attribute names are <b><i>not</i></b> standardized between providers and therefore will vary.
+ * <b>NOTE:</b> Attribute names are <b>not</b> 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

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 <code>List</code> of {@link OAuth2UserService}'s.
+ * to it's internal {@code List} of {@link OAuth2UserService}(s).
  * <p>
  * Each {@link OAuth2UserService} is given a chance to
  * {@link OAuth2UserService#loadUser(OAuth2UserRequest) load} an {@link OAuth2User}
- * with the first <code>non-null</code> {@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 <R> The type of <i>OAuth 2.0 User Request</i>
+ * @param <R> The type of OAuth 2.0 User Request
- * @param <U> The type of <i>OAuth 2.0 User</i>
+ * @param <U> The type of OAuth 2.0 User
  */
 public class DelegatingOAuth2UserService<R extends OAuth2UserRequest, U extends OAuth2User> implements OAuth2UserService<R, U> {
 	private final List<OAuth2UserService<R, U>> userServices;
 
+	/**
+	 * Constructs a {@code DelegatingOAuth2UserService} using the provided parameters.
+	 *
+	 * @param userServices a {@code List} of {@link OAuth2UserService}(s)
+	 */
 	public DelegatingOAuth2UserService(List<OAuth2UserService<R, U>> userServices) {
 		Assert.notEmpty(userServices, "userServices cannot be empty");
 		this.userServices = Collections.unmodifiableList(new ArrayList<>(userServices));

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 <i>UserInfo Endpoint</i>.
+ * 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;
 	}

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 <i>End-User</i> (Resource Owner) from the <i>UserInfo Endpoint</i>
+ * 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 <R> The type of <i>OAuth 2.0 User Request</i>
+ * @param <R> The type of OAuth 2.0 User Request
- * @param <U> The type of <i>OAuth 2.0 User</i>
+ * @param <U> The type of OAuth 2.0 User
  */
 public interface OAuth2UserService<R extends OAuth2UserRequest, U extends OAuth2User> {
 
+	/**
+	 * 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;
 
 }

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 <i>OAuth 2.0 User</i>.
+ * 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;

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.
  *
  * <p>
- * Used by the {@link OAuth2AuthorizationRequestRedirectFilter} for persisting the <i>Authorization Request</i>
+ * 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 <i>Authorization Request</i> when handling the <i>Authorization Response</i>.
+ * the associated Authorization Request when handling the callback of the Authorization Response.
  *
  * @author Joe Grandja
  * @since 5.0
  * @see OAuth2AuthorizationRequest
  * @see HttpSessionOAuth2AuthorizationRequestRepository
  *
- * @param <T> The type of <i>OAuth 2.0 Authorization Request</i>
+ * @param <T> The type of OAuth 2.0 Authorization Request
  */
 public interface AuthorizationRequestRepository<T extends OAuth2AuthorizationRequest> {
 
+	/**
+	 * 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);
 
 }

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<OAuth2AuthorizationRequest> {

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 <code>Filter</code> initiates the authorization code grant or implicit grant flow
+ * 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 <i>Authorization Endpoint</i>.
+ * by redirecting the End-User's user-agent to the Authorization Server's Authorization Endpoint.
  *
  * <p>
- * It builds the <i>OAuth 2.0 Authorization Request</i>,
+ * It builds the OAuth 2.0 Authorization Request,
- * which is used as the redirect <code>URI</code> to the <i>Authorization Endpoint</i>.
+ * which is used as the redirect {@code URI} to the Authorization Endpoint.
- * The redirect <code>URI</code> will include the client identifier, requested scope(s), state,
+ * 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 <a target="_blank" href="https://tools.ietf.org/html/rfc6749#section-4.2.1">Section 4.2.1 Authorization Request (Implicit)</a>
  */
 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<OAuth2AuthorizationRequest> 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<OAuth2AuthorizationRequest> authorizationRequestRepository) {
 		Assert.notNull(authorizationRequestRepository, "authorizationRequestRepository cannot be null");
 		this.authorizationRequestRepository = authorizationRequestRepository;

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 <i>OAuth 2.0 Authorization Request</i>.
+ * A {@code URI} builder for an OAuth 2.0 Authorization Request.
  *
  * @author Joe Grandja
  * @since 5.0

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
+ * An implementation of an {@link AbstractAuthenticationProcessingFilter} for OAuth 2.0 Login.
- * the processing of an <i>OAuth 2.0 Authorization Response</i> for the authorization code grant flow.
  *
  * <p>
- * This <code>Filter</code> processes the <i>Authorization Response</i> 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.
+ *
+ * <p>
+ * The OAuth 2.0 Authorization Response is processed as follows:
  *
  * <ul>
  * <li>
- *	Assuming the resource owner (end-user) has granted access to the client, the authorization server will append the
+ *	Assuming the End-User (Resource Owner) has granted access to the Client, the Authorization Server will append the
- *	{@link OAuth2ParameterNames#CODE} and {@link OAuth2ParameterNames#STATE} (if provided in the <i>Authorization Request</i>) parameters
+ *	{@link OAuth2ParameterNames#CODE code} and {@link OAuth2ParameterNames#STATE state} parameters
- *	to the {@link OAuth2ParameterNames#REDIRECT_URI} (provided in the <i>Authorization Request</i>)
+ *	to the {@link OAuth2ParameterNames#REDIRECT_URI redirect_uri} (provided in the Authorization Request)
- *	and redirect the end-user's user-agent back to this <code>Filter</code> (the client).
+ *	and redirect the End-User's user-agent back to this {@code Filter} (the Client).
  * </li>
  * <li>
- *  This <code>Filter</code> will then create an {@link OAuth2LoginAuthenticationToken} with
+ *  This {@code Filter} will then create an {@link OAuth2LoginAuthenticationToken} with
- *  the {@link OAuth2ParameterNames#CODE} received in the previous step and delegate it to
+ *  the {@link OAuth2ParameterNames#CODE code} received and
- *  {@link OAuth2LoginAuthenticationProvider#authenticate(Authentication)} (indirectly via {@link AuthenticationManager}).
+ *  delegate it to the {@link AuthenticationManager} to authenticate.
+ * </li>
+ * <li>
+ *  Upon a successful authentication, an {@link OAuth2AuthenticationToken} is created (representing the End-User {@code Principal})
+ *  and associated to the {@link OAuth2AuthorizedClient Authorized Client} using the {@link OAuth2AuthorizedClientService}.
+ * </li>
+ * <li>
+ *  Finally, the {@link OAuth2AuthenticationToken} is returned and ultimately stored
+ *  in the {@link SecurityContextRepository} to complete the authentication processing.
  * </li>
  * </ul>
  *
@@ -73,11 +86,15 @@ import java.io.IOException;
  * @see AuthorizationRequestRepository
  * @see OAuth2AuthorizationRequestRedirectFilter
  * @see ClientRegistrationRepository
+ * @see OAuth2AuthorizedClient
  * @see OAuth2AuthorizedClientService
  * @see <a target="_blank" href="https://tools.ietf.org/html/rfc6749#section-4.1">Section 4.1 Authorization Code Grant</a>
  * @see <a target="_blank" href="https://tools.ietf.org/html/rfc6749#section-4.1.2">Section 4.1.2 Authorization Response</a>
  */
 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<OAuth2AuthorizationRequest> 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<OAuth2AuthorizationRequest> authorizationRequestRepository) {
 		Assert.notNull(authorizationRequestRepository, "authorizationRequestRepository cannot be null");
 		this.authorizationRequestRepository = authorizationRequestRepository;

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;

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) {