Add javadoc for spring-security-oauth2-jose

Fixes gh-4885

oauth2/oauth2-jose/src/main/java/org/springframework/security/oauth2/jose/jws/JwsAlgorithms.java

@@ -16,8 +16,8 @@
 package org.springframework.security.oauth2.jose.jws;
 
 /**
- * The cryptographic algorithms defined by the <i>JSON Web Algorithms (JWA)</i> specification
- * and used by <i>JSON Web Signature (JWS)</i> to digitally sign or create a MAC
+ * The cryptographic algorithms defined by the JSON Web Algorithms (JWA) specification
+ * and used by JSON Web Signature (JWS) to digitally sign or create a MAC
  * of the contents of the JWS Protected Header and JWS Payload.
  *
  * @author Joe Grandja

oauth2/oauth2-jose/src/main/java/org/springframework/security/oauth2/jose/jws/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 JSON Web Signature (JWS).
+ */
+package org.springframework.security.oauth2.jose.jws;

oauth2/oauth2-jose/src/main/java/org/springframework/security/oauth2/jwt/Jwt.java

@@ -24,13 +24,13 @@ import java.util.LinkedHashMap;
 import java.util.Map;
 
 /**
- * An implementation of an {@link AbstractOAuth2Token} representing a <i>JSON Web Token (JWT)</i>.
+ * An implementation of an {@link AbstractOAuth2Token} representing a JSON Web Token (JWT).
  *
  * <p>
- * JWTs represent a set of &quot;Claims&quot; as a JSON object that may be encoded in a
- * <i>JSON Web Signature (JWS)</i> and/or <i>JSON Web Encryption (JWE)</i> structure.
- * The JSON object, also known as the <i>JWT Claims Set</i>, consists of one or more Claim Name/Claim Value pairs.
- * The Claim Name is a <code>String</code> and the Claim Value is an arbitrary JSON object.
+ * JWTs represent a set of &quot;claims&quot; as a JSON object that may be encoded in a
+ * JSON Web Signature (JWS) and/or JSON Web Encryption (JWE) structure.
+ * The JSON object, also known as the JWT Claims Set, consists of one or more claim name/value pairs.
+ * The claim name is a {@code String} and the claim value is an arbitrary JSON object.
  *
  * @author Joe Grandja
  * @since 5.0
@@ -44,6 +44,15 @@ public class Jwt extends AbstractOAuth2Token implements JwtClaimAccessor {
 	private final Map<String, Object> headers;
 	private final Map<String, Object> claims;
 
+	/**
+	 * Constructs a {@code Jwt} using the provided parameters.
+	 *
+	 * @param tokenValue the token value
+	 * @param issuedAt the time at which the JWT was issued
+	 * @param expiresAt the expiration time on or after which the JWT MUST NOT be accepted
+	 * @param headers the JOSE header(s)
+	 * @param claims the JWT Claims Set
+	 */
 	public Jwt(String tokenValue, Instant issuedAt, Instant expiresAt,
 				Map<String, Object> headers, Map<String, Object> claims) {
 		super(tokenValue, issuedAt, expiresAt);
@@ -53,10 +62,20 @@ public class Jwt extends AbstractOAuth2Token implements JwtClaimAccessor {
 		this.claims = Collections.unmodifiableMap(new LinkedHashMap<>(claims));
 	}
 
+	/**
+	 * Returns the JOSE header(s).
+	 *
+	 * @return a {@code Map} of the JOSE header(s)
+	 */
 	public Map<String, Object> getHeaders() {
 		return this.headers;
 	}
 
+	/**
+	 * Returns the JWT Claims Set.
+	 *
+	 * @return a {@code Map} of the JWT Claims Set
+	 */
 	@Override
 	public Map<String, Object> getClaims() {
 		return this.claims;

oauth2/oauth2-jose/src/main/java/org/springframework/security/oauth2/jwt/JwtClaimAccessor.java

@@ -22,8 +22,8 @@ import java.time.Instant;
 import java.util.List;
 
 /**
- * A {@link ClaimAccessor} for the "Claims" that may be contained
- * in the JSON object <i>JWT Claims Set</i> of a <i>JSON Web Token (JWT)</i>.
+ * A {@link ClaimAccessor} for the &quot;claims&quot; that may be contained
+ * in the JSON object JWT Claims Set of a JSON Web Token (JWT).
  *
  * @author Joe Grandja
  * @since 5.0
@@ -34,30 +34,69 @@ import java.util.List;
  */
 public interface JwtClaimAccessor extends ClaimAccessor {
 
+	/**
+	 * Returns the Issuer {@code (iss)} claim which identifies the principal that issued the JWT.
+	 *
+	 * @return the Issuer identifier
+	 */
 	default URL getIssuer() {
 		return this.getClaimAsURL(JwtClaimNames.ISS);
 	}
 
+	/**
+	 * Returns the Subject {@code (sub)} claim which identifies the principal
+	 * that is the subject of the JWT.
+	 *
+	 * @return the Subject identifier
+	 */
 	default String getSubject() {
 		return this.getClaimAsString(JwtClaimNames.SUB);
 	}
 
+	/**
+	 * Returns the Audience {@code (aud)} claim which identifies the recipient(s)
+	 * that the JWT is intended for.
+	 *
+	 * @return the Audience(s) that this JWT intended for
+	 */
 	default List<String> getAudience() {
 		return this.getClaimAsStringList(JwtClaimNames.AUD);
 	}
 
+	/**
+	 * Returns the Expiration time {@code (exp)} claim which identifies the expiration time
+	 * on or after which the JWT MUST NOT be accepted for processing.
+	 *
+	 * @return the Expiration time on or after which the JWT MUST NOT be accepted for processing
+	 */
 	default Instant getExpiresAt() {
 		return this.getClaimAsInstant(JwtClaimNames.EXP);
 	}
 
+	/**
+	 * Returns the Not Before {@code (nbf)} claim which identifies the time
+	 * before which the JWT MUST NOT be accepted for processing.
+	 *
+	 * @return the Not Before time before which the JWT MUST NOT be accepted for processing
+	 */
 	default Instant getNotBefore() {
 		return this.getClaimAsInstant(JwtClaimNames.NBF);
 	}
 
+	/**
+	 * Returns the Issued at {@code (iat)} claim which identifies the time at which the JWT was issued.
+	 *
+	 * @return the Issued at claim which identifies the time at which the JWT was issued
+	 */
 	default Instant getIssuedAt() {
 		return this.getClaimAsInstant(JwtClaimNames.IAT);
 	}
 
+	/**
+	 * Returns the JWT ID {@code (jti)} claim which provides a unique identifier for the JWT.
+	 *
+	 * @return the JWT ID claim which provides a unique identifier for the JWT
+	 */
 	default String getId() {
 		return this.getClaimAsString(JwtClaimNames.JTI);
 	}

oauth2/oauth2-jose/src/main/java/org/springframework/security/oauth2/jwt/JwtClaimNames.java

@@ -16,8 +16,8 @@
 package org.springframework.security.oauth2.jwt;
 
 /**
- * The &quot;Registered Claim Names&quot; defined by the <i>JSON Web Token (JWT)</i> specification
- * that may be contained in the JSON object <i>JWT Claims Set</i>.
+ * The Registered Claim Names defined by the JSON Web Token (JWT) specification
+ * that may be contained in the JSON object JWT Claims Set.
  *
  * @author Joe Grandja
  * @since 5.0
@@ -26,18 +26,39 @@ package org.springframework.security.oauth2.jwt;
  */
 public interface JwtClaimNames {
 
+	/**
+	 * {@code iss} - the Issuer claim identifies the principal that issued the JWT
+	 */
 	String ISS = "iss";
 
+	/**
+	 * {@code sub} - the Subject claim identifies the principal that is the subject of the JWT
+	 */
 	String SUB = "sub";
 
+	/**
+	 * {@code aud} - the Audience claim identifies the recipient(s) that the JWT is intended for
+	 */
 	String AUD = "aud";
 
+	/**
+	 * {@code exp} - the Expiration time claim identifies the expiration time on or after which the JWT MUST NOT be accepted for processing
+	 */
 	String EXP = "exp";
 
+	/**
+	 * {@code nbf} - the Not Before claim identifies the time before which the JWT MUST NOT be accepted for processing
+	 */
 	String NBF = "nbf";
 
+	/**
+	 * {@code iat} - The Issued at claim identifies the time at which the JWT was issued
+	 */
 	String IAT = "iat";
 
+	/**
+	 * {@code jti} - The JWT ID claim provides a unique identifier for the JWT
+	 */
 	String JTI = "jti";
 
 }

oauth2/oauth2-jose/src/main/java/org/springframework/security/oauth2/jwt/JwtDecoder.java

@@ -17,12 +17,12 @@ package org.springframework.security.oauth2.jwt;
 
 /**
  * Implementations of this interface are responsible for "decoding"
- * a <i>JSON Web Token (JWT)</i> from it's compact claims representation format to a {@link Jwt}.
+ * a JSON Web Token (JWT) from it's compact claims representation format to a {@link Jwt}.
  *
  * <p>
  * JWTs may be represented using the JWS Compact Serialization format for a
- * <i>JSON Web Signature (JWS)</i> structure or JWE Compact Serialization format for a
- * <i>JSON Web Encryption (JWE)</i> structure. Therefore, implementors are responsible
+ * JSON Web Signature (JWS) structure or JWE Compact Serialization format for a
+ * JSON Web Encryption (JWE) structure. Therefore, implementors are responsible
  * for verifying a JWS and/or decrypting a JWE.
  *
  * @author Joe Grandja
@@ -36,6 +36,13 @@ package org.springframework.security.oauth2.jwt;
  */
 public interface JwtDecoder {
 
+	/**
+	 * Decodes the JWT from it's compact claims representation format and returns a {@link Jwt}.
+	 *
+	 * @param token the JWT value
+	 * @return a {@link Jwt}
+	 * @throws JwtException if an error occurs while attempting to decode the JWT
+	 */
 	Jwt decode(String token) throws JwtException;
 
 }

oauth2/oauth2-jose/src/main/java/org/springframework/security/oauth2/jwt/JwtException.java

@@ -16,17 +16,28 @@
 package org.springframework.security.oauth2.jwt;
 
 /**
- * Base exception for all <i>JSON Web Token (JWT)</i> related errors.
+ * Base exception for all JSON Web Token (JWT) related errors.
  *
  * @author Joe Grandja
  * @since 5.0
  */
 public class JwtException extends RuntimeException {
 
+	/**
+	 * Constructs a {@code JwtException} using the provided parameters.
+	 *
+	 * @param message the detail message
+	 */
 	public JwtException(String message) {
 		super(message);
 	}
 
+	/**
+	 * Constructs a {@code JwtException} using the provided parameters.
+	 *
+	 * @param message the detail message
+	 * @param cause the root cause
+	 */
 	public JwtException(String message, Throwable cause) {
 		super(message, cause);
 	}

oauth2/oauth2-jose/src/main/java/org/springframework/security/oauth2/jwt/NimbusJwtDecoderJwkSupport.java

@@ -39,12 +39,12 @@ import java.util.Map;
 
 /**
  * An implementation of a {@link JwtDecoder} that "decodes" a
- * <i>JSON Web Token (JWT)</i> and additionally verifies it's digital signature if the JWT is a
- * <i>JSON Web Signature (JWS)</i>. The public key used for verification is obtained from the
- * <i>JSON Web Key (JWK)</i> Set <code>URL</code> which is supplied via the constructor.
+ * JSON Web Token (JWT) and additionally verifies it's digital signature if the JWT is a
+ * JSON Web Signature (JWS). The public key used for verification is obtained from the
+ * JSON Web Key (JWK) Set {@code URL} supplied via the constructor.
  *
  * <p>
- * <b>NOTE:</b> This implementation uses the <b>Nimbus JOSE + JWT SDK</b> internally.
+ * <b>NOTE:</b> This implementation uses the Nimbus JOSE + JWT SDK internally.
  *
  * @author Joe Grandja
  * @since 5.0
@@ -59,10 +59,21 @@ public final class NimbusJwtDecoderJwkSupport implements JwtDecoder {
 	private final JWSAlgorithm jwsAlgorithm;
 	private final ConfigurableJWTProcessor<SecurityContext> jwtProcessor;
 
+	/**
+	 * Constructs a {@code NimbusJwtDecoderJwkSupport} using the provided parameters.
+	 *
+	 * @param jwkSetUrl the JSON Web Key (JWK) Set {@code URL}
+	 */
 	public NimbusJwtDecoderJwkSupport(String jwkSetUrl) {
 		this(jwkSetUrl, JwsAlgorithms.RS256);
 	}
 
+	/**
+	 * Constructs a {@code NimbusJwtDecoderJwkSupport} using the provided parameters.
+	 *
+	 * @param jwkSetUrl the JSON Web Key (JWK) Set {@code URL}
+	 * @param jwsAlgorithm the JSON Web Algorithm (JWA) used for verifying the digital signatures
+	 */
 	public NimbusJwtDecoderJwkSupport(String jwkSetUrl, String jwsAlgorithm) {
 		Assert.hasText(jwkSetUrl, "jwkSetUrl cannot be empty");
 		Assert.hasText(jwsAlgorithm, "jwsAlgorithm cannot be empty");

oauth2/oauth2-jose/src/main/java/org/springframework/security/oauth2/jwt/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 JSON Web Token (JWT).
+ */
+package org.springframework.security.oauth2.jwt;