MFA: Use codes from an authenticator app using OATH
The OATH nodes support HMAC one-time password (HOTP) and time-based one-time password (TOTP) authentication as defined in the OATH standard protocols for HOTP (RFC 4226) and TOTP (RFC 6238). Both HOTP and TOTP authentication require an OATH-compliant device that can provide the password.
About OTPs
HOTP authentication generates a one-time password (OTP) every time the end user requests a new password on their device. The device tracks the number of times the user requests a new OTP with a counter. The OTP displays for a period of time you specify in the node configuration, so the user might be further in the counter on their device than on their account.
Advanced Identity Cloud resynchronizes the counter when the user finally logs in. To accommodate this, you set the number of passwords a user can generate before their device can’t be resynchronized. For example, if you set the HOTP Window Size to 50 and the user presses the button 30 times on their device to generate a new password, the counter in Advanced Identity Cloud reviews the passwords until it reaches the OTP entered by the user. If the user presses the button 51 times, you’ll need to reset the counter in the user profile to match the number on the device’s counter before the user can log in to Advanced Identity Cloud. HOTP authentication doesn’t check earlier passwords. If the user attempts to reset the counter on their device, they won’t be able to log in until you reset the counter in Advanced Identity Cloud to match their device. Find more information in Reset registered devices using REST.
TOTP authentication constantly generates a new OTP based on a time interval you specify. The device tracks the last several passwords generated and the current password. The TOTP Time Steps setting configures the number of passwords tracked. The Last Login Time setting monitors the time when a user logs in to make sure that user is not logged in several times within the present time period. The TOTP Time-Step Interval should not be so long as to lock users out, with a recommended time of 30 seconds.
Create a journey for OTP authentication
The following example journey uses TOTP, the default:
-
In the Advanced Identity Cloud admin console, start a custom OATH journey.
Learn more in Custom journeys.
-
In the Advanced Identity Cloud admin console, add the following nodes to your journey:
-
On the first OATH Token Verifier node, select Allow recovery codes.
-
On the OATH Registration node, select Generate Recovery Codes.
The value for OATH Algorithm must be the same for the registration and verification nodes.
-
Connect the nodes as shown:
-
Save your changes.
This journey demonstrates OATH authentication. In a production environment, you could include additional nodes, such as:
- Get Authenticator App node
-
Displays links to an authenticator app for Android and iOS.
- MFA Registration Options node
-
Provides options for users to register a multi-factor authentication device, get the authenticator app, or skip the registration process.
- Opt-out Multi-Factor Authentication node
-
Sets an attribute in the user’s profile which lets them skip multi-factor authentication.
Authenticate using an OTP
After creating the journey, test it as follows:
-
Register a test user account unless you have already done so.
-
Copy and paste the Preview URL into a browser in incognito mode.
A login screen prompts for your credentials.
-
Sign in with the username and password of the test user.
A registration screen prompts to display a QR code.
-
Register an authenticator app by scanning the QR code.
The journey registers your OTP app and displays recovery codes.
-
Save the recovery codes and click Done to proceed to OTP authentication.
-
Enter the OTP from your app, and click Submit:
If the animated timer indicates the OTP is close to expiry, wait for the app to generate a new one.
The UI displays the user profile page.
-
Browse to Edit Your Profile > 2-Step Verification > Change.
The UI displays your registered devices.
The OTP app you registered is named
OATH Device
.