Skip to main content

Two-factor authentication

Use this raw HTTP example to complete password authentication followed by an OTP second factor. Before starting, configure an Authentication API application, assign it a resource rule that requires this flow, and assign the selected authenticators to the user.

The flow has five requests:

  1. Query the user's authenticators.
  2. Request the first-factor challenge.
  3. Complete the first factor.
  4. Request the second-factor challenge.
  5. Complete the second factor.

Query the user's authenticators​

  • Method: POST
  • Path: /api/web/v2/authentication/users
  • Content type: application/json
{
  "userId": "jsmith",
  "applicationId": "11111111-1111-1111-1111-111111111111"
}

The response identifies the combined flow and the available second factors:

{
  "authenticationTypes": ["PASSWORD_AND_SECONDFACTOR"],
  "availableSecondFactor": ["TOKENPUSH", "TOKEN", "OTP"]
}

Request the first-factor challenge​

  • Method: POST
  • Path: /api/web/v2/authentication/users/authenticate/PASSWORD_AND_SECONDFACTOR
  • Content type: application/json
{
  "userId": "jsmith",
  "applicationId": "11111111-1111-1111-1111-111111111111"
}

Store the returned challenge token:

{
  "authenticationCompleted": false,
  "token": "<first-factor-challenge-token>"
}

Complete the first factor​

  • Method: POST
  • Path: /api/web/v1/authentication/users/authenticate/PASSWORD_AND_SECONDFACTOR/complete
  • Authorization: Bearer <first-factor-challenge-token>
  • Content type: application/json
{
  "applicationId": "11111111-1111-1111-1111-111111111111",
  "response": "<user-password>"
}

The first factor does not complete the overall flow. Store the new token returned for the second-factor selection:

{
  "authenticationCompleted": false,
  "token": "<first-factor-token>"
}

Request the second-factor challenge​

  • Method: POST
  • Path: /api/web/v2/authentication/users/authenticate/PASSWORD_AND_SECONDFACTOR
  • Content type: application/json
{
  "applicationId": "11111111-1111-1111-1111-111111111111",
  "secondFactorAuthenticator": "OTP",
  "authToken": "<first-factor-token>"
}

IDaaS sends the OTP and returns another challenge token:

{
  "authenticationCompleted": false,
  "token": "<second-factor-challenge-token>",
  "otpdeliveryType": "SMS"
}

Complete the second factor​

  • Method: POST
  • Path: /api/web/v1/authentication/users/authenticate/PASSWORD_AND_SECONDFACTOR/complete
  • Authorization: Bearer <second-factor-challenge-token>
  • Content type: application/json
{
  "applicationId": "11111111-1111-1111-1111-111111111111",
  "response": "123456",
  "secondFactorAuthenticator": "OTP"
}

When both factors succeed, the response contains the IDaaS authentication JWT:

{
  "firstName": "John",
  "lastName": "Smith",
  "authenticationCompleted": true,
  "token": "<idaas-jwt>"
}