Configure telephony providers through the Admin Console

Send a one-time passcode (OTP) to your users by connecting an external telephony provider in the Admin Console. This topic explains how to add and manage telephony service providers through the Admin Console.

How it works

You can configure one of or both Twilio or Telesign as telephony service providers. When they're configured through the Admin Console, Okta handles the communication between your org and your telephony provider. To customize your telephony providers, go to your telephony service provider and adjust different settings there.

If you have other methods of telephony that are active, such as using the telephony inline hook, you must deactivate those other methods before you can activate an external telephony provider.

You can configure up to two telephony service providers in the Admin Console and assign one as your primary provider and the other as your secondary provider. If your primary provider experiences an outage or service disruption, Okta automatically routes one-time passcodes (OTPs) to your secondary provider to ensure continuous authentication service.

Before you begin

Choose Twilio or Telesign as your telephony service provider. Then, create an account with them, and configure your telephony settings.

Gather the following details from your provider:

• Account string identifier (SID)

  For Telesign, the SID is your Customer ID.

• Authentication token

• A phone number that you own. Use the phone number to send SMS messages and for voice calls.

Add a telephony provider

1. In the Admin Console, go to Customizations > Telephony Providers.

2. Next to the provider you want to add, click Add.

3. Configure the following options, then click Save.

Status callbacks

When you use a custom telephony provider, Okta receives deliverability status updates from the provider and records them in the System Log. You can use these events to verify whether SMS messages and voice calls reach your users. See View or query SMS messages or voice call events.

Okta records the following events when it receives a deliverability status update from your custom telephony provider:

• system.sms.receive_status: Recorded when Okta receives a status update for an SMS message.
• system.voice.receive_status: Recorded when Okta receives a status update for a voice call.

Okta records a receive status event for real SMS and voice messages sent through your custom telephony provider (for example, MFA challenges, enrollment, account recovery, and unlock). Test messages and calls sent from the Send a test message or call feature don't generate a receive status event. If Okta can't verify a status callback (for example, because of a credential mismatch), it discards the callback without logging it. This is different from standard message delivery failures, which Okta always logs with a failed status.

Okta automatically injects the required callback URLs when it sends messages through the following provider services. You don't need to perform any manual configuration for these services:

• Twilio Programmable Messaging
• Twilio Voice
• Telesign Messaging
• Telesign Voice
• Telesign Verify

Configure Twilio Verify webhooks

If you use Twilio Verify for SMS, you must configure an event webhook in the Twilio console to send deliverability statuses back to Okta. See the Twilio Verify Events Webhook Onboarding Guide.

When configuring the webhook in Twilio, use the following Okta-specific settings.

• Webhook URL: Point the webhook to your Okta domain using this format: https://<your-okta-domain>/api/v1/internal/telephonystatus/customtwilio
• Event subscriptions: Select the following events:
  • com.twilio.accountsecurity.verify.message.delivered
  • com.twilio.accountsecurity.verify.message.undelivered
  • com.twilio.accountsecurity.verify.message.failed

Send a test message or call

1. In the Admin Console, go to Customizations > Telephony Providers.

2. Under the telephony provider you want to test, click Send test.

3. In Test using, select the telephony method you want to test.

4. In Country, select the country code for the phone number that you're using for the test.

5. In Telephone number, enter the phone number that you want to use for the test. If you're sending a voice test, you can enter the extension of the phone number that you're using, if applicable.

6. For SMS tests, click Send test via SMS. For Voice call tests, click Send test via voice call.

Activate a telephony provider

After you've configured your telephony provider, activate it to use it for telephony.

1. In the Admin Console, go to Customizations > Telephony Providers.

2. Next to the provider you want to activate, click Actions > Activate.

   Note:

   There are different ways to set up telephony with your telephony providers. Refer to your provider's documentation when selecting the different SMS and Voice options.

Deactivate a telephony provider

Review the following requirements and limitations before deactivating a provider:

• If you have two telephony providers configured, and both are active, you can only deactivate the secondary provider. You can't deactivate the Primary provider.
• You can't deactivate a telephony provider if the phone authenticator is active without an active telephony inline hook. To deactivate the provider, perform one of the following actions first:
  • Remove the phone authenticator.
  • Configure and activate a telephony inline hook.

1. In the Admin Console, go to Customizations > Telephony Providers.

2. Next to the provider you want to deactivate, click Actions > Deactivate.

Set the primary telephony provider

1. In the Admin Console, go to Customizations > Telephony Providers.

2. Next to the provider you want to set as the primary provider, click Actions > Set as primary.

Remove a telephony provider

Before removing a telephony provider, ensure that you're prepared. Set up a new telephony provider, configure a new telephony method, or plan to not use the phone authenticator for authentication. See Set up an external telephony provider for the different ways to set up telephony in your org.

If you're removing telephony completely as an option for authentication or recovery, ensure that you update your app sign-in policies.

If the telephony provider that you want to delete is active, you must deactivate it before you can delete it.

1. In the Admin Console, go to Customizations > Telephony Providers.

2. Next to the provider you want to delete, click Actions > Delete.

3. Review the checkbox warning and then check it.

4. Click Remove.

Edit a telephony provider

1. In the Admin Console, go to Customizations > Telephony Providers.

2. Next to the provider you want to edit, click Actions > Edit.

3. Make the necessary changes to the telephony provider settings.

4. Click Save.

Troubleshoot provider credentials

If receive status events don't appear in the System Log, your provider credentials might be failing validation.

• Telesign: If your account has multiple API keys, Telesign uses the one with the latest expiration date to authenticate callbacks. A key without an expiration date counts as the most recent key. If more than one key don't have an expiration date, Telesign selects the key unpredictably. Ensure that the key entered in Okta matches the active key in Telesign. Otherwise, Okta can't verify the callback, and delivery status events don't appear.

• Twilio: You must use the account SID and auth token. Don't use Twilio API Keys. Twilio always uses the account's primary auth token to authenticate callbacks, not an API Key and Secret pair.