Connect to an external telephony service provider

Connect to an external telephony provider to use the phone authenticator. When the end user requests a one-time passcode (OTP) through an SMS text message or a voice call, Okta uses this provider.

Okta uses the external web service to connect to the provider to make the request on the user's behalf. The telephony service provider delivers the OTP to the requester's device. The external web service responds to Okta with the OTP delivery status. If the telephony provider fails to deliver the OTP, Okta uses its fallback provider to send the OTP.

Your org can have only one active telephony inline hook at any given time. However, logic in the external web service can direct requests to different telephony providers based on the conditions you specify. For example, you might send the request to different telephony providers based on the country where the request originates. Or, your custom code might include error handling to send requests to a secondary telephony provider if your primary telephony provider fails to deliver messages.

Before you begin

Configure Okta Workflows for an external telephony provider. Take note of the Invoke URL, Alias, and Client Token.

Alternatively, you can use the Okta API. See developer documentation: Telephony inline hook reference.

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:

    • 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.
    • Authentication field: Enter the Alias.
    • 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.
    • Optional. Add Custom Headers.
  4. Click Save. This activates the telephony inline hook.

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