Phone authenticator

Learn about using the phone authenticator in Okta.

Factor type Possession
Method characteristics

User presence
Description The SMS and voice call authenticators require the use of a phone. They send a code in a text message or voice call that the user enters when prompted by Okta.

The phone authenticator allows users to authenticate themselves using a one-time passcode (OTP) that is delivered to their phone either as an SMS message or as a voice call. It also allows users to enroll their devices and initiate account recovery.

Before you begin

  • Review Telephony to understand the impact of regulatory requirements, toll fraud, technical considerations, and other factors.
  • If you’re configuring the phone authenticator for the first time for your org, you must first set up an external telephony service provider. See Choose telephony provider.
  • The token lifetime of the OTP sent to the phone authenticator (voice or SMS methods) is five minutes.

Start this procedure

Set up the phone authenticator by first adding a telephony inline hook, testing it, and then adding the phone authenticator.

Add a telephony inline hook

After you configure your external telephony service, connect it with Okta by adding a telephony inline hook:

  1. In the Admin Console, go to Workflow > Inline Hooks.
  2. Click Add Inline Hook, and then select Telephony.
  3. Type a descriptive name for the telephony provider inline hook.
  4. Add the external service URL, including the endpoint that sends the one-time passcode (OTP) to end-user devices.
  5. Optional. Specify a value for the Authentication field header field.

  6. Optional. Specify a value for the Authentication secret header field.

    The external service should use the authentication secret to validate that the request is an Okta request for service.

  7. Click Save to make the inline hook active.

Test the telephony inline hook

After you configure the telephony hook for your service provider, you can test its operation using the Preview action.

To test your connection to the telephony service provider:

  1. In the Admin Console, go to Workflow > Inline Hooks.

  2. Identify the Active telephony inline hook.

  3. Click Actions, and then select Preview.

  4. Select a user profile for a user with a phone as a valid authenticator.

  5. Select the event that results in an SMS text message or voice call you want to test.

    For example, select one of the following event actions:

    • MFA enrollment

    • MFA verification

    • Account unlock

    • Password reset

  6. Click Generate request to generate the HTTP request to send to your telephony provider.

    Optionally, you can edit the generated request by clicking Edit. For example, you might want to edit the profile to send a text message to a phone number that you use for testing purposes.

  7. Click View response to view the response from your service provider.

Add phone as an authenticator

After you configure and test the telephony inline hook, use it to configure the phone authenticator:

  1. In the Admin Console, go to Security > Authenticators.
  2. On the Setup tab, click Add Authenticator.
  3. Click Add on the Phone tile. The Add Phone window pops up.
  4. In the User can verify with section, select the methods that users can verify with. You can select Voice call,SMS, or both.
  5. In the This authenticator can be used for section, select the actions you want to use the phone authenticator for:
    • Authentication and recovery: This option allows users to use this authenticator to authenticate themselves and recover their account
    • Recovery: This option allows users to use this authenticator only for recovering their account. If you choose this option, Okta doesn't request authentication during the evaluation of your Global Session Policy.

  6. Click Add.

End-user experience

When users sign in to Okta for the first time, they see that extra verification is required. They select the phone authenticator, enter a phone number, and choose SMS or Voice call, depending on the options you've made available to them. After they verify the phone number, they can use it for authentication and recovery or recovery only, depending on how you've set up the authenticator.

If the user selects SMS, they may only provide a mobile phone number. For Voice call, they may provide a mobile phone number or a phone number with an extension.

Toll-free, premium, or invalid phone numbers can't be used for multifactor authentication or device enrollment. Such phone numbers are rejected.

Too many attempts

Okta uses rate limiting to protect against brute-force attacks on SMS authenticators. After entering incorrect credentials for multiple times, users see the message - Too many attempts. Try again later. In this case, they should use a different authenticator to gain access to their account. Set up multiple authenticators for your users to ensure that they have alternatives.

Change in phone number

If the user changes their phone number but doesn't update it in Okta, the voice calls and SMS go to the user's old phone number. In this case, they can't complete verification. They should click Sign in with something else on the Sign-In Widget, and verify with a different authenticator. Next, they should add another phone numbers in the End-User Dashboard, and replace their old phone number with the new one.

End-user tasks

End users perform these tasks to enroll their phone, use it for signing in, and add another phone number to their account.

Set up the phone authenticator for the first time

  1. In the Sign-In Widget > Set up security methods > Phone, Click Set up.
  2. Select SMS or Voice call. If you select SMS, you may only provide a mobile phone number.
  3. Select your phone number's country from the Country dropdown.
  4. Type your phone number in the Phone number field. Don't include the country code, leave out any dashes, and leave out the leading zero if your country's phone system uses them.
  5. If you selected Voice call and your phone number includes an extension number, type it in the Extension field.
  6. Click Receive a code via SMS or Receive a code via voice call. You receive a code either by SMS or voice call, depending on which option you select.
  7. Type the code in the Enter Code field.
  8. Click Verify.

Use your phone to sign in

  1. Go to your org's sign-in page. Provide your username and any other credentials requested by the Sign-In Widget, such as a password.
  2. On the page that lists the available security methods, click Select beside the Phone option.
  3. To receive a code in an SMS message, click Receive a code via SMS. To receive a code in a voice call, click Receive a voice call instead.
  4. Okta sends an SMS message, or calls the user's phone, and the Sign-In Widget displays the Enter Code field.
  5. Type the code provided in the SMS message or voice call in the Enter Code field.
  6. Click Verify.

Add another phone number

After signing in, users can add another phone numbers to their profile.

  1. In the End-User Dashboard, click your username in the upper-right corner.
  2. Select My settings.
  3. In the Security Methods section, click Set up another beside Phone.
  4. Click Set up.
  5. Select SMS or Voice call. If you select SMS, you may only provide a mobile phone number.
  6. Select the country that your phone number is from in the Country dropdown list.
  7. Type your phone number in the Phone number field. Don't include the country code, leave out any dashes, and leave out the leading zero if your country's phone system uses them.
  8. If you selected Voice call and your phone number includes an extension number, type it in the Extension field.
  9. Click Receive a code via SMS or Receive a code via voice call. You receive a code either by SMS or voice call, depending on which option you select.
  10. Type the code in the Enter Code field.
  11. Click Verify.

The new phone number is added. Next time you're signing in, you can choose the phone number you want to use to complete the prompt.

Next steps