Modifying the "Password is not acceptable" Error Message

To modify the error message displayed when a user attempts to reuse a password you need to change (or add) the error message to all the forms where users are allowed to change their password; for example, if you’re using Hosted Login that means you’ll need to modify the forms changePasswordForm and changePasswordNoAuthForm. In this walkthrough, we’ll work with the changePasswordNoAuthForm form, and we’ll assume that the passwordUnacceptable validation rule hasn’t been added to the form yet.

Note that your existing forms (and flows) might already include this validation rule, even if those forms and flows were created before the password history feature was released. That's because the password history elements have been added to the default Identity Cloud flow, which means that, at the very least. your Hosted Login flows should automatically begin using those elements. (Hosted Login is designed to use core flow elements from a master flow if those core elements can't be found in the current flow.) You can verify the existence of the passwordUnacceptable validation rule by returning the property values of the form and looking for a section similar to this:

 "validation": [
    {
      "rule": "passwordUnacceptable",
      "message": "a90e78fc1784c0e8bcdb163a9eee4020"
    }
  ]

If the validation rule already exists then that rule doesn't need to be added to the form. In addition, you can change the text of that flow by using the /translations endpoint to modify the translation specified by the message property (in the preceding example, that's the translation with the key ID a90e78fc1784c0e8bcdb163a9eee4020.

Step 1: Return the Current Properties and Property Values of the Form

To add the validation rule to a form, start by using the /forms/{form} endpoint and the GET method to return the current properties of that form. The following Curl command does just that:

curl -L -X GET \
  'https://v1.api.us.janrain.com/config/79y4mqf2rt3bxs378kw5479xdu/flows/new-test-flow/forms/changePasswordNoAuthForm' \
  -H 'Authorization: Basic eTR4Zmc2ZjQ0bXNhYzN2ZXBqanZ4Z2d6dnQzZTNzazk6OTVjY3hrN2N6YnZ1eng2ZHB0ZTVrOXA2ZGo1Ynpla3U='

In return, you’ll get an API response similar to the following:

{
    "action": "profileUpdate",
    "fields": [
        {
            "_self": "/config/79y4mqf2rt3bxs378kw5479xdu/flows/new-test-flow/fields/newPassword",
            "name": "newPassword",
            "required": true
        },
        {
            "_self": "/config/79y4mqf2rt3bxs378kw5479xdu/flows/new-test-flow/fields/
newPasswordConfirm",
            "name": "newPasswordConfirm",
            "required": false
        }
    ],
    "next": {
        "sendMail": {
            "mail": "passwordChanged"
        },
        "type": "server"
    },
    "_self": "/config/79y4mqf2rt3bxs378kw5479xdu/flows/new-test-flow/forms/changePasswordNoAuthForm"
}

You’ll need to copy this response and use it in Step 2.


Step 2:Add a Validation Rule to the Form

The next step is to add the passwordUnacceptable validation rule to the form. By default, that rule looks like this: 

 "validation": [
    {
      "rule": "passwordUnacceptable",
      "message": "This password is not acceptable. Select a different password."
    }
  ]

As you can see, the validation includes two parts:

  • The rule indicates the validation rule used to check the data input. In this case, that’s the passwordUnacceptable rule.
  • The message specifies the text displayed if validation fails. In the preceding example, that’s the default message The password is not acceptable. Select a different password.

If you don’t like the default message that accompanies the passwordUnacceptable rule you can change it before making your API call:

 "validation": [
    {
      "rule": "passwordUnacceptable",
      "message": "You’ve already used this password. Please select a different password."
    }
  ]

When you make that API call, you’ll use the /forms/{form} endpoint and the PUT method. In addition, you’ll also need to:

  1. Configure the body parameter of the API call to use JSON format.
  2. Paste in the current properties and property values of the form, the same properties and property values you copied in Step 1.
  3. Add the passwordUnacceptable validation rule to the body parameter.

A complete Curl command for adding the validation rule to a form will look similar to this:

curl -L -X PUT \
  'https://v1.api.us.janrain.com/config/79y4mqf2rt3bxs378kw5479xdu/flows/new-test-flow/forms/
changePasswordNoAuthForm' \
  -H 'Authorization: Basic eTR4Zmc2ZjQ0bXNhYzN2ZXBqanZ4Z2d6dnQzZTNzazk6OTVjY3hrN2N6YnZ1eng2ZH
B0ZTVrOXA2ZGo1Ynpla3U=' \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "action": "profileUpdate",
    "fields": [
        {
            "name": "newPassword",
            "required": true
        },
        {
            "name": "newPasswordConfirm",
            "required": false
        }
    ],
    "next": {
        "sendMail": {
            "mail": "passwordChanged"
        },
        "type": "server"
    },
    "validation": [
        {
            "rule": "passwordUnacceptable",
            "message": "You’ve already used this password. Please select a different password."
        }
    ]
}'

If your API call succeeds, you’ll get the HTTP response 204 No Content. If you then call the GET method in order to view the updated properties of the form, you should see the new validation rule

{
    "action": "profileUpdate",
    "fields": [
        {
            "_self": "/config/79y4mqf2rt3bxs378kw5479xdu/flows/new-test-flow/fields/newPassword",
            "name": "newPassword",
            "required": true
        },
        {
            "_self": "/config/79y4mqf2rt3bxs378kw5479xdu/flows/new-test-flow/fields/newPasswordConfirm",
            "name": "newPasswordConfirm",
            "required": false
        }
    ],
    "next": {
        "sendMail": {
            "mail": "passwordChanged"
        },
        "type": "server"
    },
    "validation": [
        {
            "rule": "passwordUnacceptable",
            "message": "a90e78fc1784c0e8bcdb163a9eee4020"
        }
    ],
    "_self": "/config/79y4mqf2rt3bxs378kw5479xdu/flows/new-test-flow/forms/changePasswordNoAuthForm"
}

As you might have noticed, in the API response the message text has been replaced by an ID: a90e78fc1784c0e8bcdb163a9eee4020. As alluded to earlier, the ID is actually a translation containing the message text. That means that you can use a Curl command similar to this one to view that translation (and the message text):

curl -L -X GET \
  'https://v1.api.us.janrain.com/config/79y4mqf2rt3bxs378kw5479xdu/flows/new-test-flow/translations/a90e78fc1784c0e8bcdb163a9eee4020'\
  -H 'Authorization: Basic eTR4Zmc2ZjQ0bXNhYzN2ZXBqanZ4Z2d6dnQzZTNzazk6OTVjY3hrN2N6YnZ1eng2ZHB0ZTVrOXA2ZGo1Ynpla3U=' \

That returns information similar to the following:

{
    "key": "a90e78fc1784c0e8bcdb163a9eee4020",
    "path": "fields.changePasswordNoAuthForm.messages.errors.passwordUnacceptable",
    "values": {
        "en-US": "You’ve already used this password. Please select a different password."
    },
    "_self": "/config/79y4mqf2rt3bxs378kw5479xdu/flows/new-test-flow/translations/a90e78fc1784c0e8bcdb163a9eee4020"
}

From now on you can change the passwordUnacceptable text anytime you want simply by changing the value of the a90e78fc1784c0e8bcdb163a9eee4020 translation key.