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}