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