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, {@code false} if the client
057         *                           is public.
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}