Custom TOTP Factor

This is an Early AccessEarly Access (EA) features are opt-in features that you can try out in your org by asking Okta Support to enable them. Additionally, the Features page in the Okta Admin Console (Settings > Features) allows Super Admins to enable and disable some EA features themselves. feature. To enable it, please contact Okta Support.

Custom TOTP Factor allows admins to enroll users in a custom TOTP factor by importing a seed into Okta and authenticating users with the imported hardware token. Successful factor enrollment requires passing a profile ID and shared secret for each token.

Custom TOTP factor flow

  1. Contact Okta Support to enable the TOTP factor for your orgThe Okta container that represents a real-world organization..
  2. Create a profile ID.
  3. Obtain the profile ID from the adminAn abbreviation of administrator. This is the individual(s) who have access to the Okta Administrator Dashboard. They control the provisioning and deprovisioning of end users, the assigning of apps, the resetting of passwords, and the overall end user experience. Only administrators have the Administration button on the upper right side of the My Applications page. console.
  4. Include the custom TOTP factor as an optional or required factor as part of your factor enrollment policy.
  5. Use the profile ID and hardware token secret to enroll a user in the factor using the factors API.

  6. Verify that authentication is successful for a single user before enrolling multiple users.

Before you begin


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

  • Ensure that one or more profiles have been created before TOTP factor enrollment.
  • Consider testing the TOTP hardware token in your own test environment first or work with Okta Support before using this feature to minimize any potential issues.

  • Important: Verify that authentication is successful for a single user

    It is critical to enroll and authenticate a single user with the TOTP hardware token first before other users are enrolled. This verification ensures that your configuration is correct since a factor profile cannot be edited once created. If a profile is not configured correctly, it will require re-enrollment of all users to a new custom TOTP profile.



  1. From the admin console, navigate to Security > Multifactor. The Multifactor settings page is displayed.
  2. Click TOTP to view settings for the custom TOTP factor.
  3. To add a new custom TOTP factor, click Add TOTP Factor. The Add TOTP Factor window is displayed.

  4. Fill out the following fields:
    • Name
    • TOTP Length (6,8,10)
    • HMAC Algorithm (HmacSHA1, HmacSHA256, HmacSHA512)
    • Time step (15, 30, 60 seconds)
    • Clock drift interval (3, 5, 10 seconds)
    • Shared secret encoding (Hexadecimal, Base 32, Base64)
  5. Click Add TOTP Factor to save your settings. Once the TOTP factor is created, the factor profile ID will appear on the Multifactor page.

  6. Click Copy to copy the Factor Profile ID to your clipboard. The factor profile ID is used to enroll a user in the TOTP factor using the factors API.

  7. Navigate to Factor Enrollment settings and add the Custom TOTP factor to your org's factor enrollment policy so that it appears to end usersEnd users are people in your org without administrative control. They can authenticate into apps from the icons on their My Applications home page, but they are provisioned, deprovisioned, assigned, and managed by admins. once they sign in to their org.

  8. Use the factor profile ID to enroll a user in the TOTP factor by referring to the API documentation Enroll Custom HOTP Factor.

    The API call should contain the following attributes and hardware token shared secret:

    • Profile ID
    • Factor Type
    • Provider
  9. Note: You must enroll a user with a factor profile ID that matches that of the user's assigned hardware token. If the correct profile ID is not used, an error will occur when the user attempts to authenticate.

  10. Verify that authentication is successful for a single user before enrolling all other users.

    Note: A misconfigured profile requires re-enrollment of all users to a new custom TOTP profile.

End-user experience

  • If the TOTP factor is set to Active and the end user is not yet enrolled in the factor, they will see the Set up authentication methods screen.

  • If an end user is enrolled in the TOTP factor by an admin, a factor verification screen appears instead.
  • If the user was not enrolled successfully from the APIs, they will receive the following error: Contact your administrator to continue enrollment.

  • If the user was enrolled successfully from the APIs, they will be prompted to enter a code to proceed with verification.