Verification Failed for the Provided custom_password_hash

Knowledge Articles
1

Overview

When a user attempts to log in using the correct password following a custom password hash import, the login fails, and the tenant logs record the following error:

Password change required error with reason Verification failed for the provided custom_password_hash

Applies To

  • Bulk user import
  • Custom password hashes

Cause

This error is expected when a user enters the wrong password, as Auth0 cannot be certain if there is an issue with the hash provided or the password is simply incorrect, as detailed in this community article:

Password Change Required After Password Hash Import

However, if the password is verifiably correct, then there is most likely an issue in the provided custom_password_hash object, leading to Auth0 generating a different hash at the point the user logs in to what is stored on the user account.

Solution

Check the documentation below that all the necessary details are included in the user’s import object:

Depending on the algorithm in use on the legacy system, the contents of the custom_password_hash object will need different attributes:

The most common issues with custom password hashes are encoding-related issues.

  • For example, there may be a mismatch between the encoding used for the hash that is provided and what the encoding is specified as in the import.

Another potential cause is if the plaintext password is converted to bytes differently by the source/legacy system—by default, Auth0 will use UTF-8 to encode the password string to bytes before attempting hashing, but the source system may have used a different encoding when the original hash was generated.

This can be accounted for by specifying the password.encoding attribute:

  • If the source system used UFT-16 LE to encode the original password before hashing, the below would be required to allow the hash to be generated in the same way by Auth0 to check the password is correct:
      "custom_password_hash": {
        "algorithm": "sha1",
        "hash": {
          "value": "HASH_IN_BASE64_HERE",
          "encoding": "base64"
        },
        "salt": {
          "value": "SALT_IN_BASE64_HERE",
                     "encoding": "base64",
          "position": "prefix"
        },
        "password": {
          "encoding" :"utf16le"
        }
      }