diff --git a/oauth2/oauth2-jose/src/main/java/org/springframework/security/oauth2/jose/jws/JwsAlgorithms.java b/oauth2/oauth2-jose/src/main/java/org/springframework/security/oauth2/jose/jws/JwsAlgorithms.java index 7fb672550f..0d219ea710 100644 --- a/oauth2/oauth2-jose/src/main/java/org/springframework/security/oauth2/jose/jws/JwsAlgorithms.java +++ b/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 JSON Web Algorithms (JWA) specification - * and used by JSON Web Signature (JWS) 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 diff --git a/oauth2/oauth2-jose/src/main/java/org/springframework/security/oauth2/jose/jws/package-info.java b/oauth2/oauth2-jose/src/main/java/org/springframework/security/oauth2/jose/jws/package-info.java new file mode 100644 index 0000000000..75e4bfbb48 --- /dev/null +++ b/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; diff --git a/oauth2/oauth2-jose/src/main/java/org/springframework/security/oauth2/jwt/Jwt.java b/oauth2/oauth2-jose/src/main/java/org/springframework/security/oauth2/jwt/Jwt.java index c09c985566..bae22b67f5 100644 --- a/oauth2/oauth2-jose/src/main/java/org/springframework/security/oauth2/jwt/Jwt.java +++ b/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 JSON Web Token (JWT). + * An implementation of an {@link AbstractOAuth2Token} representing a JSON Web Token (JWT). * *

- * JWTs represent a set of "Claims" 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/Claim Value pairs. - * The Claim Name is a String and the Claim Value is an arbitrary JSON object. + * JWTs represent a set of "claims" 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 headers; private final Map 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 headers, Map 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 getHeaders() { return this.headers; } + /** + * Returns the JWT Claims Set. + * + * @return a {@code Map} of the JWT Claims Set + */ @Override public Map getClaims() { return this.claims; diff --git a/oauth2/oauth2-jose/src/main/java/org/springframework/security/oauth2/jwt/JwtClaimAccessor.java b/oauth2/oauth2-jose/src/main/java/org/springframework/security/oauth2/jwt/JwtClaimAccessor.java index 6a3d1b146b..fea9d9335a 100644 --- a/oauth2/oauth2-jose/src/main/java/org/springframework/security/oauth2/jwt/JwtClaimAccessor.java +++ b/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 JWT Claims Set of a JSON Web Token (JWT). + * A {@link ClaimAccessor} for the "claims" 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 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); } diff --git a/oauth2/oauth2-jose/src/main/java/org/springframework/security/oauth2/jwt/JwtClaimNames.java b/oauth2/oauth2-jose/src/main/java/org/springframework/security/oauth2/jwt/JwtClaimNames.java index 8cdf231be7..3dfd128a9a 100644 --- a/oauth2/oauth2-jose/src/main/java/org/springframework/security/oauth2/jwt/JwtClaimNames.java +++ b/oauth2/oauth2-jose/src/main/java/org/springframework/security/oauth2/jwt/JwtClaimNames.java @@ -16,8 +16,8 @@ package org.springframework.security.oauth2.jwt; /** - * The "Registered Claim Names" defined by the JSON Web Token (JWT) specification - * that may be contained in the JSON object JWT Claims Set. + * 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"; } diff --git a/oauth2/oauth2-jose/src/main/java/org/springframework/security/oauth2/jwt/JwtDecoder.java b/oauth2/oauth2-jose/src/main/java/org/springframework/security/oauth2/jwt/JwtDecoder.java index 7c4564afdf..83d505e2db 100644 --- a/oauth2/oauth2-jose/src/main/java/org/springframework/security/oauth2/jwt/JwtDecoder.java +++ b/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 JSON Web Token (JWT) 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}. * *

* JWTs may be represented using the JWS Compact Serialization format for a - * JSON Web Signature (JWS) structure or JWE Compact Serialization format for a - * JSON Web Encryption (JWE) 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; } diff --git a/oauth2/oauth2-jose/src/main/java/org/springframework/security/oauth2/jwt/JwtException.java b/oauth2/oauth2-jose/src/main/java/org/springframework/security/oauth2/jwt/JwtException.java index c24f5bba55..a82ddf4f44 100644 --- a/oauth2/oauth2-jose/src/main/java/org/springframework/security/oauth2/jwt/JwtException.java +++ b/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 JSON Web Token (JWT) 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); } diff --git a/oauth2/oauth2-jose/src/main/java/org/springframework/security/oauth2/jwt/NimbusJwtDecoderJwkSupport.java b/oauth2/oauth2-jose/src/main/java/org/springframework/security/oauth2/jwt/NimbusJwtDecoderJwkSupport.java index 4011c0c5ab..a9aad2e10e 100644 --- a/oauth2/oauth2-jose/src/main/java/org/springframework/security/oauth2/jwt/NimbusJwtDecoderJwkSupport.java +++ b/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 - * 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 URL 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. * *

- * NOTE: This implementation uses the Nimbus JOSE + JWT SDK internally. + * NOTE: 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 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"); diff --git a/oauth2/oauth2-jose/src/main/java/org/springframework/security/oauth2/jwt/package-info.java b/oauth2/oauth2-jose/src/main/java/org/springframework/security/oauth2/jwt/package-info.java new file mode 100644 index 0000000000..b03b58c532 --- /dev/null +++ b/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;