Introduce JWT Builder API

api/src/main/java/org/eclipse/microprofile/jwt/algorithm/ContentEncryptionAlgorithm.java

@@ -0,0 +1,37 @@
+/*
+ * Copyright (c) 2016-2017 Contributors to the Eclipse Foundation
+ *
+ *  See the NOTICE file(s) distributed with this work for additional
+ *  information regarding copyright ownership.
+ *
+ *  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.
+ *
+ */
+package org.eclipse.microprofile.jwt.algorithm;
+
+/**
+ * * JWT JSON Web Content Encryption Algorithms which must be supported.
+ * 
+ * @see <a href="https://tools.ietf.org/html/rfc7518#section-5">https://tools.ietf.org/html/rfc7518#section-5</a>
+ */
+public enum ContentEncryptionAlgorithm {
+    /**
+     * AES GCM using 256-bit key.
+     */
+    A256GCM;
+
+
+    public String getAlgorithm() {
+        return name();
+    }
+}

api/src/main/java/org/eclipse/microprofile/jwt/algorithm/KeyEncryptionAlgorithm.java

@@ -0,0 +1,42 @@
+/*
+ * Copyright (c) 2016-2017 Contributors to the Eclipse Foundation
+ *
+ *  See the NOTICE file(s) distributed with this work for additional
+ *  information regarding copyright ownership.
+ *
+ *  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.
+ *
+ */
+package org.eclipse.microprofile.jwt.algorithm;
+
+/**
+ * JWT JSON Web Key Encryption (Management) Algorithms which must be supported.
+ * 
+ * @see <a href="https://tools.ietf.org/html/rfc7518#section-4">https://tools.ietf.org/html/rfc7518#section-4</a>
+ */
+public enum KeyEncryptionAlgorithm {
+    /**
+     *  RSA with Optimal Asymmetric Encryption Padding
+     */
+    RSA_OAEP("RSA-OAEP");
+
+    private String algorithmName;
+
+    KeyEncryptionAlgorithm(String algorithmName) {
+        this.algorithmName = algorithmName;
+    }
+
+    public String getAlgorithm() {
+        return algorithmName;
+    }
+}

api/src/main/java/org/eclipse/microprofile/jwt/algorithm/SignatureAlgorithm.java

@@ -0,0 +1,40 @@
+/*
+ * Copyright (c) 2016-2017 Contributors to the Eclipse Foundation
+ *
+ *  See the NOTICE file(s) distributed with this work for additional
+ *  information regarding copyright ownership.
+ *
+ *  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.
+ *
+ */
+package org.eclipse.microprofile.jwt.algorithm;
+
+/**
+ * JWT JSON Web Signature Algorithms which must be supported.
+ * 
+ * @see <a href="https://tools.ietf.org/html/rfc7518#section-3">https://tools.ietf.org/html/rfc7518#section-3</a>
+ */
+public enum SignatureAlgorithm {
+    /**
+     * RSASSA-PKCS1-v1_5 using SHA-256
+     */
+    RS256,
+    /**
+     * ECDSA using P-256 and SHA-256
+     */
+    ES256;
+
+    public String getAlgorithm() {
+        return name();
+    }
+}

api/src/main/java/org/eclipse/microprofile/jwt/builder/Jwt.java

@@ -0,0 +1,93 @@
+/*
+ * Copyright (c) 2016-2017 Contributors to the Eclipse Foundation
+ *
+ *  See the NOTICE file(s) distributed with this work for additional
+ *  information regarding copyright ownership.
+ *
+ *  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.
+ *
+ */
+package org.eclipse.microprofile.jwt.builder;
+
+import java.util.Map;
+
+import org.eclipse.microprofile.jwt.builder.spi.JwtProvider;
+
+/**
+ * Factory class for creating {@link JwtClaimsBuilder} which produces
+ * signed, encrypted or signed first and then encrypted JWT tokens.
+ *
+ * <p>
+ * The following example shows how to initialize a {@link JwtClaimsBuilder} from an existing resource
+ * containing the claims in a JSON format and produce a signed JWT token with a configured signing key:
+ * 
+ * <pre>
+ * <code>
+ * String = Jwt.claims("/tokenClaims.json").sign();
+ * </code>
+ * </pre>
+ * <p>
+ * The next example shows how to use {@link JwtClaimsBuilder} to add the claims and encrypt a JSON
+ * representation of these claims with a configured encrypting key:
+ * 
+ * <pre>
+ * <code>
+ * String = Jwt.claims().issuer("https://issuer.org").claim("custom-claim", "custom-value").encrypt();
+ * </code>
+ * </pre>
+ * <p>
+ * The final example shows how to initialize a {@link JwtClaimsBuilder} from an existing resource
+ * containing the claims in a JSON format, produce an inner signed JWT token with a configured signing key
+ * and encrypt it with a configured encrypting key.
+ * 
+ * <pre>
+ * <code>
+ * String = Jwt.claims("/tokenClaims.json").innerSign().encrypt();
+ * </code>
+ * </pre>
+ */
+public final class Jwt {
+    private Jwt() {
+
+    }
+    /**
+     * Creates a new instance of {@link JwtClaimsBuilder}
+     *
+     * @return {@link JwtClaimsBuilder}
+     */
+    public static JwtClaimsBuilder claims() {
+        return JwtProvider.provider().claims();
+    }
+
+    /**
+     * Creates a new instance of {@link JwtClaimsBuilder} from a map of claims.
+     * 
+     * @param claims the map with the claim name and value pairs. Claim value is converted to String unless it is
+     *        an instance of {@code Boolean}, {@code Number}, {@code Collection}, {@code Map},
+     *        {@code JsonObject} or {@code JsonArray}.
+     * @return {@link JwtClaimsBuilder}
+     */
+    public static JwtClaimsBuilder claims(Map<String, Object> claims) {
+        return JwtProvider.provider().claims(claims);
+    }
+
+    /**
+     * Creates a new instance of {@link JwtClaimsBuilder} from a JSON resource.
+     * 
+     * @param jsonLocation JSON resource location
+     * @return {@link JwtClaimsBuilder}
+     */
+    public static JwtClaimsBuilder claims(String jsonLocation) {
+        return JwtProvider.provider().claims(jsonLocation);
+    }
+}

api/src/main/java/org/eclipse/microprofile/jwt/builder/JwtClaimsBuilder.java

@@ -0,0 +1,153 @@
+/*
+ * Copyright (c) 2016-2017 Contributors to the Eclipse Foundation
+ *
+ *  See the NOTICE file(s) distributed with this work for additional
+ *  information regarding copyright ownership.
+ *
+ *  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.
+ *
+ */
+package org.eclipse.microprofile.jwt.builder;
+
+import java.util.Set;
+
+/**
+ * JWT Claims Builder.
+ * 
+ * <p>
+ * JwtClaimsBuilder implementations must set the 'iat' (issued at time), 'exp' (expiration time)
+ * and 'jit' (unique token identifier) claims unless they have already been set.
+ * <p>
+ * Note that JwtClaimsBuilder implementations are not expected to be thread-safe.
+ * 
+ * @see <a href="https://tools.ietf.org/html/rfc7519">RFC7515</a>
+ */
+public interface JwtClaimsBuilder extends JwtSignature {
+
+    /**
+     * Set an issuer 'iss' claim
+     * 
+     * @param issuer the issuer
+     * @return JwtClaimsBuilder
+     */
+    JwtClaimsBuilder issuer(String issuer);
+
+    /**
+     * Set a subject 'sub' claim
+     * 
+     * @param subject the subject
+     * @return JwtClaimsBuilder
+     */
+    JwtClaimsBuilder subject(String subject);
+
+    /**
+     * Set a 'upn' claim
+     * 
+     * @param upn the upn
+     * @return JwtClaimsBuilder
+     */
+    JwtClaimsBuilder upn(String upn);
+
+    /**
+     * Set a preferred user name 'preferred_username' claim
+     * 
+     * @param preferredUserName the preferred user name
+     * @return JwtClaimsBuilder
+     */
+    JwtClaimsBuilder preferredUserName(String preferredUserName);
+
+    /**
+     * Set an issuedAt 'iat' claim
+     * 
+     * @param issuedAt the issuedAt time in seconds
+     * @return JwtClaimsBuilder
+     */
+    JwtClaimsBuilder issuedAt(long issuedAt);
+
+    /**
+     * Set an expiry 'exp' claim
+     * 
+     * @param expiredAt the expiry time
+     * @return JwtClaimsBuilder
+     */
+    JwtClaimsBuilder expiresAt(long expiredAt);
+
+    /**
+     * Set a single value 'groups' claim
+     * 
+     * @param group the groups
+     * @return JwtClaimsBuilder
+     */
+    JwtClaimsBuilder groups(String group);
+
+    /**
+     * Set a multiple value 'groups' claim
+     * 
+     * @param groups the groups
+     * @return JwtClaimsBuilder
+     */
+    JwtClaimsBuilder groups(Set<String> groups);
+
+    /**
+     * Set a single value audience 'aud' claim
+     * 
+     * @param audience the audience
+     * @return JwtClaimsBuilder
+     */
+    JwtClaimsBuilder audience(String audience);
+
+    /**
+     * Set a multiple value audience 'aud' claim
+     * 
+     * @param audiences the audiences
+     * @return JwtClaimsBuilder
+     */
+    JwtClaimsBuilder audience(Set<String> audiences);
+
+    /**
+     * Set a custom claim. Claim value is converted to String unless it is
+     * an instance of {@code Boolean}, {@code Number}, {@code Collection}, {@code Map},
+     * {@code JsonObject} or {@code JsonArray}.
+     * 
+     * @param name the claim name
+     * @param value the claim value
+     * @return JwtClaimsBuilder
+     */
+    JwtClaimsBuilder claim(String name, Object value);
+
+    /**
+     * Return a JSON representation of the claims before they have been signed or encrypted.
+     * Note that the 'iat' (issued at time), 'exp' (expiration time) and 'jit' (unique token identifier) claims
+     * must be set if they have not already been set before creating a JSON representation to ensure it is consistent
+     * with what will be signed or encrypted.
+     * This method will return the same JSON representation if called multiple times unless some new claims have
+     * been added since the previous call.
+     *
+     * @return the JSON representation
+     */
+    String json();
+
+    /**
+     * Set JsonWebSignature headers and sign the claims by moving to {@link JwtSignatureBuilder}
+     * 
+     * @return JwtSignatureBuilder
+     */
+    JwtSignatureBuilder jws();
+
+    /**
+     * Set JsonWebEncryption headers and encrypt the claims by moving to {@link JwtEncryptionBuilder}
+     * 
+     * @return JwtSignatureBuilder
+     */
+    JwtEncryptionBuilder jwe();
+}