Configure the custom OTP authenticator

The custom OTP authenticator allows users to authenticate with a one-time passcode (OTP) that they receive through a hardware or software security token. This authenticator supports standard OTP tokens only. You can create as many custom OTP authenticator instances as you need and assign them to different groups of users for granular control and security.

This authenticator is a possession factor, fulfills the requirements for user presence, and is device-bound. See Multifactor authentication.

Before you begin

If you use an HMAC algorithm or shared secret encoding in your OTP implementation, have this information ready before you begin the procedure.

Add the custom OTP authenticator

1. In the Admin Console, go to SecurityAuthenticators.

2. On the Setup tab, click Add Authenticator.

3. Click Add on the authenticator tile.

Configuration options

1. Configure the following options:

   Field	Value
   Authenticator name	Enter a descriptive name for this authenticator.
   OTP length	Enter the number of digits each one-time passcode should be.
   HMAC algorithm	Select the algorithm that matches your implementation.
   Time step	Enter the interval, in seconds, for synchronization comparisons. This value is used with the Clock drift interval value to calculate the window during which Okta accepts passcodes.
   Clock drift interval	Enter the difference between the token's current time and the server's current time, in seconds, that Okta will tolerate for passcode entry. To calculate the window during which users are allowed to enter their passcode, multiply the Time step value by the Clock drift interval value. For example, a Time step value of 60 seconds and a Clock drift interval value of five seconds results in 300 seconds (60 X 5). This means that Okta will accept passcodes within 300 seconds, or five minutes, before or after the passcode entry timestamp.
   Shared secret encoding	Select the algorithm that matches your implementation.

2. Click Add. Okta generates the authenticator ID, which is used to enroll a user in the custom OTP authenticator using the Okta Factors API.
3. Obtain the authenticator ID:
   1. Click Actions.
   2. Click Authenticator ID & Info.
   3. Click the clipboard icon to copy the authenticator ID. You enter this ID as the factorProfileId when you enroll users in the Okta Factors API.
   4. Share the authenticator ID with your users in a secure manner. They need to enter this ID in the Sign-In Widget when Okta asks them to enroll in the custom OTP authenticator.

Enroll end users

You can enroll a user in only one custom OTP authenticator instance at a time. Ensure that no user appears in multiple instances. See Enroll Custom TOTP Factor.

Add the custom OTP authenticator to the authenticator enrollment policy

1. In the Admin Console, go to SecurityAuthenticators.

2. Click the Enrollment tab.
3. Add the authenticator to a new or an existing authenticator enrollment policy. See Create an authenticator enrollment policy.

Edit or delete the custom OTP authenticator

You can’t edit an OTP authenticator. If you discover configuration errors in a custom OTP authenticator instance, you can re-enroll all affected users in a new custom OTP authenticator instance.

You can delete a custom OTP authenticator instance only after you've removed all users from it. Before you delete the authenticator, you may have to update existing policies that use this authenticator.

1. In Authenticators, go to the Setup tab.
2. Open the Actions dropdown menu beside the authenticator, and then select Delete.

End-user experience

When users sign in to Okta for the first time after the custom OTP authenticator has been added, the Sign-In Widget prompts them to enroll in the custom OTP authenticator. The user must provide the authenticator ID that their admin generates for them.

When users sign in to Okta after they’ve enrolled in the custom OTP authenticator, they select this authenticator (or the customized name of the authenticator instance) from the Sign-In Widget. An OTP appears in the user’s OTP app or security token. The user enters that OTP into the Sign-In Widget.

Okta enforces a rate limit on unsuccessful authentication attempts from your Okta-enrolled third-party OTP authenticators. A cumulative limit of five unsuccessful authentication attempts is enforced over a rolling five-minute period. Authentication attempts aren’t allowed until that period has elapsed. Okta displays a “too many requests” error to users and records an entry in the System Log.

Related topics

Create an authenticator enrollment policy

Configure an authenticator enrollment policy rule

Enroll Custom TOTP Factor