RespondToAuthChallenge
Some API operations in a user pool generate a challenge, like a prompt for an MFA
code, for device authentication that bypasses MFA, or for a custom authentication
challenge. A RespondToAuthChallenge
API request provides the answer to that
challenge, like a code or a secure remote password (SRP). The parameters of a response
to an authentication challenge vary with the type of challenge.
For more information about custom authentication challenges, see Custom authentication challenge Lambda triggers.
Note
Amazon Cognito doesn't evaluate Amazon Identity and Access Management (IAM) policies in requests for this API operation. For this operation, you can't use IAM credentials to authorize requests, and you can't grant IAM permissions in policies. For more information about authorization models in Amazon Cognito, see Using the Amazon Cognito user pools API and user pool endpoints.
Note
This action might generate an SMS text message. Starting June 1, 2021, US telecom carriers
require you to register an origination phone number before you can send SMS messages
to US phone numbers. If you use SMS text messages in Amazon Cognito, you must register a
phone number with Amazon Pinpoint
If you have never used SMS text messages with Amazon Cognito or any other Amazon Web Services service, Amazon Simple Notification Service might place your account in the SMS sandbox. In sandbox mode , you can send messages only to verified phone numbers. After you test your app while in the sandbox environment, you can move out of the sandbox and into production. For more information, see SMS message settings for Amazon Cognito user pools in the Amazon Cognito Developer Guide.
Request Syntax
{
"AnalyticsMetadata": {
"AnalyticsEndpointId": "string
"
},
"ChallengeName": "string
",
"ChallengeResponses": {
"string
" : "string
"
},
"ClientId": "string
",
"ClientMetadata": {
"string
" : "string
"
},
"Session": "string
",
"UserContextData": {
"EncodedData": "string
",
"IpAddress": "string
"
}
}
Request Parameters
For information about the parameters that are common to all actions, see Common Parameters.
The request accepts the following data in JSON format.
- AnalyticsMetadata
-
The Amazon Pinpoint analytics metadata that contributes to your metrics for
RespondToAuthChallenge
calls.Type: AnalyticsMetadataType object
Required: No
- ChallengeName
-
The challenge name. For more information, see InitiateAuth.
ADMIN_NO_SRP_AUTH
isn't a valid value.Type: String
Valid Values:
SMS_MFA | EMAIL_OTP | SOFTWARE_TOKEN_MFA | SELECT_MFA_TYPE | MFA_SETUP | PASSWORD_VERIFIER | CUSTOM_CHALLENGE | SELECT_CHALLENGE | DEVICE_SRP_AUTH | DEVICE_PASSWORD_VERIFIER | ADMIN_NO_SRP_AUTH | NEW_PASSWORD_REQUIRED | SMS_OTP | PASSWORD | WEB_AUTHN | PASSWORD_SRP
Required: Yes
- ChallengeResponses
-
The responses to the challenge that you received in the previous request. Each challenge has its own required response parameters. The following examples are partial JSON request bodies that highlight challenge-response parameters.
Important
You must provide a SECRET_HASH parameter in all challenge responses to an app client that has a client secret. Include a
DEVICE_KEY
for device authentication.- SELECT_CHALLENGE
-
"ChallengeName": "SELECT_CHALLENGE", "ChallengeResponses": { "USERNAME": "[username]", "ANSWER": "[Challenge name]"}
Available challenges are
PASSWORD
,PASSWORD_SRP
,EMAIL_OTP
,SMS_OTP
, andWEB_AUTHN
.Complete authentication in the
SELECT_CHALLENGE
response forPASSWORD
,PASSWORD_SRP
, andWEB_AUTHN
:-
"ChallengeName": "SELECT_CHALLENGE", "ChallengeResponses": { "ANSWER": "WEB_AUTHN", "USERNAME": "[username]", "CREDENTIAL": "[AuthenticationResponseJSON]"}
-
"ChallengeName": "SELECT_CHALLENGE", "ChallengeResponses": { "ANSWER": "PASSWORD", "USERNAME": "[username]", "PASSWORD": "[password]"}
-
"ChallengeName": "SELECT_CHALLENGE", "ChallengeResponses": { "ANSWER": "PASSWORD_SRP", "USERNAME": "[username]", "SRP_A": "[SRP_A]"}
For
SMS_OTP
andEMAIL_OTP
, respond with the username and answer. Your user pool will send a code for the user to submit in the next challenge response.-
"ChallengeName": "SELECT_CHALLENGE", "ChallengeResponses": { "ANSWER": "SMS_OTP", "USERNAME": "[username]"}
-
"ChallengeName": "SELECT_CHALLENGE", "ChallengeResponses": { "ANSWER": "EMAIL_OTP", "USERNAME": "[username]"}
-
- SMS_OTP
-
"ChallengeName": "SMS_OTP", "ChallengeResponses": {"SMS_OTP_CODE": "[code]", "USERNAME": "[username]"}
- EMAIL_OTP
-
"ChallengeName": "EMAIL_OTP", "ChallengeResponses": {"EMAIL_OTP_CODE": "[code]", "USERNAME": "[username]"}
- SMS_MFA
-
"ChallengeName": "SMS_MFA", "ChallengeResponses": {"SMS_MFA_CODE": "[code]", "USERNAME": "[username]"}
- PASSWORD_VERIFIER
-
This challenge response is part of the SRP flow. Amazon Cognito requires that your application respond to this challenge within a few seconds. When the response time exceeds this period, your user pool returns a
NotAuthorizedException
error."ChallengeName": "PASSWORD_VERIFIER", "ChallengeResponses": {"PASSWORD_CLAIM_SIGNATURE": "[claim_signature]", "PASSWORD_CLAIM_SECRET_BLOCK": "[secret_block]", "TIMESTAMP": [timestamp], "USERNAME": "[username]"}
Add
"DEVICE_KEY"
when you sign in with a remembered device. - CUSTOM_CHALLENGE
-
"ChallengeName": "CUSTOM_CHALLENGE", "ChallengeResponses": {"USERNAME": "[username]", "ANSWER": "[challenge_answer]"}
Add
"DEVICE_KEY"
when you sign in with a remembered device. - NEW_PASSWORD_REQUIRED
-
"ChallengeName": "NEW_PASSWORD_REQUIRED", "ChallengeResponses": {"NEW_PASSWORD": "[new_password]", "USERNAME": "[username]"}
To set any required attributes that
InitiateAuth
returned in anrequiredAttributes
parameter, add"userAttributes.[attribute_name]": "[attribute_value]"
. This parameter can also set values for writable attributes that aren't required by your user pool.Note
In a
NEW_PASSWORD_REQUIRED
challenge response, you can't modify a required attribute that already has a value. InRespondToAuthChallenge
, set a value for any keys that Amazon Cognito returned in therequiredAttributes
parameter, then use theUpdateUserAttributes
API operation to modify the value of any additional attributes. - SOFTWARE_TOKEN_MFA
-
"ChallengeName": "SOFTWARE_TOKEN_MFA", "ChallengeResponses": {"USERNAME": "[username]", "SOFTWARE_TOKEN_MFA_CODE": [authenticator_code]}
- DEVICE_SRP_AUTH
-
"ChallengeName": "DEVICE_SRP_AUTH", "ChallengeResponses": {"USERNAME": "[username]", "DEVICE_KEY": "[device_key]", "SRP_A": "[srp_a]"}
- DEVICE_PASSWORD_VERIFIER
-
"ChallengeName": "DEVICE_PASSWORD_VERIFIER", "ChallengeResponses": {"DEVICE_KEY": "[device_key]", "PASSWORD_CLAIM_SIGNATURE": "[claim_signature]", "PASSWORD_CLAIM_SECRET_BLOCK": "[secret_block]", "TIMESTAMP": [timestamp], "USERNAME": "[username]"}
- MFA_SETUP
-
"ChallengeName": "MFA_SETUP", "ChallengeResponses": {"USERNAME": "[username]"}, "SESSION": "[Session ID from VerifySoftwareToken]"
- SELECT_MFA_TYPE
-
"ChallengeName": "SELECT_MFA_TYPE", "ChallengeResponses": {"USERNAME": "[username]", "ANSWER": "[SMS_MFA or SOFTWARE_TOKEN_MFA]"}
For more information about
SECRET_HASH
, see Computing secret hash values. For information aboutDEVICE_KEY
, see Working with user devices in your user pool.Type: String to string map
Key Length Constraints: Minimum length of 0. Maximum length of 131072.
Value Length Constraints: Minimum length of 0. Maximum length of 131072.
Required: No
- ClientId
-
The app client ID.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 128.
Pattern:
[\w+]+
Required: Yes
- ClientMetadata
-
A map of custom key-value pairs that you can provide as input for any custom workflows that this action triggers.
You create custom workflows by assigning Amazon Lambda functions to user pool triggers. When you use the RespondToAuthChallenge API action, Amazon Cognito invokes any functions that are assigned to the following triggers: post authentication, pre token generation, define auth challenge, create auth challenge, and verify auth challenge. When Amazon Cognito invokes any of these functions, it passes a JSON payload, which the function receives as input. This payload contains a
clientMetadata
attribute, which provides the data that you assigned to the ClientMetadata parameter in your RespondToAuthChallenge request. In your function code in Amazon Lambda, you can process theclientMetadata
value to enhance your workflow for your specific needs.For more information, see Customizing user pool Workflows with Lambda Triggers in the Amazon Cognito Developer Guide.
Note
When you use the
ClientMetadata
parameter, note that Amazon Cognito won't do the following:-
Store the
ClientMetadata
value. This data is available only to Amazon Lambda triggers that are assigned to a user pool to support custom workflows. If your user pool configuration doesn't include triggers, theClientMetadata
parameter serves no purpose. -
Validate the
ClientMetadata
value. -
Encrypt the
ClientMetadata
value. Don't send sensitive information in this parameter.
Type: String to string map
Key Length Constraints: Minimum length of 0. Maximum length of 131072.
Value Length Constraints: Minimum length of 0. Maximum length of 131072.
Required: No
-
- Session
-
The session that should be passed both ways in challenge-response calls to the service. If
InitiateAuth
orRespondToAuthChallenge
API call determines that the caller must pass another challenge, they return a session with other challenge parameters. This session should be passed as it is to the nextRespondToAuthChallenge
API call.Type: String
Length Constraints: Minimum length of 20. Maximum length of 2048.
Required: No
- UserContextData
-
Contextual data about your user session, such as the device fingerprint, IP address, or location. Amazon Cognito advanced security evaluates the risk of an authentication event based on the context that your app generates and passes to Amazon Cognito when it makes API requests.
For more information, see Collecting data for threat protection in applications.
Type: UserContextDataType object
Required: No
Response Syntax
{
"AuthenticationResult": {
"AccessToken": "string",
"ExpiresIn": number,
"IdToken": "string",
"NewDeviceMetadata": {
"DeviceGroupKey": "string",
"DeviceKey": "string"
},
"RefreshToken": "string",
"TokenType": "string"
},
"ChallengeName": "string",
"ChallengeParameters": {
"string" : "string"
},
"Session": "string"
}
Response Elements
If the action is successful, the service sends back an HTTP 200 response.
The following data is returned in JSON format by the service.
- AuthenticationResult
-
The result returned by the server in response to the request to respond to the authentication challenge.
Type: AuthenticationResultType object
- ChallengeName
-
The challenge name. For more information, see InitiateAuth.
Type: String
Valid Values:
SMS_MFA | EMAIL_OTP | SOFTWARE_TOKEN_MFA | SELECT_MFA_TYPE | MFA_SETUP | PASSWORD_VERIFIER | CUSTOM_CHALLENGE | SELECT_CHALLENGE | DEVICE_SRP_AUTH | DEVICE_PASSWORD_VERIFIER | ADMIN_NO_SRP_AUTH | NEW_PASSWORD_REQUIRED | SMS_OTP | PASSWORD | WEB_AUTHN | PASSWORD_SRP
- ChallengeParameters
-
The challenge parameters. For more information, see InitiateAuth.
Type: String to string map
Key Length Constraints: Minimum length of 0. Maximum length of 131072.
Value Length Constraints: Minimum length of 0. Maximum length of 131072.
- Session
-
The session that should be passed both ways in challenge-response calls to the service. If the caller must pass another challenge, they return a session with other challenge parameters. This session should be passed as it is to the next
RespondToAuthChallenge
API call.Type: String
Length Constraints: Minimum length of 20. Maximum length of 2048.
Errors
For information about the errors that are common to all actions, see Common Errors.
- AliasExistsException
-
This exception is thrown when a user tries to confirm the account with an email address or phone number that has already been supplied as an alias for a different user profile. This exception indicates that an account with this email address or phone already exists in a user pool that you've configured to use email address or phone number as a sign-in alias.
HTTP Status Code: 400
- CodeMismatchException
-
This exception is thrown if the provided code doesn't match what the server was expecting.
HTTP Status Code: 400
- ExpiredCodeException
-
This exception is thrown if a code has expired.
HTTP Status Code: 400
- ForbiddenException
-
This exception is thrown when Amazon WAF doesn't allow your request based on a web ACL that's associated with your user pool.
HTTP Status Code: 400
- InternalErrorException
-
This exception is thrown when Amazon Cognito encounters an internal error.
HTTP Status Code: 500
- InvalidEmailRoleAccessPolicyException
-
This exception is thrown when Amazon Cognito isn't allowed to use your email identity. HTTP status code: 400.
HTTP Status Code: 400
- InvalidLambdaResponseException
-
This exception is thrown when Amazon Cognito encounters an invalid Amazon Lambda response.
HTTP Status Code: 400
- InvalidParameterException
-
This exception is thrown when the Amazon Cognito service encounters an invalid parameter.
HTTP Status Code: 400
- InvalidPasswordException
-
This exception is thrown when Amazon Cognito encounters an invalid password.
HTTP Status Code: 400
- InvalidSmsRoleAccessPolicyException
-
This exception is returned when the role provided for SMS configuration doesn't have permission to publish using Amazon SNS.
HTTP Status Code: 400
- InvalidSmsRoleTrustRelationshipException
-
This exception is thrown when the trust relationship is not valid for the role provided for SMS configuration. This can happen if you don't trust
cognito-idp.amazonaws.com
or the external ID provided in the role does not match what is provided in the SMS configuration for the user pool.HTTP Status Code: 400
- InvalidUserPoolConfigurationException
-
This exception is thrown when the user pool configuration is not valid.
HTTP Status Code: 400
- MFAMethodNotFoundException
-
This exception is thrown when Amazon Cognito can't find a multi-factor authentication (MFA) method.
HTTP Status Code: 400
- NotAuthorizedException
-
This exception is thrown when a user isn't authorized.
HTTP Status Code: 400
- PasswordHistoryPolicyViolationException
-
The message returned when a user's new password matches a previous password and doesn't comply with the password-history policy.
HTTP Status Code: 400
- PasswordResetRequiredException
-
This exception is thrown when a password reset is required.
HTTP Status Code: 400
- ResourceNotFoundException
-
This exception is thrown when the Amazon Cognito service can't find the requested resource.
HTTP Status Code: 400
- SoftwareTokenMFANotFoundException
-
This exception is thrown when the software token time-based one-time password (TOTP) multi-factor authentication (MFA) isn't activated for the user pool.
HTTP Status Code: 400
- TooManyRequestsException
-
This exception is thrown when the user has made too many requests for a given operation.
HTTP Status Code: 400
- UnexpectedLambdaException
-
This exception is thrown when Amazon Cognito encounters an unexpected exception with Amazon Lambda.
HTTP Status Code: 400
- UserLambdaValidationException
-
This exception is thrown when the Amazon Cognito service encounters a user validation exception with the Amazon Lambda service.
HTTP Status Code: 400
- UserNotConfirmedException
-
This exception is thrown when a user isn't confirmed successfully.
HTTP Status Code: 400
- UserNotFoundException
-
This exception is thrown when a user isn't found.
HTTP Status Code: 400
Examples
Example
The following example completes sign-in for the user testuser
with an email-message OTP. Because no additional challenges are required, the
request returns an AuthenticationResult
with ID, access, and
refresh tokens.
Sample Request
POST HTTP/1.1
Host: cognito-idp.us-east-1.amazonaws.com
X-Amz-Date: 20230613T200059Z
Accept-Encoding: gzip, deflate, br
X-Amz-Target: AWSCognitoIdentityProviderService.RespondToAuthChallenge
User-Agent: <UserAgentString>
Authorization: AWS4-HMAC-SHA256 Credential=<Credential>, SignedHeaders=<Headers>, Signature=<Signature>
Content-Length: <PayloadSizeBytes>
{
"ChallengeName": "EMAIL_OTP",
"ClientId": "1example23456789",
"UserPoolId": "us-west-2_EXAMPLE",
"ChallengeResponses": {
"USERNAME" : "testuser",
"EMAIL_OTP_CODE": "12345678"
},
"Session": "AYABeC1-y8qooiuysEv0uM4wAqQAHQABAAdTZXJ2aWNlABBDb2duaXRvVXNlclBvb2xzAAEAB2F3cy1rbXMAS2Fybjphd3M6a21zOnVzLXd..."
}
Sample Response
HTTP/1.1 200 OK
Date: Tue, 13 Jun 2023 20:00:59 GMT
Content-Type: application/x-amz-json-1.0
Content-Length: <PayloadSizeBytes>
x-amzn-requestid: a1b2c3d4-e5f6-a1b2-c3d4-EXAMPLE11111
Connection: keep-alive
{
"AuthenticationResult": {
"AccessToken": "eyJra456defEXAMPLE",
"ExpiresIn": 3600,
"IdToken": "eyJra789ghiEXAMPLE",
"RefreshToken": "eyJra123abcEXAMPLE",
"TokenType": "Bearer"
},
"ChallengeParameters": {
}
}
See Also
For more information about using this API in one of the language-specific Amazon SDKs, see the following: