Polish JwtEncoder APIs

Closes gh-391

Author: jgrandja

oauth2-authorization-server/src/main/java/org/springframework/security/oauth2/jwt/JoseHeader.java

@@ -24,7 +24,7 @@
 import java.util.function.Consumer;
 
 import org.springframework.security.oauth2.core.converter.ClaimConversionService;
-import org.springframework.security.oauth2.jose.jws.JwsAlgorithm;
+import org.springframework.security.oauth2.jose.JwaAlgorithm;
 import org.springframework.util.Assert;
 
 /**
@@ -36,9 +36,9 @@
  * @author Joe Grandja
  * @since 0.0.1
  * @see Jwt
- * @see <a target="_blank" href="https://tools.ietf.org/html/rfc7519#section-5">JWT JOSE Header</a>
- * @see <a target="_blank" href="https://tools.ietf.org/html/rfc7515#section-4">JWS JOSE Header</a>
- * @see <a target="_blank" href="https://tools.ietf.org/html/rfc7516#section-4">JWE JOSE Header</a>
+ * @see <a target="_blank" href="https://datatracker.ietf.org/doc/html/rfc7519#section-5">JWT JOSE Header</a>
+ * @see <a target="_blank" href="https://datatracker.ietf.org/doc/html/rfc7515#section-4">JWS JOSE Header</a>
+ * @see <a target="_blank" href="https://datatracker.ietf.org/doc/html/rfc7516#section-4">JWE JOSE Header</a>
  */
 public final class JoseHeader {
 	private final Map<String, Object> headers;
@@ -48,12 +48,13 @@ private JoseHeader(Map<String, Object> headers) {
 	}
 
 	/**
-	 * Returns the {@link JwsAlgorithm JWS algorithm} used to digitally sign the JWS.
+	 * Returns the {@link JwaAlgorithm JWA algorithm} used to digitally sign the JWS or encrypt the JWE.
 	 *
-	 * @return the JWS algorithm
+	 * @return the {@link JwaAlgorithm}
 	 */
-	public JwsAlgorithm getJwsAlgorithm() {
-		return getHeader(JoseHeaderNames.ALG);
+	@SuppressWarnings("unchecked")
+	public <T extends JwaAlgorithm> T getAlgorithm() {
+		return (T) getHeader(JoseHeaderNames.ALG);
 	}
 
 	/**
@@ -62,7 +63,7 @@ public JwsAlgorithm getJwsAlgorithm() {
 	 *
 	 * @return the JWK Set URL
 	 */
-	public URL getJwkSetUri() {
+	public URL getJwkSetUrl() {
 		return getHeader(JoseHeaderNames.JKU);
 	}
 
@@ -91,13 +92,16 @@ public String getKeyId() {
 	 *
 	 * @return the X.509 URL
 	 */
-	public URL getX509Uri() {
+	public URL getX509Url() {
 		return getHeader(JoseHeaderNames.X5U);
 	}
 
 	/**
 	 * Returns the X.509 certificate chain that contains the X.509 public key certificate
-	 * or certificate chain corresponding to the key used to digitally sign the JWS or encrypt the JWE.
+	 * or certificate chain corresponding to the key used to digitally sign the JWS or
+	 * encrypt the JWE. The certificate or certificate chain is represented as a
+	 * {@code List} of certificate value {@code String}s. Each {@code String} in the
+	 * {@code List} is a Base64-encoded DER PKIX certificate value.
 	 *
 	 * @return the X.509 certificate chain
 	 */
@@ -125,16 +129,6 @@ public String getX509SHA256Thumbprint() {
 		return getHeader(JoseHeaderNames.X5T_S256);
 	}
 
-	/**
-	 * Returns the critical headers that indicates which extensions to the JWS/JWE/JWA specifications
-	 * are being used that MUST be understood and processed.
-	 *
-	 * @return the critical headers
-	 */
-	public Set<String> getCritical() {
-		return getHeader(JoseHeaderNames.CRIT);
-	}
-
 	/**
 	 * Returns the type header that declares the media type of the JWS/JWE.
 	 *
@@ -153,6 +147,16 @@ public String getContentType() {
 		return getHeader(JoseHeaderNames.CTY);
 	}
 
+	/**
+	 * Returns the critical headers that indicates which extensions to the JWS/JWE/JWA specifications
+	 * are being used that MUST be understood and processed.
+	 *
+	 * @return the critical headers
+	 */
+	public Set<String> getCritical() {
+		return getHeader(JoseHeaderNames.CRIT);
+	}
+
 	/**
 	 * Returns the headers.
 	 *
@@ -185,13 +189,13 @@ public static Builder builder() {
 	}
 
 	/**
-	 * Returns a new {@link Builder}, initialized with the provided {@link JwsAlgorithm}.
+	 * Returns a new {@link Builder}, initialized with the provided {@link JwaAlgorithm}.
 	 *
-	 * @param jwsAlgorithm the {@link JwsAlgorithm}
+	 * @param jwaAlgorithm the {@link JwaAlgorithm}
 	 * @return the {@link Builder}
 	 */
-	public static Builder withAlgorithm(JwsAlgorithm jwsAlgorithm) {
-		return new Builder(jwsAlgorithm);
+	public static Builder withAlgorithm(JwaAlgorithm jwaAlgorithm) {
+		return new Builder(jwaAlgorithm);
 	}
 
 	/**
@@ -213,9 +217,8 @@ public static final class Builder {
 		private Builder() {
 		}
 
-		private Builder(JwsAlgorithm jwsAlgorithm) {
-			Assert.notNull(jwsAlgorithm, "jwsAlgorithm cannot be null");
-			header(JoseHeaderNames.ALG, jwsAlgorithm);
+		private Builder(JwaAlgorithm jwaAlgorithm) {
+			algorithm(jwaAlgorithm);
 		}
 
 		private Builder(JoseHeader headers) {
@@ -224,24 +227,25 @@ private Builder(JoseHeader headers) {
 		}
 
 		/**
-		 * Sets the {@link JwsAlgorithm JWS algorithm} used to digitally sign the JWS.
+		 * Sets the {@link JwaAlgorithm JWA algorithm} used to digitally sign the JWS or encrypt the JWE.
 		 *
-		 * @param jwsAlgorithm the JWS algorithm
+		 * @param jwaAlgorithm the {@link JwaAlgorithm}
 		 * @return the {@link Builder}
 		 */
-		public Builder jwsAlgorithm(JwsAlgorithm jwsAlgorithm) {
-			return header(JoseHeaderNames.ALG, jwsAlgorithm);
+		public Builder algorithm(JwaAlgorithm jwaAlgorithm) {
+			Assert.notNull(jwaAlgorithm, "jwaAlgorithm cannot be null");
+			return header(JoseHeaderNames.ALG, jwaAlgorithm);
 		}
 
 		/**
 		 * Sets the JWK Set URL that refers to the resource of a set of JSON-encoded public keys,
 		 * one of which corresponds to the key used to digitally sign the JWS or encrypt the JWE.
 		 *
-		 * @param jwkSetUri the JWK Set URL
+		 * @param jwkSetUrl the JWK Set URL
 		 * @return the {@link Builder}
 		 */
-		public Builder jwkSetUri(String jwkSetUri) {
-			return header(JoseHeaderNames.JKU, jwkSetUri);
+		public Builder jwkSetUrl(String jwkSetUrl) {
+			return header(JoseHeaderNames.JKU, convertAsURL(JoseHeaderNames.JKU, jwkSetUrl));
 		}
 
 		/**
@@ -269,16 +273,19 @@ public Builder keyId(String keyId) {
 		 * Sets the X.509 URL that refers to the resource for the X.509 public key certificate
 		 * or certificate chain corresponding to the key used to digitally sign the JWS or encrypt the JWE.
 		 *
-		 * @param x509Uri the X.509 URL
+		 * @param x509Url the X.509 URL
 		 * @return the {@link Builder}
 		 */
-		public Builder x509Uri(String x509Uri) {
-			return header(JoseHeaderNames.X5U, x509Uri);
+		public Builder x509Url(String x509Url) {
+			return header(JoseHeaderNames.X5U, convertAsURL(JoseHeaderNames.X5U, x509Url));
 		}
 
 		/**
 		 * Sets the X.509 certificate chain that contains the X.509 public key certificate
-		 * or certificate chain corresponding to the key used to digitally sign the JWS or encrypt the JWE.
+		 * or certificate chain corresponding to the key used to digitally sign the JWS or
+		 * encrypt the JWE. The certificate or certificate chain is represented as a
+		 * {@code List} of certificate value {@code String}s. Each {@code String} in the
+		 * {@code List} is a Base64-encoded DER PKIX certificate value.
 		 *
 		 * @param x509CertificateChain the X.509 certificate chain
 		 * @return the {@link Builder}
@@ -309,17 +316,6 @@ public Builder x509SHA256Thumbprint(String x509SHA256Thumbprint) {
 			return header(JoseHeaderNames.X5T_S256, x509SHA256Thumbprint);
 		}
 
-		/**
-		 * Sets the critical headers that indicates which extensions to the JWS/JWE/JWA specifications
-		 * are being used that MUST be understood and processed.
-		 *
-		 * @param headerNames the critical header names
-		 * @return the {@link Builder}
-		 */
-		public Builder critical(Set<String> headerNames) {
-			return header(JoseHeaderNames.CRIT, headerNames);
-		}
-
 		/**
 		 * Sets the type header that declares the media type of the JWS/JWE.
 		 *
@@ -340,6 +336,17 @@ public Builder contentType(String contentType) {
 			return header(JoseHeaderNames.CTY, contentType);
 		}
 
+		/**
+		 * Sets the critical headers that indicates which extensions to the JWS/JWE/JWA specifications
+		 * are being used that MUST be understood and processed.
+		 *
+		 * @param headerNames the critical header names
+		 * @return the {@link Builder}
+		 */
+		public Builder critical(Set<String> headerNames) {
+			return header(JoseHeaderNames.CRIT, headerNames);
+		}
+
 		/**
 		 * Sets the header.
 		 *
@@ -373,19 +380,15 @@ public Builder headers(Consumer<Map<String, Object>> headersConsumer) {
 		 */
 		public JoseHeader build() {
 			Assert.notEmpty(this.headers, "headers cannot be empty");
-			convertAsURL(JoseHeaderNames.JKU);
-			convertAsURL(JoseHeaderNames.X5U);
 			return new JoseHeader(this.headers);
 		}
 
-		private void convertAsURL(String header) {
-			Object value = this.headers.get(header);
-			if (value != null) {
-				URL convertedValue = ClaimConversionService.getSharedInstance().convert(value, URL.class);
-				Assert.isTrue(convertedValue != null,
-						() -> "Unable to convert header '" + header + "' of type '" + value.getClass() + "' to URL.");
-				this.headers.put(header, convertedValue);
-			}
+		private static URL convertAsURL(String header, String value) {
+			URL convertedValue = ClaimConversionService.getSharedInstance().convert(value, URL.class);
+			Assert.isTrue(convertedValue != null,
+					() -> "Unable to convert header '" + header + "' of type '" + value.getClass() + "' to URL.");
+			return convertedValue;
 		}
+
 	}
 }

oauth2-authorization-server/src/main/java/org/springframework/security/oauth2/jwt/JwtClaimsSet.java

@@ -15,13 +15,15 @@
  */
 package org.springframework.security.oauth2.jwt;
 
+import java.net.URL;
 import java.time.Instant;
 import java.util.Collections;
 import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
 import java.util.function.Consumer;
 
+import org.springframework.security.oauth2.core.converter.ClaimConversionService;
 import org.springframework.util.Assert;
 
 /**
@@ -32,7 +34,7 @@
  * @since 0.0.1
  * @see Jwt
  * @see JwtClaimAccessor
- * @see <a target="_blank" href="https://tools.ietf.org/html/rfc7519#section-4">JWT Claims Set</a>
+ * @see <a target="_blank" href="https://datatracker.ietf.org/doc/html/rfc7519#section-4">JWT Claims Set</a>
  */
 public final class JwtClaimsSet implements JwtClaimAccessor {
 	private final Map<String, Object> claims;
@@ -166,10 +168,10 @@ public Builder claim(String name, Object value) {
 		}
 
 		/**
-		 * A {@code Consumer} to be provided access to the claims set
+		 * A {@code Consumer} to be provided access to the claims
 		 * allowing the ability to add, replace, or remove.
 		 *
-		 * @param claimsConsumer a {@code Consumer} of the claims set
+		 * @param claimsConsumer a {@code Consumer} of the claims
 		 */
 		public Builder claims(Consumer<Map<String, Object>> claimsConsumer) {
 			claimsConsumer.accept(this.claims);
@@ -183,6 +185,17 @@ public Builder claims(Consumer<Map<String, Object>> claimsConsumer) {
 		 */
 		public JwtClaimsSet build() {
 			Assert.notEmpty(this.claims, "claims cannot be empty");
+
+			// The value of the 'iss' claim is a String or URL (StringOrURI).
+			// Attempt to convert to URL.
+			Object issuer = this.claims.get(JwtClaimNames.ISS);
+			if (issuer != null) {
+				URL convertedValue = ClaimConversionService.getSharedInstance().convert(issuer, URL.class);
+				if (convertedValue != null) {
+					this.claims.put(JwtClaimNames.ISS, convertedValue);
+				}
+			}
+
 			return new JwtClaimsSet(this.claims);
 		}
 	}

oauth2-authorization-server/src/main/java/org/springframework/security/oauth2/jwt/JwtEncoder.java

@@ -32,11 +32,11 @@
  * @see JoseHeader
  * @see JwtClaimsSet
  * @see JwtDecoder
- * @see <a target="_blank" href="https://tools.ietf.org/html/rfc7519">JSON Web Token (JWT)</a>
- * @see <a target="_blank" href="https://tools.ietf.org/html/rfc7515">JSON Web Signature (JWS)</a>
- * @see <a target="_blank" href="https://tools.ietf.org/html/rfc7516">JSON Web Encryption (JWE)</a>
- * @see <a target="_blank" href="https://tools.ietf.org/html/rfc7515#section-3.1">JWS Compact Serialization</a>
- * @see <a target="_blank" href="https://tools.ietf.org/html/rfc7516#section-3.1">JWE Compact Serialization</a>
+ * @see <a target="_blank" href="https://datatracker.ietf.org/doc/html/rfc7519">JSON Web Token (JWT)</a>
+ * @see <a target="_blank" href="https://datatracker.ietf.org/doc/html/rfc7515">JSON Web Signature (JWS)</a>
+ * @see <a target="_blank" href="https://datatracker.ietf.org/doc/html/rfc7516">JSON Web Encryption (JWE)</a>
+ * @see <a target="_blank" href="https://datatracker.ietf.org/doc/html/rfc7515#section-3.1">JWS Compact Serialization</a>
+ * @see <a target="_blank" href="https://datatracker.ietf.org/doc/html/rfc7516#section-3.1">JWE Compact Serialization</a>
  */
 @FunctionalInterface
 public interface JwtEncoder {