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

Resolution

When you configure your user pool app client as a client secret, you must include a secret hash value in the API's query parameter. If you don't include a secret hash value, then Amazon Cognito returns an Unable to verify secret hash for client error.

To resolve the issue, calculate the secret hash value. Then, include the value when you invoke Amazon Cognito APIs that accept secret hash, such as InitiateAuth or ForgotPassword.

Note: If you receive errors when you run AWS Command Line Interface (AWS CLI) commands, then see Troubleshooting errors for the AWS CLI. Also, make sure that you're using the most recent AWS CLI version.

Calculate a secret hash value

To calculate your secret hash value, you must have the following information:

• App client ID
• App client secret
• Username of the user that's in your Amazon Cognito user pool

To automate the process, complete the following steps:

1. Download the latest version of Python for Windows on the Python website. Then, install Python on your local machine.
2. Save the following example Python script as a .py file. For example, you can save the file as secret_hash.py. The following script uses the application client secret as the key and the SHA256 hash function to show the calculation of an HMAC digest:

   import sys, hmac, hashlib, base64
   
   # Unpack command line arguments
   username, app_client_id, key = sys.argv[1:4]
   
   # Create message and key bytes
   message, key = (username + app_client_id).encode('utf-8'), key.encode('utf-8')
   
   # Calculate secret hash
   secret_hash = base64.b64encode(hmac.new(key, message, digestmod=hashlib.sha256).digest()).decode()
   
   print(f"Secret Hash for user '{username}': {secret_hash}")
   

   Note: Replace username with the username of the user that's in the user pool. Also, replace app_client_id with your user pool's app client ID and key with your app client's secret.
3. To get the secret hash value, run the following command:

   python3 secret_hash.py username app_client_id app_client_secret

   Note: If you're running a version of Python that's earlier than Python 3.0, then replace python3 with python. Replace secret_hash.py with your file name, username with the user pool username, app_client_id with your app client ID, and app_client_secret with your app client's secret.

Include secret hash values in API calls

Add your secret hash value 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 example_client-id

Example InitiateAuth API call output:

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

Note: If you use the USER_PASSWORD_AUTH authentication flow, then turn on ALLOW_USER_PASSWORD_AUTH for the app client.

Example ForgotPassword API call that includes a SECRET_HASH parameter:

aws cognito-idp forgot-password --client-id example_client-id --username example_username --secret-hash example_secret-hash

Note: Replace username with your username and secret-hash with your secret hash value.

Example ForgotPassword API call output:

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