Custom TOTP Factor

You can add a Time-based One-Time Password (TOTP) factor as a multifactor authentication (MFA) option in Okta. After you configure Custom TOTP and associated policies in Okta, end users are prompted to set it up by entering a code that you provide. After setup, end users can prove their identity when signing in to Okta or accessing Okta-protected resources by selecting your Custom TOTP. Successful factor enrollment requires passing a factorProfileId and sharedSecret through the Okta Factors API for each token.

You can add any number of Custom TOTP factor instances in Okta for use with your multifactor authentication (MFA) strategy. Each factor instance corresponds to a particular configuration of a given Custom TOTP factor. End users can be enrolled in only one Custom OTP authenticator instance, even if multiple exist.

Before you begin

  • Review the Okta Factors API documentation.
  • If Custom TOTP is not already enabled for your org, contact Okta Support to enable it.
  • Generate unique shared secrets for each user you want to enroll in your Custom TOTP factor.
  • Make a note of the HMAC and shared secret encoding algorithms you use in your implementation.
  • Provide end users with a hardware or software security token programmed with a unique shared secret.

Add Custom TOTP as a factor

  1. In the Admin Console, go to Security > Multifactor.
  2. On the Factor Types tab, click TOTP.
  3. Click Add TOTP Factor.
  4. Configure the following, making sure to select the HMAC and shared secret encoding algorithms that match your implementation:
    • Name
    • TOTP 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 drift between the token's current time and the server's current time. For example, if you select a time step of 15 seconds and a clock drift interval of 3, Okta will accept passcodes 15 X 3 = 45 seconds before or after a user enters their passcode.
    • Shared secret encoding. Select the algorithm that matches your implementation.

  5. Click Save. The factor and associated Factor Profile ID are displayed.
  6. To copy the Factor Profile ID for enrolling users, click the clipboard icon. You'll enter this ID when you enroll users in the Okta Factors API.
  7. Enroll users in the Okta Factors API. Make sure you have the following information for making the API call:
    • Factor type
    • Provider
    • Factor Profile ID
    • Shared secret
    Note

    Notes:

    • A user can be enrolled in only one Custom TOTP factor.
    • When enrolling users, make sure their factorID matches their assigned security token. If an incorrect factorID is used, an error occurs when the user attempts to authenticate.
    • Verify that authentication is successful for a single user before enrolling multiple users

Enroll Custom TOTP in an Okta multifactor policy

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

    If adding a policy:

    1. Click Add Multifactor Policy.
    2. Enter a name.
    3. Assign to groups.
    4. Set TOTP to Optional or Required.
    5. Click Create Policy.

    If editing a policy:

    1. Select the policy you want to edit, and then click Edit.
    2. In Effective factors, set TOTP to Optional or Required.
    3. Click Update Policy.
  1. To add one or more rules to the policy, see Configure an MFA enrollment policy rule.

End-user experience

  1. If required by sign-on policies, the end user is prompted to verify their identity with a factor when signing in to Okta or accessing an Okta-protected app.

  2. If the end user selects your Custom TOTP factor and they were 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 successfully enrolled from the API, an error displays directing them to contact their administrator.

Important considerations

  • It’s important that you verify your configuration by first enrolling and authenticating a few users with the TOTP token before enrolling additional users. This will allow you to identify and fix potential issues without affecting a larger number of users. A factor profile can’t be edited once created. If you configure a profile incorrectly, you’ll need to re-enroll all affected users to a new custom TOTP profile.

  • While you can add an unlimited number of Custom TOTP factors through the Admin Console, users can be enrolled in only one Custom TOTP factor.

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

  • An OTP configuration can’t be edited once it’s created. Make sure to select the correct settings before you click Add to save the configuration.