TOTP Authentication Method
Here is an example response from the server indicating that TOTP authentication is required as the next step:
HTTP/1.1 200 OK
Content-Type: application/json
{
"type": "totp",
"id": "e230e2e0-25ae-11e5-8dc9-0050b6c32ffc",
"allowDeferral": true
}Note that the value of the type property is totp.
When responding to the TOTP challenge a value for the otpCode property is required. This should contain the current value as displayed on the TOTP device. Additionally, if the response from the server contains a true value for the allowDeferral property, as above, the user may opt to defer being challenged for 30 days.
POST /idp/ws/rest/authn HTTP/1.1
Content-Type: application/json
Accept: application/json
{
"type": "totp",
"id": "e230e2e0-25ae-11e5-8dc9-0050b6c32ffc",
"otpCode": "123456",
"defer": true
}Deferral
If deferral is allowed and opted-into by the user, if the otpCode was valid then the next response from the server will contain a Set-Coolie header which should be handled automatically by the browser if cookies are enabled. The cookie contains information linking a particular user to a particular deferral.
Since the deferral is managed with a cookie, it is only good for a single browser on a single device. If a different browser or device is used in the future, the user will be challenged again and may opt-in to deferral for that device/browser combination.
Multiple users may have active deferrals on the same device & browser.
Setup
The first time a user is challenged for TOTP authentication they need to go through a setup phase where they register their TOTP key with a device. In this case, the server will respond with a setup object which will contain all of the information required.
Note
Displayed values have been truncated here for formatting purposes, but the strings listed here should represent actual, usable values when generated in a production environment.
HTTP/1.1 200 OK
Content-Type: application/json
{
"type": "totp",
"id": "e230e2e0-25ae-11e5-8dc9-0050b6c32ffc",
"setup": {
"setupInstructions": "You need to set this up now!",
"base64QrCode": "iVBORw0KGgoAAAANSUhEUgAAASwAAAEsAQAAAABRB[...]",
"secret": "KDXUAAZNFCYVUEVXPXPT3BHRX4S5KXFO",
"passwordRequired": false
},
"allowDeferral": true
}The setupInstructions property contains instructions which should be displayed to the user
The base64QrCode property contains a Base64-encoded PNG image of the QR code which should be displayed. Many TOTP devices allow registration by scanning a QR code.
The secret roperty contains the TOTP secret key which can be used to perform manual registration on a device
The passwordRequired property indicates whether or not a valid password is required to complete the setup process. This will be true if there have been no previous authentication steps which have validated the user is who they claim to be. In other words requiring a password for setup ensures that someone cannot setup TOTP authentication for someone else by simply supplying a valid username at the beginning of the process.
To To successfully complete the setup step a valid otpCode must be provided. This ensures that the user has successfully setup their TOTP device.
POST /idp/ws/rest/authn HTTP/1.1
Content-Type: application/json
Accept: application/json
{
"type": "totp",
"id": "e230e2e0-25ae-11e5-8dc9-0050b6c32ffc",
"otpCode": "123456",
"defer": true,
"password": "mysupersecretpassword"
}