Custom TOTP Factor
Custom TOTP factor flow
- Contact Okta Support to enable the TOTP factor for your org.
- Create a profile ID.
- Obtain the profile ID from the admin console.
- Include the custom TOTP factor as an optional or required factor as part of your factor enrollment policy.
Use the profile ID and hardware token secret to enroll a user in the factor using the factors API.
- Verify that authentication is successful for a single user before enrolling multiple users.
Before you begin
- Review the API documentation to enroll users in the TOTP factor.
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.
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.
- From the admin console, navigate to Security > Multifactor. The Multifactor settings page is displayed.
- Click TOTP to view settings for the custom TOTP factor.
- To add a new custom TOTP factor, click Add TOTP Factor. The Add TOTP Factor window is displayed.
- Fill out the following fields:
- 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)
- 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.
- Navigate to Factor Enrollment settings and add the Custom TOTP factor to your org's factor enrollment policy so that it appears to end users once they sign in to their org.
- 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
- 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.
Click Add TOTP Factor to save your settings. Once the TOTP factor is created, the factor profile ID will appear on the Multifactor page.
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.
- 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.