001package com.nimbusds.openid.connect.provider.spi.grants;
002
003
004import net.jcip.annotations.ThreadSafe;
005import org.checkerframework.checker.nullness.qual.Nullable;
006
007import com.nimbusds.oauth2.sdk.GeneralException;
008import com.nimbusds.oauth2.sdk.GrantType;
009import com.nimbusds.oauth2.sdk.Scope;
010import com.nimbusds.oauth2.sdk.client.ClientMetadata;
011import com.nimbusds.oauth2.sdk.id.ClientID;
012import com.nimbusds.openid.connect.provider.spi.InvocationContext;
013
014
015/**
016 * Service Provider Interface (SPI) for handling OAuth 2.0 client credentials
017 * grants. Returns the matching {@link GrantAuthorization authorisation} on
018 * success.
019 *
020 * <p>Implementations must be thread-safe.
021 *
022 * <p>Related specifications:
023 *
024 * <ul>
025 *     <li>OAuth 2.0 (RFC 6749), sections 1.3.4 and 4.4.
026 * </ul>
027 */
028@ThreadSafe
029public interface ClientCredentialsGrantHandler extends GrantHandler {
030
031
032        /**
033         * The handled grant type.
034         */
035        GrantType GRANT_TYPE = GrantType.CLIENT_CREDENTIALS;
036        
037        
038        @Override
039        default GrantType getGrantType() {
040                return GRANT_TYPE;
041        }
042        
043        
044        /**
045         * Handles a client credentials grant. The client is confidential and
046         * always authenticated.
047         *
048         * @param scope          The requested scope, {@code null} if not
049         *                       specified.
050         * @param clientID       The client identifier. Not {@code null}.
051         * @param clientMetadata The OAuth 2.0 client metadata. Not
052         *                       {@code null}.
053         *
054         * <p>If the requested scope is invalid, unknown, malformed, or exceeds
055         * the scope granted by the resource owner the handler must throw a
056         * {@link GeneralException} with an
057         * {@link com.nimbusds.oauth2.sdk.OAuth2Error#INVALID_SCOPE
058         * invalid_scope} error code.
059         *
060         * @return The authorisation.
061         *
062         * @throws GeneralException If the grant is invalid, or another
063         *                          exception was encountered.
064         */
065        @Deprecated
066        default GrantAuthorization processGrant(final @Nullable Scope scope,
067                                                final ClientID clientID,
068                                                final ClientMetadata clientMetadata)
069                throws GeneralException {
070                
071                return null;
072        }
073        
074        
075        /**
076         * Handles a client credentials grant. The client is confidential and
077         * always authenticated.
078         *
079         * @param tokenRequestParams The token request parameters, such as the
080         *                           requested scope. Not {@code null}.
081         * @param clientID           The client identifier. Not {@code null}.
082         * @param clientMetadata     The OAuth 2.0 client metadata. Not
083         *                           {@code null}.
084         * @param invocationCtx      The invocation context. Not {@code null}.
085         *
086         * <p>If the requested scope is invalid, unknown, malformed, or exceeds
087         * the scope granted by the resource owner the handler must throw a
088         * {@link GeneralException} with an
089         * {@link com.nimbusds.oauth2.sdk.OAuth2Error#INVALID_SCOPE
090         * invalid_scope} error code.
091         *
092         * @return The authorisation.
093         *
094         * @throws GeneralException If the grant is invalid, or another
095         *                          exception was encountered.
096         */
097        default GrantAuthorization processGrant(final TokenRequestParameters tokenRequestParams,
098                                                final ClientID clientID,
099                                                final ClientMetadata clientMetadata,
100                                                final InvocationContext invocationCtx)
101                throws GeneralException {
102                
103                return processGrant(tokenRequestParams.getScope(), clientID, clientMetadata);
104        }
105}