How do I troubleshoot "Unable to verify secret hash for client <client-id>" errors from my Amazon Cognito user pools API?

Short description

When a user pool app client is configured with a client secret in the user pool, a SecretHash value is required in the API's query argument. If a secret hash isn't provided in the APIs query argument, then Amazon Cognito returns an **Unable to verify secret hash for client <client-id>**error.

The following example shows how to create a SecretHash value and include it in either an InitiateAuth or ForgotPassword API call.

Resolution

Note: If you receive errors when running AWS Command Line Interface (AWS CLI) commands, make sure that you're using the most recent AWS CLI version.

To create a SecretHash value

Follow the instructions in Computing SecretHash values. You'll need your app client ID, app client secret, and the user name of the user in your Amazon Cognito user pool.

-or-

To automate the process, do the following:

1.    If you haven't done so already, install Python.

2.    Save the following example Python script as a .py file:

import sys
import hmac, hashlib, base64

username = sys.argv[1]
app_client_id = sys.argv[2]
key = sys.argv[3]
message = bytes(sys.argv[1]+sys.argv[2],'utf-8')
key = bytes(sys.argv[3],'utf-8')
secret_hash = base64.b64encode(hmac.new(key, message, digestmod=hashlib.sha256).digest()).decode()

print("SECRET HASH:",secret_hash)

Note: Replace the following values before running the example script: For username, enter the user name of the user in the user pool. For app_client_id, enter your user pool's app client ID. For key, enter your app client's secret.

3.    Run the following command to run the script:

python3 secret_hash.py <username> <app_client_id> <app_client_secret>

Note: Replace the following values before running the command: If you're running a version of Python earlier than Python 3.0, replace python3 with python. For secret_hash.py, enter the file name of the example script. For username, enter the user pool username. For app_client_id, enter your app client ID For app_client_secret, enter your app client's secret.

The command response returns a SecretHash value.

To include SecretHash values in API calls

Note: A SecretHash value isn't required in Amazon Cognito API calls if your app client isn't configured with an app client secret. For more information, see Configuring a user pool app client.

Add the SecretHash value you created as a SECRET_HASH parameter in the query string parameters of the API call.

Example InitiateAuth API call that includes a SECRET_HASH parameter

$ aws cognito-idp initiate-auth --auth-flow USER_PASSWORD_AUTH --auth-parameters USERNAME=<username>,PASSWORD=<password>,SECRET_HASH=<secret_hash> --client-id <client-id>

Example InitiateAuth API call response

{
    "ChallengeParameters": {},
    
    "AuthenticationResult": {
        "AccessToken": "<HIDDEN>",
        "ExpiresIn": 3600,
        "TokenType":
    "Bearer",
    
        "RefreshToken": "<HIDDEN>",
        "IdToken": "<HIDDEN>"
    }
}

Note: If you're using USER_PASSWORD_AUTH authentication flow, make sure that ALLOW_USER_PASSWORD_AUTH is turned on.

Example ForgotPassword API call that includes a SECRET_HASH parameter

$ aws cognito-idp forgot-password --client-id <client-id> --username <username> --secret-hash <secret-hash>

Example ForgotPassword API call response

{
    "CodeDeliveryDetails": {
        "Destination": "+***********",
        "DeliveryMedium": "SMS",
        "AttributeName": "phone_number"
    }
}