Skip to main content

External authentication with a second factor

Use this raw HTTP example when your application completes the first factor outside IDaaS and then uses the Authentication API to determine whether an IDaaS second factor is required.

Your application must verify the external first factor before starting this flow. Configure the Authentication API application's resource rule to use EXTERNAL as the first authentication step for the applicable risk level. The Authentication API does not perform the external authentication represented by this step.

The example assumes that the Authentication API application uses Provided in the API as its client IP source. Include the same end-user IP address in every request that can evaluate IP-based risk factors.

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",
  "clientIp": "<end-user-public-ip-address>"
}

The response identifies EXTERNAL and the second factors available to the user:

{
  "authenticationTypes": ["EXTERNAL"],
  "availableSecondFactor": ["TOKENPUSH", "TOKEN", "OTP"],
  "token": "<external-authentication-token>"
}

Complete the external first factor​

  • Method: POST
  • Path: /api/web/v1/authentication/users/authenticate/EXTERNAL/complete
  • Authorization: Bearer <external-authentication-token>
  • Content type: application/json
{
  "applicationId": "11111111-1111-1111-1111-111111111111",
  "clientIp": "<end-user-public-ip-address>"
}

If the resource rule requires a second factor, the response returns an intermediate token:

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

If no second factor is required, authenticationCompleted is true, and token contains the IDaaS authentication JWT:

{
  "authenticationCompleted": true,
  "token": "<idaas-jwt>"
}

Request the second-factor challenge​

Select a value from availableSecondFactor. This example requests an OTP challenge.

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

Store the returned challenge token:

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

Complete the second factor​

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

When the second factor succeeds, the response contains the IDaaS authentication JWT:

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

For complete risk-context examples, including machine authentication, see Risk-based authentication.