This guide describes common MFA use-cases and their solutions within the Cloudentity stack.

Note
 Each flow may be handled using the appropriate Cloudentity UI, or through direct API calls. These distinctions are made clear throughout this guide.

General

MFA flows begin with an initial, single-factor authentication. Identifier + password authentication is commonly used as the first factor, although other options exist such as federated login using SAML. The session token generated by a successful authentication may then be used for upgraded authentication using any of the MFA techniques. The flows described here assume that a valid session token has already been created for the user by some means.

Warning

The term "multi-factor" implies that some "first factor" of authentication has been satisfied. However, some of the advanced authentication techniques described in this document may be used as the first factor (in lieu of password or other common authentication techniques) for certain use-cases. For example, the API "Identifier + TOTP Authentication" exists for such cases.

In general, in this document the term "MFA" will be used in the context of stepped-up, non-first-factor authentication.

Time-based One-Time Password (TOTP)

Time-based One-Time Password (TOTP) Authentication uses the current time to generate a random code based on some secret only made known to the user. If the user submits the code and it matches the system-generated code corresponding to that user account, the user’s identity is trusted and authentication succeeds. The code is only valid for a short period of time (typically 30 seconds) before a new code is generated.

Any application which supports TOTP may be used for TOTP Authentication in the Cloudentity system. Mobile apps which support TOTP include:

  • Google Authenticator (GA): available for free at Google Play or the App Store. Google Authenticator is used throughout this document.

  • Microsoft Authenticator: available for free at Google Play or the App Store.

By entering the TOTP secret into the mobile app, the app can consistently supply up-to-date codes which the user may submit for authentication.

Warning
 The original name of TOTP Authentication in the Cloudentity stack was "Google Authentication". This name can still be found in various places in the stack, for backward-compatibility reasons; for example, the value of mfaMethod corresponding to TOTP MFA is "GOOGLE_AUTHENTICATION".
Note

Relevant user attributes for TOTP MFA:

  • googleAuthSecret: TOTP secret used as a seed for TOTP generation. Only visible to the user during TOTP setup phase.

  • googleAuthSecretAccepted: "true"|"false" Whether this user has completed setup of TOTP.

TOTP Setup

A setup phase is required before TOTP can be used for authentication.

1. Initializing the TOTP secret

When a new user is registered in the Cloudentity system, a TOTP secret (attribute name googleAuthSecret) is generated and stored with the user record. The user’s googleAuthSecretAccepted status is also initialized to "false".

2. Retrieving the TOTP secret

The TOTP secret can be viewed by an authenticated user through the self-service "Get Auth Secret" API:

API — Get Auth Secret (Self-Service)

Request (example):

GET /user/authsecret
token: ac74d01d-1c47-4aad-bdaf-085769c33674

Response (example):

200 OK

{
 "googleAuthSecret": "24JEEBYXSOPXYFFU"
}

In the AuthN UI, TOTP users whose TOTP secret has not yet been accepted will be guided to the "TOTP Authentication Setup" screen to retrieve the TOTP secret:

TOTP Setup
Figure 1. TOTP Setup
Note

The TOTP secret (googleAuthSecret) is considered to be a sensitive attribute. It cannot be viewed:

  • by any other user or admin

  • through any other API

  • if the user has already confirmed the TOTP secret (i.e. if googleAuthSecretAccepted is "true") — see below

3. Setting up TOTP Generation

The user must enter the TOTP secret into the TOTP mobile app or system to continue:

GA Setup
Figure 2. GA Setup

The user may select either of two setup types: "Scan barcode" or "Manual entry":

GA Setup Type
Figure 3. GA Setup Type

If the user’s mobile device has a QR code scanner, the QR code from the UI may be scanned to automatically record the username and TOTP secret:

GA QR Scan
Figure 4. GA QR Scan

If the user chooses not to use the QR code scanner, the TOTP secret may be entered manually:

GA Manual Entry
Figure 5. GA Manual Entry

Once the TOTP secret is entered, the TOTP app will begin to generate TOTPs:

GA TOTP
Figure 6. GA TOTP

4. TOTP confirmation

Before the TOTP can be used for authentication, the user must confirm that it has been set up properly by successfully submitting a TOTP code. This is done through the self-service "Confirm Auth Secret" API:

API — Confirm Auth Secret (Self-Service)

Request (example):

POST /user/authsecret/confirm
token: ac74d01d-1c47-4aad-bdaf-085769c33674
Content-Type: application/json

{
 "googlekey": "238079"
}

Response:

204 NO CONTENT

The TOTP may also be entered through the Authn UI’s TOTP Setup page.

Upon success, the user’s googleAuthSecretAccepted is set to "true", preventing further retrieval of the googleAuthSecret. An auth event may also be generated for this session indicating that the TOTP secret was confirmed.

Tip
Configuration Tip: Confirm Auth Secret

The relationship between TOTP secret confirmation and the overall authentication flow may be controlled by several options:

Invalidate sessions

A system configuration in the User Service controls session invalidation upon TOTP confirmation:

confirmAuthSecret {
  invalidateSessions = true|false
}

If true, any existing sessions of this user will be invalidated upon TOTP confirmation (including the current session). If false, the sessions will remain intact.

Automatic TOTP authentication

Certain authorization policies may choose to treat the TOTP confirmation auth event as equivalent to TOTP authentication. This has the effect of allowing the user to skip re-authentication once setup is completed.

TOTP Authentication

Once TOTP setup is completed, the user may authenticate using TOTP.

API — TOTP Authentication

Request:

POST /authn/totp
token: ac74d01d-1c47-4aad-bdaf-085769c33674
Content-Type: application/json

{
  "totpToken": "837482"
}

Response:

200 OK

Using the AuthN UI, the user must enter a valid TOTP generated from the TOTP app to proceed:

TOTP Authn
Figure 7. TOTP Authn

Upon success, a TOTP Authentication auth event is generated for the current session. Authorization policies which require this event will pass for this session.

TOTP Management

In order to protect a user account whose TOTP secret may have been compromised, it is possible to regenerate a TOTP secret for a user. An administrative user may reset the TOTP secret for a user using the administrative "Reset Auth Secret" API.

API — Reset Auth Secret (Administrative)

Request:

PUT /users/{identifier}/authsecret
token: 9412926c-009a-11e6-8d22-5e5517507c66

Response:

204 NO CONTENT

In the Administrative UI, the admin can perform this action in the User menu:

Reset Auth Secret
Figure 8. Reset Auth Secret

The action is completed once the admin clicks "Confirm":

Reset Auth Secret Confirmation
Figure 9. Reset Auth Secret Confirmation

Alternatively, an authenticated user may reset the TOTP secret using the self-service "Self Reset Auth Secret" API.

API — Reset Auth Secret (Self-Service)

Request:

PUT /user/authsecret
token: ac74d01d-1c47-4aad-bdaf-085769c33674

Response:

204 NO CONTENT

Upon success, a new TOTP secret is generated and stored in the user’s googleAuthSecret attribute, and TOTP confirmation is cleared (googleAuthSecretAccepted is reset to "false"). The user must complete TOTP setup again to be able to perform TOTP authentication.

One-Time Password (OTP)

One-Time Password (OTP) Authentication is achieved when a one-time password (OTP), generated and sent to the user via some messaging method, is correctly returned by the user as an authentication credential. Because the user is the owner of the destination address to which the OTP is sent, when the OTP is submitted correctly the user’s identity is trusted.

In the Cloudentity stack, the following messaging methods are available:

  • Email

  • SMS

  • Voice message

Note

Relevant user attributes for OTP MFA:

  • identifierEmails/identifierMobiles: OTP authentication is only allowed for email address or mobile numbers of a user which are marked as unique identifiers.

  • otpMethod: User’s preferred means of receiving an OTP (email, SMS, voice message).

  • otpMfaDestination: Default destination address (email or mobile) for authentication OTPs to be sent.

  • otpSetupComplete: Whether a default destination has been established and verified.

The flows described below are organized into several categories:

  • Explicit destination: The destination address is specified in the request.

  • Implicit destination: The destination address is inferred from the user’s otpMfaDestination and otpMethod attributes (not available during first-time OTP setup).

  • Masked destination: A masked identifier key is generated for the destination address and is submitted instead of the destination address itself.

OTP Setup

A setup phase is required before OTP can be used for authentication.

1. Generating and sending the setup OTP

The first step in OTP MFA authentication is to verify that the user is able to receive OTPs at the desired destination. The OTP can either be sent according to the explicit destination flow, or the masked destination flow.

Note
 Certain UI flows may skip this step, if the user already has a verified identifier email or mobile.
1a. Explicit destination flow

For the explicit destination flow, an OTP must be generated and delivered to the destination using the self-service "Setup OTP MFA" API.

API — Setup OTP MFA (Self-Service), Explicit Destination Flow

Request (explicit destination):

POST /user/otpmfa/setup
token: ac74d01d-1c47-4aad-bdaf-085769c33674
Content-Type: application/json

{
  "destination": "testuser@test.cloudentity.com",
  "destinationType": "E|M",
  "otpMethod": "E|M|V"
}

Request (resend to previous destination):

POST /user/otpmfa/setup
token: ac74d01d-1c47-4aad-bdaf-085769c33674
Content-Type: application/json

{}

Response (if send info configured — see Configuration Tip: Send Info):

202 ACCEPTED

{
  "destination": "testuser@test.cloudentity.com",
  "destinationType": "EMAIL|MOBILE",
  "deliveryMode": "EMAIL|SMS|VOICE",
  "codeType": "PLAINTEXT"
}

Response (if send info disabled):

204 NO CONTENT

Upon success, an OTP is generated and sent to the requested destination, using the requested messaging method. The destination and delivery method are stored in the user’s otpMfaDestination and otpMethod attributes, respectively, and the user’s otpSetupComplete is set to false. If the destination address was not already a registered address for the user, it will be automatically added as an unverified email or mobile of the user (based on the requested destinationType).

If an OTP has already been sent to the user, the request may be replayed by calling the "Setup OTP MFA" API with an empty request body — in this case, the user’s otpMfaDestination and otpMethod will be used to generate and send an OTP to the original destination by the original method.

Tip
Configuration Tip: Send OTP Parameters

In the Cloudentity User Service, many APIs are capable of sending messages to users by various means ("message-sending" APIs). The OTP action ID and expiration time may be independently configured for each of these APIs. For example, an API which generates OTPs used for MFA, expiring in 15 minutes, would have the following configuration:

otp {
  <api_identifier_key> {
    action = "mfaChallenge"
    expirationTimeInMinutes = 15
  }
  ...
}

Tip
Configuration Tip: Send Info

For each message-sending API, a system configuration exists to enable or disable the inclusion of details about the delivery in the response body.

sendInfo {
  <api_identifier_key> {
    returnSendInfo = true|false
    maskDestinationInResponse = true|false
  }
  ...
}

If returnSendInfo is true, the delivery details will be included in the response. If maskDestinationInResponse is true, the destination will be masked according to the system configuration for email and mobile address masking.

Example response body when returnSendInfo = true and maskDestinationInResponse = true:

{
  "destination": "*******3567",
  "destinationType": "MOBILE",
  "deliveryMode": "SMS",
  "codeType": "PLAINTEXT"
}
1b. Masked destination flow

The masked destination flow allows users to specify a destination based on a generated identifier key corresponding to that destination, rather than submitting the destination directly. Before the MFA-setup OTP can be generated, the user’s destination addresses must be masked using the self-service "Get Masked User Identifiers" API:

API — Get Masked User Identifiers (Self-Service)

Request:

GET /user/identifiers/masked
token: ac74d01d-1c47-4aad-bdaf-085769c33674

Response:

200 OK

{
  "emails": [
    {
      "key": "28adecc0-4441-11e6-beb8-9e71128cae77",
      "masked": "t******r@t***************.com",
      "isDefault": true|false,
      "isVerified": true|false
    },
    ...
  ],
  "mobiles": [
    {
      "key": "d5243fa0-709d-46d7-b8c3-1704dc92df8f",
      "masked": "*******3567",
      "isDefault": true|false,
      "isVerified": true|false
    },
    ...
  ],
  "otpMfaDestination": "*******3567",
  "otpMethod": "E|M|V"
}

Once the masked identifiers keys are created, an OTP must be generated and delivered to the destination (specified using the corresponding masked identifier key) using the self-service "Setup OTP MFA" API.

API — Setup OTP MFA (Self-Service), Masked Destination Flow

Request (masked destination):

POST /user/otpmfa/setup
token: ac74d01d-1c47-4aad-bdaf-085769c33674
Content-Type: application/json

{
  "otpMethod": "E|M|V",
  "maskIdentifierKey": "d5243fa0-709d-46d7-b8c3-1704dc92df8f"
}

Request (resend to previous destination):

POST /user/otpmfa/setup
token: ac74d01d-1c47-4aad-bdaf-085769c33674
Content-Type: application/json

{}

Response (if send info configured — see Configuration Tip: Send Info):

202 ACCEPTED

{
  "destination": "5555553567",
  "destinationType": "EMAIL|MOBILE",
  "deliveryMode": "EMAIL|SMS|VOICE",
  "codeType": "PLAINTEXT"
}

Response (if send info disabled):

204 NO CONTENT

2. Confirming OTP setup

Once the OTP has been sent to the destination, the user must return it through the self-service "Confirm OTP MFA Setup" API, in order to verify the destination address. This step is performed in the same manner, regardless of whether the OTP was sent according to the explicit destination or masked destination flow.

API — Confirm OTP MFA Setup (Self-Service)

Request:

POST /user/otpmfa/confirm
token: ac74d01d-1c47-4aad-bdaf-085769c33674
Content-Type: application/json

{
  "code": "255540"
}

Response:

204 NO CONTENT

Upon success, the email or mobile address is upgraded to "verified" status, and the user’s otpSetupComplete is set to true. An auth event may also be generated for the current session indicating that OTP setup is completed.

Tip
Configuration Tip: Automatic OTP authentication

Certain authorization policies may choose to treat the OTP setup auth event as equivalent to OTP authentication. This has the effect of allowing the user to skip re-authentication once setup is completed.

OTP Authentication

Once OTP MFA setup is completed, the user may perform OTP authentication by receiving and successfully returning an OTP challenge.

1. Send OTP Challenge

The OTP challenge may be generated and sent according to the explicit destination flow, or through the masked destination flow.

1a. Explicit destination flow

To send the OTP challenge according to the explicit destination flow, the self-service "Send Authentication OTP" API must be called with a destination address and delivery mode specified:

API — Send Authentication OTP (Self-Service), Explicit Destination Flow

Request:

POST /user/authn/otp/send
token: ac74d01d-1c47-4aad-bdaf-085769c33674
Content-Type: application/json

{
  "destination": "testuser@test.cloudentity.com",
  "deliveryMode": "E|M|V"
}

Response (if send info configured — see Configuration Tip: Send Info):

202 ACCEPTED

{
  "destination": "testuser@test.cloudentity.com",
  "destinationType": "EMAIL|MOBILE",
  "deliveryMode": "EMAIL|SMS|VOICE",
  "codeType": "PLAINTEXT"
}

Response (if send info disabled):

204 NO CONTENT
1b. Implicit destination flow

To send the OTP challenge according to the implicit destination flow, the self-service "Send Authentication OTP" API must be called with an empty request body. The OTP will be generated and sent according to the user’s otpMfaDestination and otpMethod attributes.

API — Send Authentication OTP (Self-Service), Explicit Destination Flow

Request:

POST /user/authn/otp/send
token: ac74d01d-1c47-4aad-bdaf-085769c33674
Content-Type: application/json

{}

Response (if send info configured — see Configuration Tip: Send Info):

202 ACCEPTED

{
  "destination": "testuser@test.cloudentity.com",
  "destinationType": "EMAIL|MOBILE",
  "deliveryMode": "EMAIL|SMS|VOICE",
  "codeType": "PLAINTEXT"
}

Response (if send info disabled):

204 NO CONTENT
1c. Masked destination flow

To to send the OTP challenge using a masked identifier, the self-service "Get Masked User Identifiers" API must have been called first. See API — Get Masked User Identifiers (Self-Service) for details.

Once the masked identifier has been generated, the self-service "Send Authentication OTP" API may be called:

API — Send Authentication OTP (Self-Service), Masked Destination Flow

Request:

POST /user/authn/otp/send
token: ac74d01d-1c47-4aad-bdaf-085769c33674
Content-Type: application/json

{
  "deliveryMode": "E|M|V",
  "maskIdentifierKey": "d5243fa0-709d-46d7-b8c3-1704dc92df8f"
}

Response (if send info configured — see Configuration Tip: Send Info):

202 ACCEPTED

{
  "destination": "5555553567",
  "destinationType": "EMAIL|MOBILE",
  "deliveryMode": "EMAIL|SMS|VOICE",
  "codeType": "PLAINTEXT"
}

Response (if send info disabled):

204 NO CONTENT

Using the AuthN UI, an OTP MFA user may request an OTP challenge:

Send OTP Challenge
Figure 10. Send OTP Challenge

Once the OTP has been sent, the UI prompts for the OTP:

Complete OTP Challenge
Figure 11. Complete OTP Challenge

2. Complete OTP Authentication

2a. Retrieve OTP

The OTP value may be retrieved from an email, SMS message or voice message:

Retrieve OTP from Email
Figure 12. Retrieve OTP from Email
Retrieve OTP from SMS
Figure 13. Retrieve OTP from SMS
2b. Complete OTP Authentication

Once the OTP has been received, OTP authentication can be completed by calling the "OTP Authentication" API. This step is performed in the same manner, regardless of whether the OTP was sent according to the explicit destination, implicit destination or masked destination flow:

API — OTP Authentication

Request:

POST /authn/otp
token: ac74d01d-1c47-4aad-bdaf-085769c33674
Content-Type: application/json

{
  "otp": "5003512803"
}

Response:

200 OK

The OTP may also be submitted using the AuthN UI:

OTP Authenticate
Figure 14. OTP Authenticate

OTP Management

Reset OTP MFA Enrollment

In order to protect a user account whose credentials may have been compromised, it is possible to clear OTP MFA enrollment for a user. An administrative user may reset user’s otpMfaDestination, otpMethod and otpSetupComplete attributes using the administrative "Reset OTP MFA Enrollment" API:

API — Reset OTP MFA Enrollment (Administrative)

Request:

DELETE /users/{identifier}/otpmfa/reset
token: 9412926c-009a-11e6-8d22-5e5517507c66

Response:

204 NO CONTENT

Change OTP MFA Destination

Users who have completed OTP MFA enrollment can change their own default OTP destination. This flow begins by sending a verification OTP to the desired new address, using the self-service "Send Verification Code" API:

API — Send Verification Code (Self-Service)

Request:

POST /user/identifier/verification/send
token: ac74d01d-1c47-4aad-bdaf-085769c33674
Content-Type: application/json

{
  "destination": "testuser2@test.cloudentity.com",
  "deliveryMode": "E|M|V",
  "codeType": "P" // Must be set to "P" for this flow, to send a plaintext OTP
}

Response (if send info configured — see Configuration Tip: Send Info):

202 ACCEPTED

{
  "destination": "testuser2@test.cloudentity.com",
  "destinationType": "EMAIL|MOBILE",
  "deliveryMode": "EMAIL|SMS|VOICE",
  "codeType": "PLAINTEXT"
}

Response (if send info disabled):

204 NO CONTENT

Once the OTP has been received, the update can be completed using the self-service "Change OTP MFA Destination" API:

API — Change OTP MFA Destination (Self-Service)

Request:

POST /user/otpmfa/change
token: ac74d01d-1c47-4aad-bdaf-085769c33674
Content-Type: application/json

{
  "otp": "384923",
  "destination": "testuser2@test.cloudentity.com",
  "otpMethod": "E|M|V"
}

Response:

204 NO CONTENT

Knowledge-Based Authentication (KBA)

Knowledge-Based Authentication (KBA) is achieved when a user correctly answers questions whose answers would only be known by the user. Examples of such questions include:

  • "In what city were you married?"

  • "In what city was your high school?"

When correct answers are submitted, the user’s identity is trusted.

Note

Relevant user attributes for KBA MFA:

  • kbaResponseSet: The set of KBA question-answer pairs the user has setup in preparation for KBA authentication.

  • kbaPendingQuestions: A specific set of KBA challenge questions which the user must answer to complete KBA authentication.

KBA Global Config

The KBA system is governed by a global configuration object, which can be retrieved using the "Get KBA Config" API:

API — Get KBA Config

Request:

GET /config/kba

Response:

200 OK

{
  "kbaConfigId": "default",
  "kbaMinQuestionsPerUser": 1,
  "kbaMaxQuestionsPerUser": 4,
  "kbaQuestionSet": [
    {
      "questionIdentifier": "ldap.security.question.0",
      "questionPhrase": "In what city were you married?"
    },
    {
      "questionIdentifier": "ldap.security.question.1",
      "questionPhrase": "In what city was your high school?"
    },
    ...
  ]
}

The KBA config attributes are used for the following purposes:

  • kbaConfigId: Unique identifier for this KBA config. Always has the value "default".

  • kbaMinQuestionsPerUser: Minimum number of KBA questions to be answered by each user.

  • kbaMaxQuestionsPerUser: Maximum number of KBA questions which may be stored by each user.

  • kbaQuestionSet: Set of available questions which may be used for KBA.

    • questionIdentifier: Unique identifier for a KBA question (most KBA APIs utilize this value).

    • questionPhrase: Display phrase for a KBA question.

Warning
 The global KBA configuration is initialized upon deployment of the Cloudentity Stack. No APIs are exposed to update the KBA configuration.

KBA Setup

In order to set up KBA, the user must store personal responses to a set of questions. This can be done at user registration time (if using self-service "Register User" API), or with an authenticated session using the self-service "Set User KBA Responses" API:

API — Register User (Self-Service)

Request:

POST /user
Content-Type: application/json

{
  <other user attributes>
  ...
  "kbaResponseSet": [
    {
      "questionIdentifier": "ldap.security.question.0",
      "response": "new york"
    },
    ...
  ]
}

Response:

200 OK

{
  "uuid": "ed6d0412-e7a0-11e6-bf01-fe55135034f3"
}
API — Set User KBA Responses (Self-Service)

Request:

POST /user/kba
token: ac74d01d-1c47-4aad-bdaf-085769c33674
Content-Type: application/json

{
  "kbaResponseSet": [
    {
      "questionIdentifier": "ldap.security.question.0",
      "response": "new york"
    },
    ...
  ]
}

Response:

204 NO CONTENT
Note
 The number of responses the user provides may not exceed the global KBA config’s kbaMaxQuestionsPerUser, and may not be less than the kbaMinQuestionsPerUser.

The UI may be used to set KBA responses at registration time. If the user selects "Knowledge-based Authentication" for MFA Method, the user will be prompted to supply KBA responses:

MFA Method KBA
Figure 15. MFA Method KBA
Set KBA Responses
Figure 16. Set KBA Responses
Set KBA Responses Answered
Figure 17. Set KBA Responses Answered

Upon success of any of the above methods, the user’s responses will be hashed and stored in the user’s kbaResponseSet attribute. Any existing kbaPendingQuestions (i.e. from past authentications) will be cleared.

KBA Authentication

Once the user’s KBA responses are set up, the user can proceed to authentication.

1. KBA Challenge

The user must generate a set of challenge questions to answer by calling the self-service "Generate User KBA Challenge" API:

API — Generate User KBA Challenge (Self-Service)

Request:

PUT /user/kba/challenge
token: ac74d01d-1c47-4aad-bdaf-085769c33674

Response:

200 OK

{
  "kbaChallengeQuestions": [
    "ldap.security.question.0",
    "ldap.security.question.1"
  ]
}
Note
 The UI will automatically call this API when a KBA-enabled user completes their first-factor authentication.

Upon success, the challenge questions are stored in the user’s kbaPendingQuestions attribute. Until the user completes authentication or the KBA challenge is cleared, successive calls to generate a KBA challenge will yield the same question set.

Note

The global KBA config’s kbaMinQuestionsPerUser attribute determines the number of challenge questions generated. If the user supplied responses for more than this number of questions, kbaMinQuestionsPerUser questions will be randomly selected from among the user’s response set.

2. KBA Authentication

Once a KBA challenge is generated, the user must respond to exactly this set of questions for authentication to succeed.

API — KBA Authentication

Request:

POST /authn/kba
token: ac74d01d-1c47-4aad-bdaf-085769c33674
Content-Type: application/json

{
  "kbaResponseSet": [
    {
      "questionIdentifier": "ldap.security.question.0",
      "response": "new york"
    },
    {
      "questionIdentifier": "ldap.security.question.1",
      "response": "boston"
    }
  ]
}

Response:

200 OK

The UI displays the KBA challenge view:

KBA Challenge
Figure 18. KBA Challenge
KBA Challenge Answered
Figure 19. KBA Challenge Answered

Upon success, a KBA Authentication auth event is generated for the current session. Authorization policies which require this event will pass for this session.

KBA Management

In order to protect a user account whose KBA answers may have been compromised, an admin can reset the user’s KBA responses using the "Reset User KBA" API:

API — Reset User KBA (Administrative)

Request:

DELETE /users/{identifier}/kba
token: 9412926c-009a-11e6-8d22-5e5517507c66

Response:

204 NO CONTENT

Upon success, the user’s kbaResponseSet is cleared, forcing the user to set up KBA responses again. Any existing challenge questions for the user are also cleared.

Supplementary Features

Preferred MFA Method

A user attribute, mfaMethod, is available to specify the user’s preferred means of MFA. Authorization policies may utilize this attribute to direct a user through an MFA flow. Authenticated users may update their mfaMethod using the self-service "Set MFA Method" API:

API — Set MFA Method (Self-Service)

Request:

PUT /user/mfamethod
token: ac74d01d-1c47-4aad-bdaf-085769c33674
Content-Type: application/json

{
  "mfaMethod": "NONE|GOOGLE_AUTHENTICATION|OTP|KBA"
}

Reset MFA Credentials

This flow provides a reset path to a user who has forgotten an MFA credential.

An administrative user sends a verification OTP or encrypted code to a user to reset MFA for a specific type. Verification of the code partially authenticates the user, enabling further action based on authorization policy configuration.

The flow begins with an admin calling the "Request Reset MFA Credentials" API, providing a specific MFA type for which this reset is valid. The provided destination must be among the target user’s email or mobile addresses.

API — Request Reset MFA Credentials (Administrative)

Request:

POST /users/{identifier}/mfa/reset
token: 9412926c-009a-11e6-8d22-5e5517507c66
Content-Type: application/json

{
  "mfaMethod": "GOOGLE_AUTHENTICATION|OTP|KBA"
  "destination": "testuser@test.cloudentity.com",
  "deliveryMode": "E|M|V",
  "codeType": "P|E"
}

Response (if send info configured — see Configuration Tip: Send Info):

202 ACCEPTED

{
  "destination": "testuser@test.cloudentity.com",
  "destinationType": "EMAIL|MOBILE",
  "deliveryMode": "EMAIL|SMS|VOICE",
  "codeType": "PLAINTEXT|ENCRYPTED"
}

Response (if send info disabled):

204 NO CONTENT

Once the verification OTP or encrypted code is received, the user may call the "Verify Reset MFA Credentials" API:

API — Verify Reset MFA Credentials

Request (encrypted verification code):

POST /user/mfa/reset/verify
Content-Type: application/json

{
  "code": "V29jUTFqRl..."
}

Request (plaintext OTP):

POST /user/mfa/reset/verify
Content-Type: application/json

{
  "code": "384956",
  "identifier": "testuser",
  "mfaMethod": "GOOGLE_AUTHENTICATION|OTP|KBA"
}

Response:

200 OK

{
  "token": "ac74d01d-1c47-4aad-bdaf-085769c33674"
}

The session generated by this API is granted an auth event specific to that MFA type. Policies may use these auth events to allow users access to additional, alternative-login resources.