001package com.nimbusds.openid.connect.provider.spi.grants; 002 003 004import net.jcip.annotations.ThreadSafe; 005 006import com.nimbusds.oauth2.sdk.GeneralException; 007import com.nimbusds.oauth2.sdk.GrantType; 008import com.nimbusds.oauth2.sdk.id.ClientID; 009import com.nimbusds.oauth2.sdk.tokenexchange.TokenExchangeGrant; 010import com.nimbusds.openid.connect.provider.spi.InvocationContext; 011import com.nimbusds.openid.connect.sdk.rp.OIDCClientMetadata; 012 013 014/** 015 * Service Provider Interface (SPI) for handling token exchange grants. Returns 016 * a {@link TokenExchangeAuthorization token exchange authorisation} on 017 * success. Must throw a {@link GeneralException} with an 018 * {@link com.nimbusds.oauth2.sdk.OAuth2Error#INVALID_GRANT invalid_grant} 019 * error code if the {@code subject_token} or the optional {@code actor_token} 020 * are invalid. 021 * 022 * <p>Implementations must be thread-safe. 023 * 024 * <p>Related specifications: 025 * 026 * <ul> 027 * <li>OAuth 2.0 Token Exchange (RFC 8693). 028 * </ul> 029 */ 030@ThreadSafe 031public interface TokenExchangeGrantHandler extends GrantHandler { 032 033 034 /** 035 * The handled grant type. 036 */ 037 GrantType GRANT_TYPE = GrantType.TOKEN_EXCHANGE; 038 039 040 @Override 041 default GrantType getGrantType() { 042 return GRANT_TYPE; 043 } 044 045 046 /** 047 * Handles a token exchange request from a client registered with the 048 * Connect2id server. 049 * 050 * @param grant The token exchange grant. Not 051 * {@code null}. 052 * @param tokenRequestParams The token request parameters, such as the 053 * requested scope. Not {@code null}. 054 * @param clientID The client identifier. Not {@code null}. 055 * @param confidentialClient {@code true} if the client is 056 * confidential and has been authenticated, 057 * else {@code false}. 058 * @param clientMetadata The OpenID Connect client metadata. Not 059 * {@code null}. 060 * @param tokenIntrospection Token introspection interface for locally 061 * issued subject tokens. Not {@code null}. 062 * @param tokenIssueHelpers Token issue helpers. Not {@code null}. 063 * @param invocationCtx The invocation context. Not {@code null}. 064 * 065 * @return The authorisation. 066 * 067 * @throws GeneralException If the grant is invalid, or another 068 * exception was encountered. 069 */ 070 TokenExchangeAuthorization processGrant(final TokenExchangeGrant grant, 071 final TokenRequestParameters tokenRequestParams, 072 final ClientID clientID, 073 final boolean confidentialClient, 074 final OIDCClientMetadata clientMetadata, 075 final TokenIntrospection tokenIntrospection, 076 final TokenIssueHelpers tokenIssueHelpers, 077 final InvocationContext invocationCtx) 078 throws GeneralException; 079}