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