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.ResourceOwnerPasswordCredentialsGrant;
009import com.nimbusds.oauth2.sdk.Scope;
010import com.nimbusds.oauth2.sdk.id.ClientID;
011
012import com.nimbusds.openid.connect.sdk.rp.OIDCClientMetadata;
013
014
015/**
016 * Service Provider Interface (SPI) for handling OAuth 2.0 resource owner
017 * password credentials grants. Returns the matching
018 * {@link PasswordGrantAuthorization authorisation} on success. Must throw an
019 * {@link GeneralException} with an
020 * {@link com.nimbusds.oauth2.sdk.OAuth2Error#INVALID_GRANT invalid_grant}
021 * error code if the user credentials are invalid.
022 *
023 * <p>Implementations must be thread-safe.
024 *
025 * <p>Related specifications:
026 *
027 * <ul>
028 *     <li>OAuth 2.0 (RFC 6749), sections 1.3.3 and 4.3.
029 * </ul>
030 */
031@ThreadSafe
032public interface PasswordGrantHandler extends GrantHandler {
033
034
035        /**
036         * The handled grant type.
037         */
038        GrantType GRANT_TYPE = GrantType.PASSWORD;
039
040
041        /**
042         * Handles a resource owner password credentials grant.
043         *
044         * @param grant              The resource owner password credentials
045         *                           grant. Not {@code null}.
046         * @param scope              The requested scope, {@code null} if not
047         *                           specified.
048         * @param clientID           The client identifier. Not {@code null}.
049         * @param confidentialClient {@code true} if the client is confidential
050         *                           and has been authenticated, else
051         *                           {@code false}.
052         * @param clientMetadata     The OpenID Connect client metadata. Not
053         *                           {@code null}.
054         *
055         * <p>If the user credentials are invalid the handler must throw a
056         * {@link GeneralException exception} with an
057         * {@link com.nimbusds.oauth2.sdk.OAuth2Error#INVALID_GRANT
058         * invalid_grant} error code.
059         *
060         * <p>If the requested scope is invalid, unknown, malformed, or exceeds
061         * the scope granted by the resource owner the handler must throw a
062         * {@link GeneralException} with an
063         * {@link com.nimbusds.oauth2.sdk.OAuth2Error#INVALID_SCOPE
064         * invalid_scope} error code.
065         *
066         * @return The authorisation.
067         *
068         * @throws GeneralException If the grant is invalid, or another
069         *                          exception was encountered.
070         */
071        PasswordGrantAuthorization processGrant(final ResourceOwnerPasswordCredentialsGrant grant,
072                                                final Scope scope,
073                                                final ClientID clientID,
074                                                final boolean confidentialClient,
075                                                final OIDCClientMetadata clientMetadata)
076                throws GeneralException;
077}