Configure the Custom OTP authenticator

The Custom OTP authenticator provides a one-time password (OTP) through a hardware or software security token as an additional factor of authentication for users who sign in to environments where multifactor authentication (MFA) is required.

In Okta, admins add the Custom OTP authenticator to the list of accepted authenticators and, optionally, customize the name of the authenticator. In addition, admins must pass the Authenticator ID and sharedSecret elements through the Okta Factors API for each token.

Then, end users are prompted to set up the authenticator by entering a code that the admin provides. After end users have set up the authenticator, each time they sign in, they will be prompted to enter the time-based code they see in their OTP app or on their token to prove their identity.

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 end users to different instances of the authenticator for greater control and security.

This authenticator only supports standard OTP tokens. Proprietary implementations or non-standard tokens are not supported.

Before you begin

Add Custom OTP as an authenticator

Enroll end users

Apply a multifactor policy to a 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 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’re going to 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 Security > Authenticators.
  2. On the Setup tab, click Add Authenticator.
  3. Click Add for Custom OTP.
  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. To calculate the interval (in seconds) during which users will be 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, which 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.

You can’t edit an OTP configuration after you’ve created it. Verify your selections before you proceed to the next step.

  1. 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.
  2. Obtain the Authenticator ID:
    1. Click Actions.
    2. Click Authenticator ID & Info.
    3. Click the clipboard icon to copy the Authenticator ID. You will 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; ensure that no user appears in multiple instances.

Okta recommends that you verify your configuration works by testing it on a small number of 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.

You can’t edit a Custom OTP authenticator profile after it has been created. If you discover configuration errors in a Custom OTP authenticator profile, you can re-enroll all affected users in a new Custom OTP authenticator profile. You may delete a Custom OTP authenticator profile after you have removed all users from it.

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

Verify that the correct userId is assigned to each factorID and that they are assigned to the correct security token. If these values don’t correspond to the correct end user, an error occurs when the end user attempts to authenticate.

Apply a multifactor policy to a Custom OTP authenticator

  1. In the Admin Console, go to Security > Authenticators.
  2. On the Enrollment tab, add a new or edit an existing multifactor policy.

Add a policy

  1. Click Add Multifactor Policy.
  2. Enter a name.
  3. Assign the multifactor policy to groups.
  4. 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.
  5. Click Create Policy.
  6. To add rules to the policy, see Configure an authentication enrollment policy rule.

Edit a policy

  1. Select the policy you want to edit and click Edit.
  2. 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.
  3. Click Update Policy.
  4. To add rules to the policy, see Configure an authentication 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.

To protect your sensitive corporate resources from unauthorized access, 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. If unsuccessful authentications exceed the rate limit, authentication isn't allowed until the rate limit period has elapsed. Okta returns HTTP status code 429, indicating "too many requests". A message appears on the user interface and an entry is written to the System Log.