Configure the Custom OTP authenticator

The Custom OTP authenticator provides a one-time password (OTP) through a hardware or software security token.

To use this authenticator, admins add the Custom OTP authenticator to Okta. Then they must pass the Authenticator ID and sharedSecret elements through the Okta Factors API for each token.

When users sign in to Okta after the authenticator has been activated, they're prompted to enter a code that the admin provides to them. After that, users provide the code they see in their OTP app or on their token to verify their identity when they sign in.

You can add as many Custom OTP authenticator instances as you require and each instance has its own configuration. This lets you assign groups of users to different instances of the authenticator for greater control and security.

Before you begin

Add Custom OTP as an authenticator

Enroll end users

Configure the Custom OTP authenticator

End-user experience

Related topics

Before you begin

• Review the Okta Factors API documentation and the instructions for enrolling end users in the Custom HOTP factor.
• If the Custom OTP authenticator isn't already enabled for your org, contact Okta Support to enable it.
• Generate unique shared secrets for each user that you want to enroll in the Custom OTP authenticator.
• Provide end users with a hardware or software security token programmed with a unique shared secret.
• If you use an HMAC algorithm or shared secret encoding in your OTP implementation, have this information ready before you begin the procedure.

Add Custom OTP as an authenticator

1. In the Admin Console, go to SecurityAuthenticators.

2. On the Setup tab, click Add Authenticator.
3. Click Add on the Custom OTP tile.
4. Configure the following settings:

   • Authenticator name

   • OTP length

   • HMAC Algorithm. Select the algorithm that matches your implementation.

   • Time step. See Clock drift interval.

   • Clock drift interval. This setting allows you to build in tolerance for any difference between the token's current time and the server's current time. This value is measured in seconds. To calculate the interval during which users are allowed to enter their code, multiply the Time step value by the Clock drift interval value. For example, with a Time step value of 60 seconds and a Clock drift interval value of 5, the result of 60 X 5 is 300. This means that Okta will accept passcodes within 300 seconds before or after the end user enters their code.

   • Shared secret encoding. Select the algorithm that matches your implementation.

5. Click Add. Okta generates the Authenticator ID, which will be is used to enroll a user in the Custom OTP authenticator using the Okta Factors API.
6. Obtain the Authenticator ID:
   1. Click Actions.
   2. Click Authenticator ID & Info.
   3. Click the clipboard icon to copy the Authenticator ID. You'll enter this ID as the factorProfileId when you enroll users in the Okta Factors API.

Enroll end users

Use the Enroll Custom HOTP Factor functionality in the Okta Factors API to enroll users.

A user can be enrolled in only one Custom OTP authenticator instance at a time. Ensure that no user appears in multiple instances.

Okta recommends that you verify your configuration works by testing it on a few users before enrolling all other users. This allows you to limit the effect of configuration errors to only a few users and then correct them before enrolling the rest of your users.

Verify that you have the following information for each user for making the API call:

• Factor type: token:hotp
• Provider: CUSTOM
• Profile ID (the Authenticator ID obtained during the setup procedure)
• Shared secret

Add a multifactor policy to a Custom OTP authenticator

1. In the Admin Console, go to Security > Authenticators.
2. On the Enrollment tab, click Add a policy.
3. Enter a name and description for this policy.
4. Assign the multifactor policy to groups.
5. Select the Optional or Required option for the Custom OTP authenticator instance. If you customized the name of the instance, find the customized name instead of Custom OTP.
6. Click Create Policy.
7. To add rules to the policy, see Configure an authenticator enrollment policy rule.

Edit a multifactor policy to a Custom OTP authenticator

1. In the Admin Console, go to Security > Authenticators.
2. On the Enrollment tab, select the policy that you want to edit and click Edit.
3. In Effective factors, select the Optional or Required option for the Custom OTP authenticator instance. If you customized the name of the instance, find the customized name instead of Custom OTP.
4. Click Update Policy.
5. To add rules to the policy, see Configure an authenticator enrollment policy rule.

End-user experience

1. According to the Global Session Policies, the user is prompted to confirm their identity with an authenticator when signing in to Okta or accessing an Okta-protected app.
2. The user selects the Custom OTP authenticator (or the customized name of the authenticator instance).

• If the user was enrolled successfully from the Okta Factors API, they’re prompted to enter the passcode that appears on their security token.
• If the end user wasn’t enrolled successfully from the API, they receive an error directing them to contact their administrator.