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.ResourceOwnerPasswordCredentialsGrant;
010import com.nimbusds.oauth2.sdk.Scope;
011import com.nimbusds.oauth2.sdk.id.ClientID;
012import com.nimbusds.openid.connect.provider.spi.InvocationContext;
013import com.nimbusds.openid.connect.sdk.rp.OIDCClientMetadata;
014
015
016/**
017 * Service Provider Interface (SPI) for handling OAuth 2.0 resource owner
018 * password credentials grants. Returns the matching
019 * {@link PasswordGrantAuthorization authorisation} on success. Must throw an
020 * {@link GeneralException} with an
021 * {@link com.nimbusds.oauth2.sdk.OAuth2Error#INVALID_GRANT invalid_grant}
022 * error code if the user credentials are invalid.
023 *
024 * <p>Implementations must be thread-safe.
025 *
026 * <p>Related specifications:
027 *
028 * <ul>
029 *     <li>OAuth 2.0 (RFC 6749), sections 1.3.3 and 4.3.
030 * </ul>
031 */
032@ThreadSafe
033public interface PasswordGrantHandler extends GrantHandler {
034
035
036        /**
037         * The handled grant type.
038         */
039        GrantType GRANT_TYPE = GrantType.PASSWORD;
040        
041        
042        @Override
043        default GrantType getGrantType() {
044                return GRANT_TYPE;
045        }
046        
047        
048        /**
049         * Handles a resource owner password credentials grant.
050         *
051         * @param grant              The resource owner password credentials
052         *                           grant. Not {@code null}.
053         * @param scope              The requested scope, {@code null} if not
054         *                           specified.
055         * @param clientID           The client identifier. Not {@code null}.
056         * @param confidentialClient {@code true} if the client is confidential
057         *                           and has been authenticated, else
058         *                           {@code false}.
059         * @param clientMetadata     The OpenID Connect client metadata. Not
060         *                           {@code null}.
061         *
062         * <p>If the user credentials are invalid the handler must throw a
063         * {@link GeneralException exception} with an
064         * {@link com.nimbusds.oauth2.sdk.OAuth2Error#INVALID_GRANT
065         * invalid_grant} error code.
066         *
067         * <p>If the requested scope is invalid, unknown, malformed, or exceeds
068         * the scope granted by the resource owner the handler must throw a
069         * {@link GeneralException} with an
070         * {@link com.nimbusds.oauth2.sdk.OAuth2Error#INVALID_SCOPE
071         * invalid_scope} error code.
072         *
073         * @return The authorisation.
074         *
075         * @throws GeneralException If the grant is invalid, or another
076         *                          exception was encountered.
077         */
078        @Deprecated
079        default PasswordGrantAuthorization processGrant(final ResourceOwnerPasswordCredentialsGrant grant,
080                                                        final @Nullable Scope scope,
081                                                        final ClientID clientID,
082                                                        final boolean confidentialClient,
083                                                        final OIDCClientMetadata clientMetadata)
084                throws GeneralException {
085                
086                return null;
087        }
088        
089        
090        /**
091         * Handles a resource owner password credentials grant.
092         *
093         * @param grant              The resource owner password credentials
094         *                           grant. Not {@code null}.
095         * @param tokenRequestParams The token request parameters, such as the
096         *                           requested scope. Not {@code null}.
097         * @param clientID           The client identifier. Not {@code null}.
098         * @param confidentialClient {@code true} if the client is confidential
099         *                           and has been authenticated, else
100         *                           {@code false}.
101         * @param clientMetadata     The OpenID Connect client metadata. Not
102         *                           {@code null}.
103         * @param invocationCtx      The invocation context. Not {@code null}.
104         *
105         * <p>If the user credentials are invalid the handler must throw a
106         * {@link GeneralException exception} with an
107         * {@link com.nimbusds.oauth2.sdk.OAuth2Error#INVALID_GRANT
108         * invalid_grant} error code.
109         *
110         * <p>If the requested scope is invalid, unknown, malformed, or exceeds
111         * the scope granted by the resource owner the handler must throw a
112         * {@link GeneralException} with an
113         * {@link com.nimbusds.oauth2.sdk.OAuth2Error#INVALID_SCOPE
114         * invalid_scope} error code.
115         *
116         * @return The authorisation.
117         *
118         * @throws GeneralException If the grant is invalid, or another
119         *                          exception was encountered.
120         */
121        default PasswordGrantAuthorization processGrant(final ResourceOwnerPasswordCredentialsGrant grant,
122                                                        final TokenRequestParameters tokenRequestParams,
123                                                        final ClientID clientID,
124                                                        final boolean confidentialClient,
125                                                        final OIDCClientMetadata clientMetadata,
126                                                        final InvocationContext invocationCtx)
127                throws GeneralException {
128                
129                return processGrant(grant, tokenRequestParams.getScope(), clientID, confidentialClient, clientMetadata);
130        }
131}