001package com.nimbusds.openid.connect.provider.spi.claims;
002
003
004import com.nimbusds.openid.connect.provider.spi.internal.sessionstore.SubjectSession;
005import net.minidev.json.JSONObject;
006import org.checkerframework.checker.nullness.qual.Nullable;
007
008import com.nimbusds.oauth2.sdk.id.ClientID;
009import com.nimbusds.oauth2.sdk.token.AccessToken;
010import com.nimbusds.openid.connect.provider.spi.InvocationContext;
011import com.nimbusds.openid.connect.provider.spi.tokens.TokenEncoderContext;
012import com.nimbusds.openid.connect.sdk.claims.ClaimsTransport;
013
014
015/**
016 * OpenID Connect claims request context. The supplied context parameters can
017 * be used in the processing and accounting of a claims request.
018 */
019public interface ClaimsSourceRequestContext extends InvocationContext {
020        
021        
022        /**
023         * Returns the claims transport, if applicable.
024         *
025         * @return {@link ClaimsTransport#USERINFO UserInfo} or
026         *         {@link ClaimsTransport#ID_TOKEN ID token}, {@code null} if
027         *         the claims source SPI is invoked for another purpose (e.g.
028         *         in a {@link TokenEncoderContext}).
029         */
030        ClaimsTransport getClaimsTransport();
031        
032        
033        /**
034         * Returns the optional claims fulfillment data.
035         *
036         * @return The claims fulfillment data, {@code null} if not specified.
037         */
038        @Nullable JSONObject getClaimsData();
039
040
041        /**
042         * Returns the identifier of the OAuth 2.0 client (client_id).
043         *
044         * @return The client ID. Not {@code null}.
045         */
046        ClientID getClientID();
047        
048        
049        /**
050         * Returns the client IP address.
051         *
052         * @return The client IP address, {@code null} if not available.
053         */
054        @Nullable String getClientIPAddress();
055        
056        
057        /**
058         * Returns the received and successfully validated UserInfo access
059         * token for the claims request. If a claims request is triggered in a
060         * OpenID Connect implicit and hybrid flows, where the claims are
061         * returned as part of the ID token, an access token is not involved
062         * and hence not returned by this method.
063         *
064         * <p>The claims source may use the UserInfo access token for the
065         * retrieval of aggregated and distributed claims, where the same token
066         * is recognised by the upstream claims providers. See OpenID Connect
067         * Core 1.0, section 5.6.
068         *
069         * @return The UserInfo access token, {@code null} if the claims
070         *         request wasn't triggered by a UserInfo request.
071         */
072        @Nullable AccessToken getUserInfoAccessToken();
073
074
075        /**
076         * Returns the associated subject (end-user) session where the claims
077         * sourcing was authorised.
078         *
079         * <p>The subject session is supplied in the following cases:
080         *
081         * <ul>
082         *     <li>Claims sourcing for the UserInfo endpoint where the subject
083         *         session where the claims consent occurred is still present
084         *         (not expired or closed)
085         *     <li>Claims sourcing for ID token issue in response to an OAuth
086         *         2.0 authorisation code, implicit (including OpenID Connect
087         *         hybrid response type) and refresh token grants.
088         *     <li>Claims sourcing for a direct authorisation request where a
089         *         valid subject session ID was supplied, or a new subject
090         *         session was created.
091         * </ul>
092         *
093         * @return The subject session, {@code null} if closed or expired, or
094         *         not available (due to the session key not being encoded into
095         *         the access token where applicable, or other reasons).
096         */
097        @Nullable SubjectSession getSubjectSession();
098}