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;
012
013
014/**
015 * Service Provider Interface (SPI) for handling OAuth 2.0 client credentials
016 * grants. Returns the matching {@link GrantAuthorization authorisation} on
017 * success.
018 *
019 * <p>Implementations must be thread-safe.
020 *
021 * <p>Related specifications:
022 *
023 * <ul>
024 *     <li>OAuth 2.0 (RFC 6749), sections 1.3.4 and 4.4.
025 * </ul>
026 */
027@ThreadSafe
028public interface ClientCredentialsGrantHandler extends GrantHandler {
029
030
031        /**
032         * The handled grant type.
033         */
034        GrantType GRANT_TYPE = GrantType.CLIENT_CREDENTIALS;
035        
036        
037        @Override
038        default GrantType getGrantType() {
039                return GRANT_TYPE;
040        }
041        
042        
043        /**
044         * Handles a client credentials grant. The client is confidential and
045         * always authenticated.
046         *
047         * @param scope          The requested scope, {@code null} if not
048         *                       specified.
049         * @param clientID       The client identifier. Not {@code null}.
050         * @param clientMetadata The OAuth 2.0 client metadata. Not
051         *                       {@code null}.
052         *
053         * <p>If the requested scope is invalid, unknown, malformed, or exceeds
054         * the scope granted by the resource owner the handler must throw a
055         * {@link GeneralException} with an
056         * {@link com.nimbusds.oauth2.sdk.OAuth2Error#INVALID_SCOPE
057         * invalid_scope} error code.
058         *
059         * @return The authorisation.
060         *
061         * @throws GeneralException If the grant is invalid, or another
062         *                          exception was encountered.
063         */
064        GrantAuthorization processGrant(final @Nullable Scope scope,
065                                        final ClientID clientID,
066                                        final ClientMetadata clientMetadata)
067                throws GeneralException;
068}