Two-factor authentication
Use this page when you want the raw HTTP flow for first-factor plus second-factor Authentication API challenges.
Two-factor authentication supports logging in by completing two-authentication challenges instead of one. This section describes how to use Identity as a Service's Authentication APIs to complete two-factor authentication. The API calls required are similar to those required for single-factor authentication:
- Get User's Authenticators
- Select Authenticator (First-factor)
- Complete Authentication Challenge (First-factor)
- Select Authenticator (Second-factor)
- Complete Authentication Challenge (Second-factor)
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 application being accessed. For example:
{
"userId": "jsmith",
"applicationId": "1111111-111111-111111-11111111"
}
An API response to the request is received. The response would include authenticationTypes marked as PASSWORD_AND_SECONDFACTOR. It would also include the section availableSecondFactor, 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": ["PASSWORD_AND_SECONDFACTOR"],
"time": 1521647783740,
"otpDeliveryInfo": {
"otpDefaultDelivery": "SMS",
"availableOTPDelivery": ["SMS", "EMAIL", "VOICE"]
}
}
Select Authenticator (First-factor)
The next step is to send a POST request to use first-factor authentication. It must be sent to a URL with PASSWORD_AND_SECONDFACTOR at the end of it. For example:
https://customer.region.trustedauth.com/api/web/v2/authentication/users/authenticate/PASSWORD_AND_SECONDFACTOR
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 application being accessed. For example:
{
"userId": "jsmith",
"applicationId": "1111111-111111-111111-11111111"
}
An API response is received after entering the request. For example:
{
"status": null,
"firstName": null,
"lastName": null,
"authenticationCompleted": false,
"machineAuthenticator": null,
"userMachineSettings": {
"machineAuthenticatorEnabled": false,
"deviceFingerprintRequired": false,
"attributeExclusions": [],
"userMachineAuthenticators": []
},
"kbaChallenge": null,
"token": "GC/qKOp/15eRQ8QnJ8DXA+RCtlXYxuAEyC5mF9WxT4byFl6EQYlPUUIaMMnbEq3+vQ3EGi4Mcp/sX3ttDdRzU6GMdjPHL21i9tNAw22fNE+ZsUtwoPzhCO6b5YRKQcJ9jJBADp+2o05oF/iQFaWeOnP6E1cW6zPAD4DYXwwbXe6pR46/XN6XDrR+C5JiCklwlY2Pf3L5fAG4Bl0QCEmEjeTpLCp7wbWsRv45RNgBE8O2MTLoRigzxMRen6+Hw94E2SD2EHvf4+IetJAsTFgfnx1YMabuHfrw5D0jlN0veaHmxp0yF0iitMkyNWPwoNEh+XltvVKYDas3Q9V16Xk5/rMKWgOYHp/Z/U8pf6heUgA6yeLo5dXIqC+TkSpibRpere/gBkVAskjePYs60BIpMiqiXAisKaIi4t3D50/X/6JXNvoinL60XHu+I97DrCQ20ozhn7aG1jHRNIGYFU+JDR9+qAOhmUQbZVQV9Ngqg7Av4jBDkBWAquA/E6zhZe4vDQo7WV0=",
"expires": 1521648764763,
"otpdeliveryType": null,
"time": 1521647864782
}
Complete authentication challenge (First-factor)
The next step is to complete the first-factor authentication challenge. For an example, a POST request to complete a Password authentication challenge would be sent to the following URL:
https://customer.region.trustedauth.com/api/web/v1/authentication/users/authenticate/PASSWORD_AND_SECONDFACTOR/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>
or
Authorization: <token>
The body of this request should contain a JSON object with the password response and the ID of the application being accessed. For example:
{
"applicationId": "1111111-111111-111111-11111111",
"response": "password"
}
The response received from this request would include a new token and a field authenticationCompleted 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
}
Select Authenticator (Second-factor)
The next step is to send a POST request to use a specific second-factor authentication. It must be sent to a URL with PASSWORD_AND_SECONDFACTOR at the end of it. For example:
https://customer.region.trustedauth.com/api/web/v2/authentication/users/authenticate/PASSWORD_AND_SECONDFACTOR
The body of this request should contain a JSON object with the ID of the application being accessed, the token that was received from the last request, and a second-factor authenticator. All the available second-factor authenticator options were received in the first call we made. For example:
{
"applicationId": "1111111-111111-111111-11111111",
"secondFactorAuthenticator": "OTP",
"authToken": "GO7mOyRuLzfTOXLk/IbzsDEuw8cFQspxz8TCWRwcrrhtoBw/o7udXt94eTkbkDFcbMVpfqHZJcJ4vavS4MEN6wp0d7MFhd0n9A9XymY5KHKyMvrqJlqh8+NrIZjkiA0sZvrAhu+6IRGfTYfoe/DwWclJi2JNNxpMX/17b7QHZdrj5ItbJUp3wHhAswUX02uWn/Fxwnt3cxGVHgmtTaVfz42JBkiIeRcOiv81iJqfTuSrd+S29RqO4PCKYGw1pKhymottvV3eVGNxdPvwSrLgXusfuCyfAB8tGl047WJQOKaHZ7k4GbzC1QKjldNWHrMAtiLUMWaxgvpU/vANJUibIPXJ6+1i7X7U6THJJg4fBG+pJo8jPKPI1B+XxE1mNBdLdMEdfUSKwUqv3BGg8g+WsL+ZLkbSzrswuoyBKWioEVXkxUVDtRghDLDjiRFjyQMwD+MhvdoC46a10IMkz1G5kKkQ6xaTTwhkEsh2iGeWtn6WDcC0PILFX4NmiF/g650j41aFWAyOD5ULBKV04a2dYKdadGfaAH0="
}
An API response is received after entering 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. It must be sent to a URL with PASSWORD_AND_SECONDFACTOR at the end of it. For example:
https://customer.region.trustedauth.com/api/web/v1/authentication/users/authenticate/PASSWORD_AND_SECONDFACTOR/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>
or
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",
"secondFactorAuthenticator": "OTP"
}
An API response is received after entering 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.