diff --git a/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/authentication/AuthorizationRequestUriBuilder.java b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/authentication/AuthorizationRequestUriBuilder.java index 2eba15386c..a64008b451 100644 --- a/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/authentication/AuthorizationRequestUriBuilder.java +++ b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/authentication/AuthorizationRequestUriBuilder.java @@ -21,9 +21,24 @@ import org.springframework.security.oauth2.core.endpoint.AuthorizationRequestAtt import java.net.URI; /** + * Implementations of this interface are responsible for building an OAuth 2.0 Authorization Request, + * which is used as the redirect URI to the Authorization Endpoint. + * + *

+ * The returned redirect URI will include the following parameters as query components to the + * Authorization Endpoint (using the "application/x-www-form-urlencoded" format): + *

* * @author Joe Grandja * @since 5.0 + * @see AuthorizationRequestAttributes + * @see Section 4.1.1 Authorization Request */ public interface AuthorizationRequestUriBuilder { diff --git a/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/authentication/DefaultAuthorizationRequestUriBuilder.java b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/authentication/DefaultAuthorizationRequestUriBuilder.java index e2ae810873..292565cfb4 100644 --- a/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/authentication/DefaultAuthorizationRequestUriBuilder.java +++ b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/authentication/DefaultAuthorizationRequestUriBuilder.java @@ -15,18 +15,22 @@ */ package org.springframework.security.oauth2.client.authentication; +import org.springframework.security.oauth2.core.endpoint.AuthorizationRequestAttributes; import org.springframework.security.oauth2.core.endpoint.OAuth2Parameter; import org.springframework.security.oauth2.core.endpoint.ResponseType; -import org.springframework.security.oauth2.core.endpoint.AuthorizationRequestAttributes; import org.springframework.web.util.UriComponentsBuilder; import java.net.URI; import java.util.stream.Collectors; /** + * The default implementation of an {@link AuthorizationRequestUriBuilder}, + * which internally uses an {@link UriComponentsBuilder} to construct the OAuth 2.0 Authorization Request. * * @author Joe Grandja * @since 5.0 + * @see AuthorizationRequestAttributes + * @see Section 4.1.1 Authorization Request */ public class DefaultAuthorizationRequestUriBuilder implements AuthorizationRequestUriBuilder { 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 new file mode 100644 index 0000000000..cf81d1aada --- /dev/null +++ b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/authentication/package-info.java @@ -0,0 +1,20 @@ +/* + * Copyright 2012-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/interfaces for authenticating an end-user + * with an authorization server using the authorization code grant flow. + */ +package org.springframework.security.oauth2.client.authentication; 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 da5b3b2ad3..63eeeca05e 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 @@ -25,11 +25,12 @@ import java.util.Collections; import java.util.LinkedHashSet; import java.util.Set; - /** + * A representation of a client registration with an OAuth 2.0 Authorization Server. * * @author Joe Grandja * @since 5.0 + * @see Section 2 Client Registration */ public class ClientRegistration { private String clientId; diff --git a/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/registration/ClientRegistrationProperties.java b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/registration/ClientRegistrationProperties.java index a4c73fb3b7..da2afc5e5a 100644 --- a/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/registration/ClientRegistrationProperties.java +++ b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/registration/ClientRegistrationProperties.java @@ -21,9 +21,16 @@ import org.springframework.security.oauth2.core.ClientAuthenticationMethod; import java.util.Set; /** + * A convenience class that provides a "flattened" property structure for {@link ClientRegistration}. + * + *

+ * This class may be used to "bind" property values located in the {@link org.springframework.core.env.Environment} + * and then pass it to {@link ClientRegistration.Builder#Builder(ClientRegistrationProperties)} + * to construct a {@link ClientRegistration} instance. * * @author Joe Grandja * @since 5.0 + * @see ClientRegistration */ public class ClientRegistrationProperties { private String clientId; 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 acfab16adf..f924719857 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 @@ -18,9 +18,18 @@ package org.springframework.security.oauth2.client.registration; import java.util.List; /** + * Implementations of this interface are responsible for the management of {@link ClientRegistration}'s. + * + *

+ * The primary client registration information is stored with the associated Authorization Server. + * However, there may be uses cases where secondary information may need to be managed + * that is not supported (or provided) by the Authorization Server. + * This interface provides this capability for managing the primary and secondary + * information of a client registration. * * @author Joe Grandja * @since 5.0 + * @see ClientRegistration */ public interface ClientRegistrationRepository { 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 3cd21fa51a..afabd923b3 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 @@ -22,9 +22,12 @@ import java.util.List; import java.util.Optional; /** + * A basic implementation of a {@link ClientRegistrationRepository} that accepts + * a List of {@link ClientRegistration}(s) via it's constructor and stores it in-memory. * * @author Joe Grandja * @since 5.0 + * @see ClientRegistration */ public final class InMemoryClientRegistrationRepository implements ClientRegistrationRepository { private final List clientRegistrations; 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 new file mode 100644 index 0000000000..791f5100e3 --- /dev/null +++ b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/registration/package-info.java @@ -0,0 +1,19 @@ +/* + * Copyright 2012-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 related to {@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/user/converter/AbstractOAuth2UserConverter.java b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/user/converter/AbstractOAuth2UserConverter.java index 1c94df7299..aa20aff605 100644 --- a/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/user/converter/AbstractOAuth2UserConverter.java +++ b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/user/converter/AbstractOAuth2UserConverter.java @@ -25,9 +25,13 @@ import java.io.IOException; import java.util.Map; /** + * Base implementation of a {@link Converter} that converts a {@link ClientHttpResponse} + * to a specific type of {@link OAuth2User}. * * @author Joe Grandja * @since 5.0 + * @see OAuth2User + * @see ClientHttpResponse */ public abstract class AbstractOAuth2UserConverter implements Converter { private final HttpMessageConverter jackson2HttpMessageConverter = new MappingJackson2HttpMessageConverter(); diff --git a/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/user/converter/CustomOAuth2UserConverter.java b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/user/converter/CustomOAuth2UserConverter.java index 48f4d75ca7..c101a4fe83 100644 --- a/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/user/converter/CustomOAuth2UserConverter.java +++ b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/user/converter/CustomOAuth2UserConverter.java @@ -24,9 +24,13 @@ import org.springframework.security.oauth2.core.user.OAuth2User; import java.io.IOException; /** + * An implementation of a {@link Converter} that converts a {@link ClientHttpResponse} + * to a custom type of {@link OAuth2User}, as supplied via the constructor. * * @author Joe Grandja * @since 5.0 + * @see OAuth2User + * @see ClientHttpResponse */ public final class CustomOAuth2UserConverter implements Converter { private final HttpMessageConverter jackson2HttpMessageConverter = new MappingJackson2HttpMessageConverter(); diff --git a/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/user/converter/OAuth2UserConverter.java b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/user/converter/OAuth2UserConverter.java index 6db9b2bded..3e0d123644 100644 --- a/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/user/converter/OAuth2UserConverter.java +++ b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/user/converter/OAuth2UserConverter.java @@ -15,6 +15,7 @@ */ package org.springframework.security.oauth2.client.user.converter; +import org.springframework.http.client.ClientHttpResponse; import org.springframework.security.oauth2.core.user.DefaultOAuth2User; import org.springframework.security.oauth2.core.user.OAuth2User; import org.springframework.util.Assert; @@ -22,9 +23,13 @@ import org.springframework.util.Assert; import java.util.Map; /** + * An implementation of a {@link AbstractOAuth2UserConverter} that converts + * a {@link ClientHttpResponse} to a {@link OAuth2User}. * * @author Joe Grandja * @since 5.0 + * @see OAuth2User + * @see ClientHttpResponse */ public final class OAuth2UserConverter extends AbstractOAuth2UserConverter { private final String nameAttributeKey; diff --git a/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/user/converter/UserInfoConverter.java b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/user/converter/UserInfoConverter.java index 481ac8c4d9..6b06fece18 100644 --- a/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/user/converter/UserInfoConverter.java +++ b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/user/converter/UserInfoConverter.java @@ -15,15 +15,20 @@ */ package org.springframework.security.oauth2.client.user.converter; +import org.springframework.http.client.ClientHttpResponse; import org.springframework.security.oauth2.oidc.user.DefaultUserInfo; import org.springframework.security.oauth2.oidc.user.UserInfo; import java.util.Map; /** + * An implementation of a {@link AbstractOAuth2UserConverter} that converts + * a {@link ClientHttpResponse} to a {@link UserInfo}. * * @author Joe Grandja * @since 5.0 + * @see UserInfo + * @see ClientHttpResponse */ public final class UserInfoConverter extends AbstractOAuth2UserConverter { diff --git a/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/user/converter/package-info.java b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/user/converter/package-info.java new file mode 100644 index 0000000000..6ebf53767b --- /dev/null +++ b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/user/converter/package-info.java @@ -0,0 +1,20 @@ +/* + * Copyright 2012-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. + */ +/** + * {@link org.springframework.core.convert.converter.Converter} implementations + * for {@link org.springframework.security.oauth2.core.user.OAuth2User}. + */ +package org.springframework.security.oauth2.client.user.converter; diff --git a/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/user/nimbus/NimbusClientHttpResponse.java b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/user/nimbus/NimbusClientHttpResponse.java index adac4c8a68..2ee2282c7b 100644 --- a/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/user/nimbus/NimbusClientHttpResponse.java +++ b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/user/nimbus/NimbusClientHttpResponse.java @@ -18,6 +18,7 @@ package org.springframework.security.oauth2.client.user.nimbus; import com.nimbusds.oauth2.sdk.http.HTTPResponse; import org.springframework.http.HttpHeaders; import org.springframework.http.client.AbstractClientHttpResponse; +import org.springframework.http.client.ClientHttpResponse; import org.springframework.util.Assert; import java.io.ByteArrayInputStream; @@ -26,6 +27,10 @@ import java.io.InputStream; import java.nio.charset.Charset; /** + * An implementation of a {@link ClientHttpResponse} which is used by {@link NimbusOAuth2UserService}. + * + *

+ * NOTE: This class is intended for internal use only. * * @author Joe Grandja * @since 5.0 diff --git a/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/user/package-info.java b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/user/package-info.java new file mode 100644 index 0000000000..65d27dda5d --- /dev/null +++ b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/user/package-info.java @@ -0,0 +1,19 @@ +/* + * Copyright 2012-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 related to an OAuth 2.0 User. + */ +package org.springframework.security.oauth2.client.user; diff --git a/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/web/converter/AuthorizationCodeAuthorizationResponseAttributesConverter.java b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/web/converter/AuthorizationCodeAuthorizationResponseAttributesConverter.java index 9a8fadc9fb..9c893bc119 100644 --- a/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/web/converter/AuthorizationCodeAuthorizationResponseAttributesConverter.java +++ b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/web/converter/AuthorizationCodeAuthorizationResponseAttributesConverter.java @@ -16,16 +16,20 @@ package org.springframework.security.oauth2.client.web.converter; import org.springframework.core.convert.converter.Converter; -import org.springframework.security.oauth2.core.endpoint.OAuth2Parameter; import org.springframework.security.oauth2.core.endpoint.AuthorizationCodeAuthorizationResponseAttributes; +import org.springframework.security.oauth2.core.endpoint.OAuth2Parameter; import org.springframework.util.Assert; import javax.servlet.http.HttpServletRequest; /** + * An implementation of a {@link Converter} that converts an OAuth 2.0 Authorization Code Grant Response + * (in the form of a {@link HttpServletRequest}) to a {@link AuthorizationCodeAuthorizationResponseAttributes}. * * @author Joe Grandja * @since 5.0 + * @see AuthorizationCodeAuthorizationResponseAttributes + * @see Section 4.1.2 Authorization Code Grant Response */ public final class AuthorizationCodeAuthorizationResponseAttributesConverter implements Converter { diff --git a/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/web/converter/ErrorResponseAttributesConverter.java b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/web/converter/ErrorResponseAttributesConverter.java index 2c422e8246..6bee0b37a4 100644 --- a/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/web/converter/ErrorResponseAttributesConverter.java +++ b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/web/converter/ErrorResponseAttributesConverter.java @@ -23,9 +23,12 @@ import org.springframework.util.StringUtils; import javax.servlet.http.HttpServletRequest; /** + * An implementation of a {@link Converter} that converts an OAuth 2.0 Error Response + * (in the form of a {@link HttpServletRequest}) to a {@link ErrorResponseAttributes}. * * @author Joe Grandja * @since 5.0 + * @see ErrorResponseAttributes */ public final class ErrorResponseAttributesConverter implements Converter { diff --git a/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/web/converter/package-info.java b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/web/converter/package-info.java new file mode 100644 index 0000000000..1678695af9 --- /dev/null +++ b/oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/web/converter/package-info.java @@ -0,0 +1,20 @@ +/* + * Copyright 2012-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. + */ +/** + * {@link org.springframework.core.convert.converter.Converter} implementations + * for OAuth 2.0 Protocol Endpoint Messages. + */ +package org.springframework.security.oauth2.client.web.converter;