001package com.nimbusds.openid.connect.provider.spi.tokens;
002
003
004import com.nimbusds.langtag.LangTag;
005import com.nimbusds.oauth2.sdk.Scope;
006import com.nimbusds.oauth2.sdk.auth.X509CertificateConfirmation;
007import com.nimbusds.oauth2.sdk.dpop.JWKThumbprintConfirmation;
008import com.nimbusds.oauth2.sdk.id.*;
009import com.nimbusds.openid.connect.sdk.SubjectType;
010import net.minidev.json.JSONObject;
011import org.checkerframework.checker.nullness.qual.Nullable;
012
013import java.time.Instant;
014import java.util.List;
015import java.util.Map;
016import java.util.Set;
017
018
019/**
020 * Access token authorisation.
021 */
022public interface AccessTokenAuthorization {
023        
024        
025        /**
026         * Returns the access token subject.
027         *
028         * @return The subject, {@code null} if not specified.
029         */
030        @Nullable Subject getSubject();
031        
032        
033        /**
034         * Returns the access token actor, in impersonation and delegation
035         * scenarios.
036         *
037         * @return The actor, {@code null} if not specified.
038         */
039        @Nullable Actor getActor();
040        
041        
042        /**
043         * Returns the identifier of the client to which the access token is
044         * issued.
045         *
046         * @return The client identifier, {@code null} if not specified.
047         */
048        @Nullable ClientID getClientID();
049        
050        
051        /**
052         * Returns the scope of the access token.
053         *
054         * @return The scope, {@code null} if not specified.
055         */
056        @Nullable Scope getScope();
057        
058        
059        /**
060         * Returns the expiration time of the access token.
061         *
062         * @return The expiration time, {@code null} if not specified.
063         */
064        @Nullable Instant getExpirationTime();
065        
066        
067        /**
068         * Returns the issue time of the access token.
069         *
070         * @return The issue time, {@code null} if not specified.
071         */
072        @Nullable Instant getIssueTime();
073        
074        
075        /**
076         * Returns the issuer of the access token.
077         *
078         * @return The issuer, {@code null} if not specified.
079         */
080        @Nullable Issuer getIssuer();
081        
082        
083        /**
084         * Returns the audience list of the access token, which may be the
085         * logical names of the intended resource servers.
086         *
087         * @return The audience list, {@code null} if not specified.
088         */
089        @Nullable List<Audience> getAudienceList();
090        
091        
092        /**
093         * Returns the access token subject type.
094         *
095         * @return The subject type, {@code null} if not specified (may imply
096         *         {@link SubjectType#PUBLIC public}).
097         */
098        default @Nullable SubjectType getSubjectType() {
099                return null;
100        }
101        
102        
103        /**
104         * Returns the access token local subject. Equals the
105         * {@link #getSubject()} value unless the {@link #getSubjectType()
106         * subject type} is pairwise.
107         *
108         * <p>Use this method if there is a need to get the local (system)
109         * subject for an access token which subject was made pairwise for its
110         * audience (resource server).
111         *
112         * <p>Note, an access token which subject is made pairwise must not
113         * have its local subject exposed in introspection responses intended
114         * for the token audience!
115         *
116         * @return The local subject, {@code null} if not specified or for a
117         *         pairwise {@link #getSubjectType() subject type} that
118         *         couldn't be reversed.
119         */
120        default @Nullable Subject getLocalSubject() {
121                if (SubjectType.PUBLIC == getSubjectType()) {
122                        return getSubject();
123                } else {
124                        return null;
125                }
126        }
127        
128        
129        /**
130         * Returns the JSON Web Token (JWT) identifier of the access token.
131         *
132         * @return The JWT ID, {@code null} if not specified or applicable.
133         */
134        @Nullable JWTID getJWTID();
135        
136        
137        /**
138         * Returns the names of the consented OpenID claims to be accessed at
139         * the UserInfo endpoint.
140         *
141         * @return The claim names, {@code null} if not specified.
142         */
143        @Nullable Set<String> getClaimNames();
144        
145        
146        /**
147         * Returns the preferred locales for the consented OpenID claims.
148         *
149         * @return The preferred claims locales, {@code null} if not specified.
150         */
151        @Nullable List<LangTag> getClaimsLocales();
152        
153        
154        /**
155         * Returns the preset OpenID claims to be included in the UserInfo
156         * response.
157         *
158         * @return The preset OpenID claims, {@code null} if not specified.
159         */
160        @Nullable JSONObject getPresetClaims();
161        
162        
163        /**
164         * Returns the optional data for the access token.
165         *
166         * @return The optional data, represented as a JSON object,
167         *         {@code null} if not specified.
168         */
169        @Nullable JSONObject getData();
170        
171        
172        /**
173         * Returns the client X.509 certificate confirmation (SHA-256
174         * thumbprint) for mutual TLS.
175         *
176         * @return The client X.509 certificate confirmation, {@code null} if
177         *         none.
178         */
179        @Nullable X509CertificateConfirmation getClientCertificateConfirmation();
180        
181        
182        /**
183         * Returns the JWK SHA-256 thumbprint confirmation for DPoP.
184         *
185         * @return The JWK thumbprint confirmation, {@code null} if none.
186         */
187        default @Nullable JWKThumbprintConfirmation getJWKThumbprintConfirmation() {
188                return null;
189        }
190        
191        
192        /**
193         * Returns a map of other top-level parameters.
194         *
195         * @return Other top-level parameters, the values should map to JSON
196         *         entities, {@code null} if none.
197         */
198        default @Nullable Map<String,Object> getOtherTopLevelParameters() {
199                return null;
200        }
201        
202        
203        /**
204         * Returns the optional OpenID claims fulfillment data.
205         *
206         * @return The OpenID claims fulfillment data, {@code null} if not
207         *         specified.
208         */
209        default @Nullable JSONObject getClaimsData() {
210                return null;
211        }
212
213
214        /**
215         * Returns the associated subject (end-user) session key (session ID
216         * with omitted HMAC).
217         *
218         * @return The subject session key, {@code null} if not available.
219         */
220        default @Nullable String getSubjectSessionKey() {
221                return null;
222        }
223}