User Authentication with MFA

This authentication use case includes Multi-Factor Authentication options, also known as Two Step Verification. In cases where a user has configured their profiles to use Multi-Factor Authentication (MFA), an additional prompt for a verification code appears after the Authenticate User Process consumes the authN ID and credential. Once a verification code has been obtained by the user (by either receiving an e-mail or SMS message, or by obtaining one through a previously configured authenticator app) and provided to the client, the Process then consumes the code and authenticates the user. The Process returns a successful response that indicates the user has been authenticated to Digital Identity Management, and the client can proceed to make requests to protected APIs (e.g., retrieve details about the User entity, associated Groups and Accounts, etc.). [product: dim]

[/product: dim]

Initial Request

The client calls the Session Start API to initialize the Process. The user’s credentials are included in the request body:

**REQUEST - POST https://\{your.url\}/session/start**
{
   "authnIdentifier": "jane.smith@example.ca",
   "credential": "5oodP@s$word321"
}

`authnIdentifier`	The user’s registered email address, mobile number, or alias (if any)
`credential`	The user’s password

(Conditional) Response: Select the desired MFA option

If the user has configured more than one two-factor authentication method (e.g. both an e-mail address and mobile phone number, or e-mail address and authenticator app), then the Process prompts for the user to select which method they would like to use in order to obtain their verification code. The Process provides a list of available methods to ease selection. Methods are obfuscated in the response to the client, so as not to unintentionally reveal sensitive information to those who should not see it, whether it’s another individual observing the user, or an unauthorized individual attempting to gain access to a User profile. If the user has only one configured two-factor authentication method, this step is not performed by the Process and instead the Process provides the next response in this flow (the prompt to provide the verification code).

**RESPONSE - body**
{
   "processId": "eec918ff-5db4-4fee-a601-5ff76a099c8e",
   "processName": "authentication.AuthenticateUser.v1.0",
   "stepName": "TwoFAMethodPrompt",
   "displayMessage": "Please input required information",
   "output": {
      "twoFAMethods": {
         "1": "f****@operator.com",
         "2": "(4**)***-***6"
      }
   },
   "parameters": {
      "twoFAMethodOptionId": "String"
    }
}

`processId`	Unique identifier for the current instance of this Process.
`processName`	Full name of the Process, including the category and version number.
`stepName`	Name of the specific step that the Process is currently on.
`displayMessage`	Optional message that the UI can display to the user.
`output`	Object that contains additional data that the client can retrain and use for additional operations beyond the Process. In this case, the client can use the output to display a list of obfuscated MFA options to the user.
`twoFAMethods`	Object that contains key/value pairs of available MFA options, where the key is an index for selection and the value is the obfuscated authN ID (or authenticator app, if configured).
`parameters`	Object that specifies the info this Process requires to continue its task.
`twoFAMethodOptionId`	Request to provide the index of the selected two-factor authentication method.

Request: Provide MFA selection

The user selects their preferred MFA option, and the client passes that selection to the Process with the Process Step:

**REQUEST - PUT https://\{your.url\}/process/step**
{
   "processId": "3fe5e67a-5200-408b-bb75-1fbe3385c094",
   "parameters": {
      "twoFAMethodOptionId": "1"
    }
}

`processId`	Unique identifier for the current instance of this Process.
`parameters`	Object that contains the data requested in the previous Process response.
`twoFAMethodOptionId`	The index of the selected MFA option, from the list of available indexes returned in the previous response.

Response: Prompt for MFA code

If the user provides valid credentials, the Digital Identity Management then sends the code to that option (either to the authentication app, or directly to the authN ID contact channel). The Process requests that code from the client, and provides the Proof Key for Action Token (handled transparently by a UI without user intervention). In addition to this, the Process response provides an option for the user to specify that they want to trust the current device. If the user opts to trust this device, subsequent authentication attempts from this device will not prompt for MFA. Other non-trusted devices will continue to use the MFA flow.

**RESPONSE - body**
{
   "processId": "eec918ff-5db4-4fee-a601-5ff76a099c8e",
   "processName": "authentication.AuthenticateUser.v1.0",
   "stepName": "TwoFACodePrompt",
   "displayMessage": "Please input required information",
   "output": {
      "pkat": "babec3b7-96b5-47f4-b697-4683820d55af",
      "attemptsRemaining": 5
   },
   "parameters": {
      "code": "String",
      "pkat": "String",
      "trustedDevice": "Boolean"
   }
}

`processId`	Unique identifier for the current instance of this Process.
`processName`	Full name of the Process, including the category and version number.
`stepName`	Name of the specific step that the Process is currently on.
`displayMessage`	Optional message that the UI can display to the user.
`output`	Object containing additional data that the client can retrain and use for additional operations beyond the Process.
`parameters`	Object that specifies the info this Process requires to continue its task.
`pkat`	Unique Proof Key for Action Token that corresponds to an existing action token.
`attemptsRemaining`	The number of attempts remaining to input a valid code. If this limit is reached, the process ends without successful authentication.
`code`	The verification code to enter, obtained via e-mail, SMS or an authenticator app (dependent on how the user configures MFA).
`trustedDevice`	If this device should be considered a trusted device, removing the need for subsequent MFA requests during authentication attempts from this device.

Request: Provide MFA code

Using the Process Step API, the client submits the verification code obtained from the user, as well as the Proof Key for Action Token obtained from the previous response. If the user selects to trust this device, then the client includes that in the request as well:

**REQUEST - PUT https://\{your.url\}/process/step**
{
   "processId": "eec918ff-5db4-4fee-a601-5ff76a099c8e",
   "parameters": {
      "code": "189635",
      "pkat": "babec3b7-96b5-47f4-b697-4683820d55af",
      "trustedDevice": "false"
    }
}

`processId`	Unique identifier for the current instance of this Process.
`parameters`	Object that contains the data requested in the previous Process response.
`pkat`	Unique Proof Key for Action Token that corresponds to an existing action token.
`code`	The verification code to enter, obtained via e-mail, SMS or an authenticator app (dependent on how two-factor authentication was configured by the user).
`trustedDevice`	If this device should be considered a trusted device, removing the need for subsequent two-factor authentication requests during authentication attempts from this device.

Process Complete

If the user provides a valid verification code the Process responds with an HTTP 200 status code, and user details in the body:

**RESPONSE - body**
{
   "processId": "eec918ff-5db4-4fee-a601-5ff76a099c8e",
   "lastStep": true,
   "runtimeId": 229,
   "userId": 12345,
   "userAuthenticated:" true
}

`processId`	The unique identifier for this instance of the Process.
`lastStep`	Boolean that indicates whether or not this was the last step in the Process.
`runtimeId`	Identifier of the Digital Identity Management Runtime entity currently associated to the Digital Identity Management User entity.About Runtime Entities:Upon user creation or authentication, Digital Identity Management looks for a JRUNTIMEID cookie in the user’s browser or application. If no cookie is found, Digital Identity Management creates a Runtime Entity with a unique ID and associates it to the user during the login phase. Digital Identity Management will generate and pass a corresponding JRUNTIMEID cookie for clients to store and return with subsequent requests.
`userId`	The unique identifier of the current user.
`userAuthenticated`	Boolean that indicates if the user was authenticated into Digital Identity Management.
The client application retains the User and Runtime entity IDs to use with the Digital Identity Management APIs to perform CRUD operations against those (and other associated) entities.

Parent topic:Authenticate User Process

Home

Guides

APIs

Initial Request

(Conditional) Response: Select the desired MFA option

Request: Provide MFA selection

Response: Prompt for MFA code

Request: Provide MFA code

Process Complete

​Initial Request

​(Conditional) Response: Select the desired MFA option

​Request: Provide MFA selection

​Response: Prompt for MFA code

​Request: Provide MFA code

​Process Complete

Initial Request

(Conditional) Response: Select the desired MFA option

Request: Provide MFA selection

Response: Prompt for MFA code

Request: Provide MFA code

Process Complete