Cwikius-Spring
/
spring-security
mirror of https://github.com/spring-projects/spring-security.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Add javadoc for spring-security-oauth2-jose 

Fixes gh-4885
This commit is contained in:
Joe Grandja 2018-01-23 19:59:32 -05:00
parent fe2ac00deb
commit 6b24aaf6f5
9 changed files with 165 additions and 19 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -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

19
oauth2/oauth2-jose/src/main/java/org/springframework/security/oauth2/jose/jws/package-info.java Normal file
View File

@ -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;

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

@ -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;

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

@ -22,8 +22,8 @@ import java.time.Instant;
import java.util.List;
/**
* A {@link ClaimAccessor} for the &quot;Claims&quot; 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);
}

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

@ -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";
}

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

@ -17,12 +17,12 @@ package org.springframework.security.oauth2.jwt;
/**
* Implementations of this interface are responsible for &quot;decoding&quot;
* 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;
}

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

@ -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);
}

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

@ -39,12 +39,12 @@ import java.util.Map;
/**
* An implementation of a {@link JwtDecoder} that &quot;decodes&quot; 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");

19
oauth2/oauth2-jose/src/main/java/org/springframework/security/oauth2/jwt/package-info.java Normal file
View File

@ -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;