IDM 7.3.1

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, refer to 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 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?"
        }
    }
}

You can change or add questions in JSON format, or if you’re configuring user self-registration, you can also edit these questions through the admin UI. From 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 refer to the same questions there.

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

  • 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.

KBA answer hashing

By default, KBA answers are SHA-256 hashed upon save. To specify another type of hashing, edit the self-service KBA configuration:

Using the Filesystem

Add the secureHash property to the conf/selfservice.kba.json file:

"secureHash" : {
  "algorithm": "{type}",
  "configProp": value
}

For example, to use BCRYPT hashing:

"secureHash": {
  "algorithm": "BCRYPT",
  "cost": 13
}
Using REST
  1. Get the current self-service KBA configuration:

    curl \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --header "Accept-API-Version: resource=1.0" \
    --request GET \
    "http://localhost:8080/openidm/config/selfservice.kba"
    {
      "_id": "selfservice.kba",
      "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?"
        }
      }
    }
  2. Add the secureHash property for the alternative hashing, and replace the self-service KBA configuration. For example, to use BCRYPT hashing:

    curl \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --header "Accept-API-Version: resource=1.0" \
    --header "Content-Type: application/json" \
    --request PUT \
    --data '{
      "_id": "selfservice.kba",
      "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?"
        }
      },
      "secureHash": {
        "algorithm": "BCRYPT",
        "cost": 13
      }
    }' \
    "http://localhost:8080/openidm/config/selfservice.kba"
    {
      "_id": "selfservice.kba",
      "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?"
        }
      },
      "secureHash": {
        "algorithm": "BCRYPT",
        "cost": 13
      }
    }
Supported Hashing Algorithms and Configuration Properties
Algorithm Config Property and Description

BCRYPT

cost

Value between 4 and 31. Default is 13.

PBKDF2

hashLength

Byte-length of the generated hash. Default is 16.

saltLength

Byte-length of the salt value. Default is 16.

iterations

Number of cryptographic iterations. Default is 20000.

hmac

HMAC algorithm. Default is SHA3-256.

Supported values:

  • SHA-224

  • SHA-256

  • SHA-384

  • SHA-512

  • SHA3-224

  • SHA3-256

  • SHA3-384

  • SHA3-512

SCRYPT

hashLength

Byte-length of the generated hash, must be greater than or equal to 8. Default is 16.

saltLength

Byte-length of the salt value. Default is 16.

n

CPU/Memory cost. Must be greater than 1, a power of 2, and less than 2^(128 * r / 8). Default is 32768.

p

Parallelization. Must be a positive integer less than or equal to Integer.MAX_VALUE / (128 * r * 8). Default is 1.

r

Block size. Must be greater than or equal to 1. Default is 8.

SHA-256

saltLength

Byte-length of the salt value. Default is 16.

This is the default hashing.

SHA-384

saltLength

Byte-length of the salt value. Default is 16.

SHA-512

saltLength

Byte-length of the salt value. Default is 16.

KBA attempts account lockout

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.

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, refer to Conditional User Stage.