Configure Security Questions

IDM uses security questions to let users verify their identities. Security questions are sometimes referred to as Knowledge-Based Authentication (KBA). When an administrator has configured security questions, self-service users can choose from the questions set in the selfservice.kba.json file, as described in "Security Questions and Self-Registration".

You can prompt users to update their security questions. As these questions may be subject to risks, you can set up IDM to prompt the user to update and/or add security questions, courtesy of the selfservice-kbaUpdate.json file. For more information, see "Prompt to Update Security Questions".

Security Questions and Self-Registration

The user is prompted to enter answers to pre-configured or custom security questions, during the self-registration process. These questions are used to help verify an identity when a user requests a password reset. These questions do not apply for users who need username retrieval.

The template version of the selfservice.kba.json file is straightforward; it includes minimumAnswersToDefine, which requires a user to define at least that many security questions and answers, along with minimumAnswersToVerify, which requires a user to answer (in this case), at least one of those questions when asking for a password reset.

    "kbaPropertyName" : "kbaInfo",
    "minimumAnswersToDefine": 2,
    "minimumAnswersToVerify": 1,
    "questions" : {
        "1" : {
            "en" : "What's your favorite color?",
            "en_GB" : "What is your favourite colour?",
            "fr" : "Quelle est votre couleur préférée?"
        "2" : {
            "en" : "Who was your first employer?"

To configure account lockout based on the security questions, add the following lines to your selfservice.kba.json file:

"numberOfAttemptsAllowed" : 2,
"kbaAttemptsPropertyName" : "lockoutproperty"

With this configuration, users who make more than two mistakes in answering security questions are prevented from using the password reset facility until the kbaAttemptsPropertyName field is removed, or the number is set to a value lower than the numberOfAttemptsAllowed. The number of mistakes is recorded in whatever property you assign to kbaAttemptsPropertyName (lockoutproperty, in this example).

If you are using an explicit mapping for managed user objects, you must add this lockoutproperty to your database schema and to the objectToColumn mapping in your repository configuration file.

For example, the previous configuration would require the following addition to your conf/repo.jdbc.json file:

"explicitMapping" : {
    "managed/user": {
        "table" : "managed_user",
        "objectToColumn": {
            "lockoutproperty" : "lockoutproperty",

You would also need to create a lockoutproperty column in the openidm.managed_user table, with datatype VARCHAR. For example:

mysql> show columns from managed_user;
| Field                | Type         | Null | Key | Default | Extra |
| objectid             | varchar(38)  | NO   | PRI | NULL    |       |
| rev                  | varchar(38)  | NO   |     | NULL    |       |
| username             | varchar(255) | YES  | UNI | NULL    |       |
| password             | varchar(511) | YES  |     | NULL    |       |
| accountstatus        | varchar(255) | YES  | MUL | NULL    |       |
| postalcode           | varchar(255) | YES  |     | NULL    |       |
| lockoutproperty      | varchar(255) | YES  |     | NULL    |       |


Once you deploy these IDM self-service features, you should never remove or change existing security questions, as users may have included those questions during the user self-registration process.

You may change or add the questions of your choice, in JSON format. If you're configuring user self-registration, you can also edit these questions through the Admin UI. In fact, the Admin UI lets you localize these questions in different languages.

In the Admin UI, select Configure > User Registration. Enable User Registration, select Options > Security Questions, and select the edit icon to add, edit, or delete these questions.

Any change you make to the security questions under User Registration also applies to Password Reset. To confirm, select Configure > Password Reset. Enable Password Reset, and edit the Security Questions. You'll see the same questions there.

In addition, individual users can configure their own questions and answers, in two ways:

  • During the user self-registration process

  • From the End User UI, in the user's Profile section (), under Account Security > Security Questions


A managed user's security questions can only be changed through the selfservice/userupdate endpoint, or when the user is created through selfservice/registration, and provides their own questions. You cannot manipulate a user's kbaInfo property directly through the managed/user endpoint.

When the answers to security questions are hashed, they are converted to lowercase. If you intend to pre-populate answers with a mapping, the openidm.hash function, or the secureHash mechanism, you must provide the string in lowercase to match the value of the answer.

Prompt to Update Security Questions

IDM supports a requirement for users to update their security questions, in the selfservice-kbaUpdate.json file. You can find this file in the following directory: /path/to/openidm/samples/example-configurations/self-service.

Alternatively, if you set up security questions from the Admin UI, you can navigate to Configure > Security Questions > Update Form, and select Enable Update. This action adds a selfservice-kbaUpdate.json file to your project's conf/ subdirectory.

For more information on this configuration file, see "Conditional User Stage".

Read a different version of :