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