Custom TOTP factor (MFA)

The Custom TOTP factor lets you use a custom time-based one-time passcodes (TOTP) solution for user authentication.

Your users select the Custom TOTP factor when they sign in and provide the TOTP from their token to sign in to Okta or Okta-protected resources.

To set this factor up, you pass a factorProfileId and sharedSecret through the Okta Factors API for each token.

You can create unlimited instances of the Custom TOTP factor for different groups of personnel, but users may only enroll in one instance at a time.

Before you begin

  • Review the Okta Factors API documentation.
  • If Custom TOTP 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 your Custom TOTP factor.
  • Make a note of the HMAC and shared secret encoding algorithms that 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 SecurityMultifactor.
  2. On the Factor Types tab, click TOTP.
  3. Click Add TOTP Factor.
  4. Configure the following options. 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. If you select a time step of 15 seconds and a clock drift interval of 3, Okta accepts 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 appear.
  6. To copy the Factor Profile ID for enrolling users, click the clipboard icon. You 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

    • A user can enroll in only one Custom TOTP factor.
    • When enrolling users, make sure their factorID matches their assigned security token. If you use an incorrect factorID, 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 SecurityMultifactor.
  2. On the Factor 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 policy to groups.
    4. Set the TOTP option to Optional or Required.
    5. Click Create Policy.

    Edit a policy

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

End-user experience

  1. The user sees a prompt to authenticate with a factor when signing in to Okta or accessing an Okta-protected app, if required by sign-on policies.
  2. If the user is enrolled from the Okta Factors API, they see a prompt to enter the passcode that appears on their security token. If the end user wasn’t enrolled from the API, an error message appears.

Important considerations

  • Verify your configuration. Enroll and authenticate a few users with the TOTP token before enrolling additional users. This allows you to identify and fix potential issues without affecting more users. You can't edit a factor profile after creating it. If you configure a profile incorrectly, you 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 only enroll in one Custom TOTP factor.
  • This feature only supports standard OTP tokens. Proprietary implementations or non-standard tokens aren't supported.
  • You can't edit an OTP configuration after creating it. Select the correct settings before you click Add to save the configuration.