EXTERNAL plus second-factor authentication

Use this page when your client completes first-factor authentication outside of Entrust Identity as a Service and then calls the Authentication API to determine whether second-factor authentication is required.

In this type of authentication, a client has already completed the first factor authentication outside of Identity as a Service and uses Identity as a Service to determine if second-factor authentication is necessary.

This section describes how to use the Identity as a Service's Authentication APIs to complete, if required, second-factor authentication. The API calls required are similar to those required for single-factor authentication:

Get User's Authenticators
Complete EXTERNAL Authentication (the result indicates if second-factor is required)
Select Authenticator (Second-factor)
Complete Authentication Challenge (Second-factor)

Flow behavior

If the Authentication API application is configured such that the client does not need to perform second-factor authentication, the client will receive an authenticated JWT in step 2.
To use some of the risk conditions, the client IP address must be made available to Identity as a Service in all requests. You define the source of the client IP address when the Authentication API application is created. The examples below assume that you selected Provided in the API.

Get User's Authenticators

The first step is to submit a POST request to get all the authenticators that can be used. For example:

https://customer.region.trustedauth.com/api/web/v2/authentication/users

The body of this request should contain a JSON object with User ID (containing the user id or a user alias value) and the ID of the Authentication API application being accessed. For example:

{
  "userId": "jsmith",
  "applicationId": "1111111-111111-111111-11111111",
  "clientIp": "1.2.3.4"
}

A response with a JSON object to the API request is received. The response includes the authenticationTypes attribute marked as EXTERNAL. It also includes the availableSecondFactor attribute showing all the authenticators that can be used for second-factor authentication. For example:

{
  "availableSecondFactor": ["TOKENPUSH", "TOKEN", "OTP"],
  "userMachineSettings": {
    "machineAuthenticatorEnabled": true,
    "deviceFingerprintRequired": false,
    "attributeExclusions": [],
    "userMachineAuthenticators": []
  },
  "machineAuthenticator": null,
  "authenticationTypes": ["EXTERNAL"],
  "time": 1521647783740,
  "otpDeliveryInfo": {
    "otpDefaultDelivery": "SMS",
    "availableOTPDelivery": ["SMS", "EMAIL", "VOICE"]
  }
}

Complete first-factor authentication

The next step is to complete the first-factor EXTERNAL authentication to determine if second-factor authentication is required. A POST request to complete the EXTERNAL authentication challenge would be sent to the following URL:

https://customer.region.trustedauth.com/api/web/v1/authentication/users/authenticate/EXTERNAL/complete

As in the first example, this request will also include an Authorization header field. The Authorization header can be sent with or without a type value of "Bearer". For example:

Authorization: Bearer <token>

Authorization: <token>

The body of this request should contain a JSON object with the ID of the API application being accessed. For example:

{
  "applicationId": "1111111-111111-111111-11111111",
  "clientIp": "1.2.3.4"
}

The response received from this request would include a new token and the authenticationCompleted attribute that would be marked as false. For example:

{
  "status": null,
  "firstName": null,
  "lastName": null,
  "authenticationCompleted": false,
  "machineAuthenticator": null,
  "userMachineSettings": {
    "machineAuthenticatorEnabled": true,
    "deviceFingerprintRequired": false,
    "attributeExclusions": [],
    "userMachineAuthenticators": []
  },
  "kbaChallenge": null,
  "token": "GO7mOyRuLzfTOXLk/IbzsDEuw8cFQspxz8TCWRwcrrhtoBw/o7udXt94eTkbkDFcbMVpfqHZJcJ4vavS4MEN6wp0d7MFhd0n9A9XymY5KHKyMvrqJlqh8+NrIZjkiA0sZvrAhu+6IRGfTYfoe/DwWclJi2JNNxpMX/17b7QHZdrj5ItbJUp3wHhAswUX02uWn/Fxwnt3cxGVHgmtTaVfz42JBkiIeRcOiv81iJqfTuSrd+S29RqO4PCKYGw1pKhymottvV3eVGNxdPvwSrLgXusfuCyfAB8tGl047WJQOKaHZ7k4GbzC1QKjldNWHrMAtiLUMWaxgvpU/vANJUibIPXJ6+1i7X7U6THJJg4fBG+pJo8jPKPI1B+XxE1mNBdLdMEdfUSKwUqv3BGg8g+WsL+ZLkbSzrswuoyBKWioEVXkxUVDtRghDLDjiRFjyQMwD+MhvdoC46a10IMkz1G5kKkQ6xaTTwhkEsh2iGeWtn6WDcC0PILFX4NmiF/g650j41aFWAyOD5ULBKV04a2dYKdadGfaAH0=",
  "expires": 1521648936739,
  "otpdeliveryType": null,
  "time": 1521648060983
}

If the Authentication API application is configured in such a way that users with low risk score do not require second-factor authentication, in this step the user would be authenticated and the response would set authenticationCompleted to true, indicating that EXTERNAL plus second-factor authentication was successful.

Select Authenticator (Second-factor)

The next step is to send a POST request to use a specific second-factor authentication. All the available second-factor authenticator options were received in the first call we made. For example, with OTP, the request URL would be:

https://customer.region.trustedauth.com/api/web/v2/authentication/users/authenticate/OTP

The body of this request should contain a JSON object with the ID of the Authentication API application being accessed and the token that was received from the last request. For example:

{
  "applicationId": "1111111-111111-111111-11111111",
  "clientIp": "1.2.3.4",
  "authToken": "GO7mOyRuLzfTOXLk/IbzsDEuw8cFQspxz8TCWRwcrrhtoBw/o7udXt94eTkbkDFcbMVpfqHZJcJ4vavS4MEN6wp0d7MFhd0n9A9XymY5KHKyMvrqJlqh8+NrIZjkiA0sZvrAhu+6IRGfTYfoe/DwWclJi2JNNxpMX/17b7QHZdrj5ItbJUp3wHhAswUX02uWn/Fxwnt3cxGVHgmtTaVfz42JBkiIeRcOiv81iJqfTuSrd+S29RqO4PCKYGw1pKhymottvV3eVGNxdPvwSrLgXusfuCyfAB8tGl047WJQOKaHZ7k4GbzC1QKjldNWHrMAtiLUMWaxgvpU/vANJUibIPXJ6+1i7X7U6THJJg4fBG+pJo8jPKPI1B+XxE1mNBdLdMEdfUSKwUqv3BGg8g+WsL+ZLkbSzrswuoyBKWioEVXkxUVDtRghDLDjiRFjyQMwD+MhvdoC46a10IMkz1G5kKkQ6xaTTwhkEsh2iGeWtn6WDcC0PILFX4NmiF/g650j41aFWAyOD5ULBKV04a2dYKdadGfaAH0="
}

An API response is received after submitting the request. For example:

{
  "status": null,
  "firstName": null,
  "lastName": null,
  "authenticationCompleted": false,
  "machineAuthenticator": null,
  "userMachineSettings": {
    "machineAuthenticatorEnabled": true,
    "deviceFingerprintRequired": false,
    "attributeExclusions": [],
    "userMachineAuthenticators": []
  },
  "kbaChallenge": null,
  "token": "GMITwEPkGILJI/jBMVT3p8a09JtGag3AzXqjan1+FBNdWjnCi16JNdpNxrBt/iuFYlozZ2Jrf6V6JEZEuQeFtZtFyETEVKNOxhbbOf+u6SmkBSwLQQm529WKUtFssLnQ9Mliojlb/1W8VXkseazUhWuvpab9t7b4Y9BP9RcXdPNdAOtR++dGwuwtAh0O6Edq9SE4yDGn8aRWJuydc7k8aQymLZfFR76y0EbG4mP/m9kZ2pDOjUrhHa8rToLLx3Jr70aHqJr5bNyCrQ96/c+5YTQeLhFL86Ch8LcIAKHh5RI2Ma6X+PTBZ4CwMrU6jUczCjJ6m94jlwIH37P0vv2GdlMZHPqjjmAuHB2SGKA0UxQywL9SbsIhyM2lxhBLUK30wRH0LHlW4reki0vF9gfc+kZQZFaVyj/bJ0P63lTsIywEmPBbCo8o21A5Mram5m+kNcCLg4ZlIaM2bWrvtBX0SxL5Cpx7vy1cUABQw+4ifRgcrwt6KWgIngmu1y/ItwaLCGgvw2dCFd3kPHd+HoXzsb2aVP+9tqo=",
  "expires": 1521648936739,
  "otpdeliveryType": "SMS",
  "time": 1521648184761
}

The token received in this request would be used to complete the second-factor authentication in the next step.

Complete authentication challenge (Second-factor)

The last step is to send a POST request to complete the second-factor authentication challenge. For example:

https://customer.region.trustedauth.com/api/web/v1/authentication/users/authenticate/OTP/complete

As in the first example, this request will also include an Authorization header field. The Authorization header can be sent with or without a type value of "Bearer". For example:

Authorization: Bearer <token>

Authorization: <token>

The body of this request should contain a JSON object with the second-factor response, the ID of the application being accessed, and the second-factor authenticator being used. For example:

{
  "applicationId": "1111111-111111-111111-11111111",
  "response": "123456789",
  "clientIp": "1.2.3.4"
}

An API response is received after submitting the request. For example:

{
  "status": null,
  "firstName": "John",
  "lastName": "Smith",
  "authenticationCompleted": true,
  "machineAuthenticator": null,
  "userMachineSettings": null,
  "kbaChallenge": null,
  "token": "GENw36RGssBDAmU8UgULDBFGp2cG6aWDO0dWUQU24QyAIDo2KFzfr62MEymgHxlU17EkLPknUUCwXm/azikw04oG2qniwwZVlXghQBFoME3DvenPMCXobOeqRqyDOeLbfLWIXdlNK2jJFIpPcTQqe3puKlAis3VfwltcOgmnQTK2ZnQA6dOICTKa0Kfr+fvUg0fmdBJ8asvryswSdeNjw2ndO638uZYhYks+2QstKxTuHXsslECPPgxa1CCidWm3EDigpH2SJQ9W1FY06zq/8BQMu3sxivWGOtd1p7xg2LldXb0dnoeztI7OQSye/8NbBuzWOdGOrwTIlOSd6mECcsdMQadstzQLoAtdRCsYW0JDVhvaaNjg2l5l7d3Tte20AXKUAKLA4NTpDZSz8N74A7me1pDV5GUXY5BdhwQGqIKtwpQvzt5uv9W/inomGdr+RO9KZGOV4Nfvilqr2yxoo0HfWkNvcsqtUXrHYN4chauqTYB7vqBBQzvhK/ar7lXg4WAjbqAOUvJXhSpuG92dltNRC9TsttUyFZ4RljhyPAyh2MNevhnEIq/jd34BhYmGyUFyshrYQE/fRTI5UvGrSybUX9IJN8dpKua64GhOspO4",
  "expires": 1521648936739,
  "otpdeliveryType": null,
  "time": 1521648223398
}

This response would indicate authenticationCompleted as true. This indicates that two-factor authentication was successful.

Get User's Authenticators​

Complete first-factor authentication​

Select Authenticator (Second-factor)​

Complete authentication challenge (Second-factor)​

Get User's Authenticators

Complete first-factor authentication

Select Authenticator (Second-factor)

Complete authentication challenge (Second-factor)