Register authentication identifier as MFA

An end user registers one of their current email addresses or mobile numbers (already registered and verified as an authN ID) as an MFA option. [product: dim]

[/product: dim] Note: Although the end user is already authenticated when they invoke this Process, Digital Identity Management requires them to provide their password to “raise” their authentication level before adding or removing an external MFA security option.

Initial Request

Your client calls the Process Start API to initialize the Process:

**REQUEST - POST https://\{your.url\}/process/start/userManagement.RegisterAuthnIdentifierAsMFA.v1.0**
<no body>

Response: password prompt

Digital Identity Management checks to see if the current end user has a registered password. If they do, then the Process returns a prompt for that password.

**RESPONSE - body**
{
   "processId": "6901dc4f-1841-4671-b3a7-a5fb341488a0",
   "processName": "userManagement.RegisterAuthnIdentifierAsMFA.v1.0",
   "stepName": "PasswordPrompt",
   "lastStep": false,
   "displayMessage": "Please provide your password.",
   "parameters": {
      "password": "String"
   }
}

Note: If the end user onboarded with their social account, and do not have a registered password, then the Process returns an error, and ends.

`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.
`lastStep`	Boolean that indicates whether or not this was the last step in the Process.
`displayMessage`	Optional message the client can render for the end user.
`parameters`	Object that specifies the info this Process requires to continue its task.
`password`	The current Digital Identity Management User’s registered password.

Next Step: User provides password

The user enters their password, and your client passes it to Digital Identity Management in a Process Step API request:

**PUT https://\{your.url\}/process/step**
{
   "processId": "6901dc4f-1841-4671-b3a7-a5fb341488a0",
   "parameters": {
      "password": "L3tm3inplease"
   }
}

`processId`	Unique identifier for the current instance of this Process.
`parameters`	Object that contains the data that was requested in the previous Process response.
`password`	The current Digital Identity Management User’s registered password.

Response: Prompt to select authN ID

Digital Identity Management returns an indexed list of the current end user’s applicable authN IDs:

**RESPONSE - body**
{
   "processId": "6901dc4f-1841-4671-b3a7-a5fb341488a0",
   "processName": "userManagement.RegisterAuthnIdentifierAsMFA.v1.0",
   "stepName": "AuthnIdentifierPrompt",
   "displayMessage": "Please input required information",
   "output": {
      "authnIdentifiers": {
         "0": {
            "bob@example.com": "EMAIL"
         },
         "1": {
            "4161234567": "SMS"
         }
      }
   },
   "parameters": {
      "authnIdentifierId": "String"
   }
}

Note: Even if the end user has only one applicable authN ID, the Process returns that option in this format so that the end user can explicitly select to set that channel (email or mobile) is as their MFA option.

`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.
`lastStep`	Boolean that indicates whether or not this was the last step in the Process.
`output`	Object that contains data that the client can consume, retain, and use for additional operations.
`authNIdentifiers`	Object that contains one or more available Authentication Identifiers to select. Each name-value pairing provides an index (used for selection), and child object containing the value of the Authentication Identifier, as well as type for identification.
`parameters`	Object that specifies the info this Process requires to continue its task.
`authnIdentifierId`	The index of the chosen Authentication Identifier (obtained from the `authnIdentifiers` object).

Next Request: User selection

The end user selects their desired authN ID, and your client passes that choice to Digital Identity Management in a Process Step API request:

**PUT https://\{your.url\}/process/step**
{
   "processId": "6901dc4f-1841-4671-b3a7-a5fb341488a0",
   "parameters": {
      "authnIdentifierId": "0"
   }
}

`processId`	Unique identifier for the current instance of this Process.
`parameters`	Data object that contains the data requested in the previous Process response.
`authnIdentifierId`	The index of the chosen Authentication Identifier (obtained from the `authnIdentifiers` object from the previous response).

Response: Verification required

Digital Identity Management generates an action token, and sends it to the user as a One-Time Passcode (OTP) to the selected method (in an email or SMS). The Process then returns a Proof Key for Action Token (PKAT) to the client, and requests for it to be sent back along with the user-supplied OTP:

**RESPONSE - body**
{
   "processId": "6901dc4f-1841-4671-b3a7-a5fb341488a0",
   "processName": "userManagement.RegisterAuthnIdentifierAsMFA.v1.0",
   "stepName": "OTPPrompt",
   "displayMessage": "Please input required information",
   "output": {
      "pkat": "88e5ee81-0ea3-47d0-b724-5da55a303f89"
   },
   "parameters": {
      "pkat": "String",
      "otp": "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.
`lastStep`	Boolean that indicates whether or not this was the last step in the Process.
`output`	Object that contains data that the client can consume, retain, and use for additional operations.
`pkat`	Unique Proof Key for Action Token that corresponds to an existing action token.
`parameters`	Object that specifies the info this Process requires to continue its task.
`pkat`	The Proof Key for Action Token required in conjunction with the token value.
`otp`	The token value obtained from the message that Digital Identity Management sent to the chosen user authN ID.
Note: In most cases that involve an action token, that token is redeemed with the GET /session/token API to trigger a subsequent Process. However, this is a rare case where the current Process simply consumes the token and it’s corresponding PKAT in the body of the subsequent request.

Final Request: OTP verification

The end user retrieves the OTP from their email or SMS, and then supplies it to your client UI. You client then passes it (along with the PKAT) back through the Process Step API request:

**PUT https://\{your.url\}/process/step**
{
   "processId": "6901dc4f-1841-4671-b3a7-a5fb341488a0",
   "parameters": {
      "pkat": "88e5ee81-0ea3-47d0-b724-5da55a303f89",
      "otp": "102528"
   }
}

`processId`	Unique identifier for the current instance of this Process.
`parameters`	Data object that contains the data requested in the previous Process response.
`pkat`	The Proof Key for Action Token provided in the previous response.
`otp`	The short-token value obtained from the e-mail or SMS message sent to the chosen Authentication Identifier.

Process Complete

Digital Identity Management sets the selected email address or mobile number as an MFA option. On the back end, the system registers an “MFA” attribute on the selected User authN ID. The Process returns a 200 HTTP status:

**RESPONSE - body**
{
   "processId": "6901dc4f-1841-4671-b3a7-a5fb341488a0",
   "processName": "userManagement.RegisterAuthnIdentifierAsMFA.v1.0",
   "lastStep": true,
   "userAuthenticated": "false"
}

Parent topic:Register Email or Mobile as MFA Process

Home

Guides

APIs

Initial Request

Response: password prompt

Next Step: User provides password

Response: Prompt to select authN ID

Next Request: User selection

Response: Verification required

Final Request: OTP verification

Process Complete

​Initial Request

​Response: password prompt

​Next Step: User provides password

​Response: Prompt to select authN ID

​Next Request: User selection

​Response: Verification required

​Final Request: OTP verification

​Process Complete

Initial Request

Response: password prompt

Next Step: User provides password

Response: Prompt to select authN ID

Next Request: User selection

Response: Verification required

Final Request: OTP verification

Process Complete