001/*
002 * (C) Copyright 2018 Nuxeo (http://nuxeo.com/) and others.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *     http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 *
016 * Contributors:
017 *     Florent Guillaume
018 */
019package org.nuxeo.ecm.jwt;
020
021import java.util.Map;
022
023/**
024 * The JSON Web Token (JWT) Service.
025 *
026 * @since 10.3
027 */
028public interface JWTService {
029
030    /**
031     * A builder for a JSON Web Token (JWT).
032     *
033     * @since 10.3
034     */
035    interface JWTBuilder {
036
037        /**
038         * Adds a TTL (in seconds) to the token to be built.
039         * <p>
040         * A negative or zero TTL means to use the platform default.
041         *
042         * @param ttlSeconds the TTL, in seconds
043         */
044        JWTBuilder withTTL(int ttlSeconds);
045
046        /**
047         * Adds a claim to the token to be built. The standard claim names are available in {@link JWTClaims}.
048         *
049         * @param name the claim name
050         * @param value the claim value
051         */
052        JWTBuilder withClaim(String name, Object value);
053
054        /**
055         * Builds and returns the token.
056         * <p>
057         * The {@link JWTClaims#CLAIM_SUBJECT} of the token is set to the current user id. The
058         * {@link JWTClaims#CLAIM_ISSUER} of the token is set to the string {@code "nuxeo"}.
059         * <p>
060         * The token hash algorithm is based on a secret provided by the service configuration.
061         *
062         * @return the token
063         */
064        String build();
065
066    }
067
068    /**
069     * Creates a new builder for a JSON Web Token.
070     *
071     * @return the new builder
072     */
073    JWTBuilder newBuilder();
074
075    /**
076     * Verifies the token and returns its claims, or {@code null} if the token is invalid (corrupted, constructed from
077     * an invalid secret, or expired).
078     * <p>
079     * The claim {@link JWTClaims#CLAIM_SUBJECT} contains the token's creator user id.
080     * <p>
081     * The token hash algorithm is based on a secret provided by the service configuration.
082     *
083     * @param token the token
084     * @return the claims if the token is valid, or {@code null} if the token is invalid
085     */
086    Map<String, Object> verifyToken(String token);
087
088}