001package com.nimbusds.openid.connect.provider.spi.tokens;
002
003
004import net.jcip.annotations.ThreadSafe;
005
006import com.nimbusds.jose.JOSEObjectType;
007import com.nimbusds.jwt.JWTClaimsSet;
008
009
010/**
011 * Service Provider Interface (SPI) for encoding and decoding authorisations
012 * for self-contained access tokens into JWT claims sets. Implementations must
013 * be thread-safe.
014 *
015 * <p>Sample JWT claims set for a self-contained access token:
016 *
017 * <pre>
018 * {
019 *  "sub" : "alice",
020 *  "cid" : "65564eb0058d",
021 *  "scp" : [ "openid", "email", "app:write" ],
022 *  "iss" : "https://c2id.com",
023 *  "iat" : 1360050000,
024 *  "exp" : 1360050795,
025 *  "aud" : [ "https://resource-1.example.com", "https://resource-2.example.com" ]
026 * }
027 * </pre>
028 *
029 * <p>Implementations should extend {@link BaseSelfContainedAccessTokenClaimsCodec}
030 * which encodes all token parameters for which there is an appropriate
031 * standard JWT claim, such as for the subject, issuer and expiration time. The
032 * implementation only needs to specify encodings for the remaining parameters,
033 * such as scope and client ID.
034 */
035@ThreadSafe
036public interface SelfContainedAccessTokenClaimsCodec {
037        
038        
039        /**
040         * Encodes the specified access token authorisation into a JWT claims
041         * set.
042         *
043         * @param tokenAuthz The access token authorisation. Not {@code null}.
044         * @param context    The token encoder context. Not {@code null}.
045         *
046         * @return The JWT claims set.
047         */
048        JWTClaimsSet encode(final AccessTokenAuthorization tokenAuthz, final TokenEncoderContext context);
049        
050        
051        /**
052         * Encodes the specified access token authorisation into a JWT.
053         *
054         * @param tokenAuthz The access token authorisation. Not {@code null}.
055         * @param context    The token encoder context. Not {@code null}.
056         *
057         * @return The JWT claims set and other details.
058         */
059        default JWTDetails advancedEncode(final AccessTokenAuthorization tokenAuthz, final TokenEncoderContext context) {
060                return new JWTDetails() {
061                        @Override
062                        public JOSEObjectType getType() {
063                                return null;
064                        }
065                        
066                        
067                        @Override
068                        public JWTClaimsSet getJWTClaimsSet() {
069                                return encode(tokenAuthz, context);
070                        }
071                };
072        }
073        
074        
075        /**
076         * Decodes the specified JWT claims set into an access token
077         * authorisation.
078         *
079         * @param claimsSet The JWT claims set. Not {@code null}.
080         * @param context   The token codec context. Not {@code null}.
081         *
082         * @return The access token authorisation.
083         *
084         * @throws TokenDecodeException If decoding failed.
085         */
086        AccessTokenAuthorization decode(final JWTClaimsSet claimsSet, final TokenCodecContext context)
087                throws TokenDecodeException;
088        
089        
090        /**
091         * Decodes the specified JWT details into an access token
092         * authorisation.
093         *
094         * @param jwtDetails The JWT claims set and other details. Not
095         *                   {@code null}.
096         * @param context    The token codec context. Not {@code null}.
097         *
098         * @return The access token authorisation.
099         *
100         * @throws TokenDecodeException If decoding failed.
101         */
102        default AccessTokenAuthorization advancedDecode(final JWTDetails jwtDetails, final TokenCodecContext context)
103                throws TokenDecodeException {
104                
105                return decode(jwtDetails.getJWTClaimsSet(), context);
106        }
107}