Connect to an external telephony service provider

Send a one-time passcode (OTP) to your users by connecting an external telephony provider using a telephony inline hook. This topic explains how to add and manage the telephony inline hook.

How it works

With a telephony inline hook you can perform outbound calls from Okta to your web service that's hosted on an external system. You can integrate your telephony service provider into enrollment, authentication, and recovery flows that involve the phone authenticator including SMS or voice call.

You can configure conditional logic in the external web service to direct requests to different telephony providers. For example, you can direct a request based on the originating country. You can also include error handling to direct it to a secondary telephony provider if the primary provider fails.

When a user requests an OTP, Okta uses the telephony inline hook to forward this request to your external web service. The service then requests your telephony provider for the message delivery. The telephony provider processes this request and sends the OTP to the user's device. It also sends the OTP delivery status to Okta as a response. This response gets registered in the System Log.

If the telephony provider fails to deliver the OTP, Okta uses its fallback provider to send the OTP. However, this fallback mechanism is heavily rate limited.

Use a robust authenticator instead

Using phone OTP isn't a guaranteed way to verify a user's identity. See Potential risks of verifying identity through SMS and voice call.

Okta recommends that you require users to authenticate using a more robust authenticator. For example, an authenticator that not only verifies the user presence but is also device-bound, hardware-protected, or phishing-resistant. Such authenticators include authenticator apps, email magic links, or FIDO2 (WebAuthn). See Multifactor authentication.

Before you begin

Set up an external telephony provider of your choice with Okta using one of the following methods:

Add a telephony inline hook

  1. In the Admin Console, go to WorkflowInline Hooks.

  2. Click Add Inline Hook, and then select Telephony.

  3. Configure the following options, then click Save.

    Field

    Description
    Name Enter a descriptive name for the inline hook.
    URL Enter the Invoke URL. This is the URL for the telephony provider, including the endpoint that sends the OTP to end-user devices.
    Enforce Okta service protection rate limits

    Okta by default enforces rate limits for the telephony inline hook. This protects you from toll-fraud attacks that could incur undesired charges to your telephony provider account. See Prevent or mitigate telephony-based fraud.

    You can opt out of this rate-limit protection. However, this may incur significant charges to your account if there is a toll-fraud attack. Okta isn't responsible for such charges. Okta recommends keeping this protection enabled.
    Authentication field

    Enter authentication for Header-based authentication.

    If you're using Okta Workflows then enter the alias you set up in Configure Okta Workflows for an external telephony provider.
    Authentication secret Enter the Client Token. The external service should use the authentication secret to validate that the request is an Okta request for service.
    Custom Headers Optional. Add custom header fields and values.

Test the telephony inline hook

  1. In Inline Hooks, find the Active telephony inline hook and click Actions Preview. The Preview tab of the inline hook opens.
  2. In the tab, go to Configure inline hook request and enter a user's information for testing:
    • data.userProfile: Enter the name of a user who has the phone as a valid authenticator.
    • requestType: From the dropdown menu, select one of the following events to send the SMS text or voice call to the user: MFA enrollment, MFA verification, account unlock, or password reset.
  3. In Preview example inline hook request, click Generate request. This generates the JSON request that Okta sends to your telephony provider.
  4. Optional. Click Edit to edit the generated request. For example, you can edit the user profile or the phone number before sending the request.
  5. In View service's response, click View response. This displays the response from your service provider.

OTP isn't generated if the telephony provider fails during the test.

View metrics for the telephony inline hook

Okta provides basic metrics to help you monitor the performance of your telephony service provider. The metrics track the total number of times a hook is executed in the last 30 days, the numbers of successful and unsuccessful executions, and the average execution time for successful executions.

  1. In the Admin Console, go to WorkflowInline Hooks.
  2. Find the Active telephony inline hook and click Actions Metrics.

Deactivate a telephony provider

You can only have one active telephony service provider for an org. However, you can configure multiple inline hooks for different telephony providers and switch between them (for example, if the current provider experiences service issues).

  1. In the Admin Console, go to WorkflowInline Hooks.
  2. Find the active telephony inline hook and click Actions Deactivate.

Next step

Configure the phone authenticator