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}