--- title: Security questions description: 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. component: pingidm version: 7.5 page_id: pingidm:self-service-reference:selfservice-questions canonical_url: https://docs.pingidentity.com/pingidm/7.5/self-service-reference/selfservice-questions.html keywords: ["JSON", "Security Questions", "Configuration", "Authentication", "Self-Service", "User Self-Service"] section_ids: selfservice-questions-main: Security questions and self-registration kba-answer-hashing: KBA answer hashing kba-lockout: KBA attempts account lockout selfservice-questions-more: Prompt to update security questions --- # 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](#selfservice-questions-main). 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](#selfservice-questions-more). ## 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. ```json { "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 ([icon: street-view, set=fas]), 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]]>: > **Collapse: Using the Filesystem** > > Add the secureHash property to the `conf/selfservice.kba.json` file: > > ```json > "secureHash" : { > "algorithm": "{type}", > "configProp": value > } > ``` > > For example, to use BCRYPT hashing: > > ```json > "secureHash": { > "algorithm": "BCRYPT", > "cost": 13 > } > ``` > **Collapse: 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: ```json "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: ```json "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](stages/stage-conditional-user.html).