Connect to an external telephony service provider
To send a one-time passcode (OTP) to your end users through an SMS message or voice call, you need to connect an external telephony service provider using a telephony inline hook. This topic explains how to add and manage the telephony inline hook.
How it works
An inline hook allows you to perform outbound calls from Okta to your web service that's hosted on an external system. With the telephony inline hook, you can integrate your telephony service provider into enrollment, authentication, and recovery flows that involve the phone authenticator.
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 or 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.
Before you begin
Set up an external telephony provider of your choice with Okta using one of the following methods:
- Use Okta Workflows. See Configure Okta Workflows for an external telephony provider. Take note of the Invoke URL, Alias, and Client Token.
- Use the Okta API. See developer documentation: Telephony inline hook reference.
Add a telephony inline hook
-
In the Admin Console, go to .
- Click Add Inline Hook, and then select Telephony.
-
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.
- Click Save. This activates the telephony inline hook.
Test the telephony inline hook
- In Inline Hooks, find the Active telephony inline hook and click . The Preview tab of the inline hook opens.
- 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.
- In Preview example inline hook request, click Generate request. This generates the JSON request that Okta sends to your telephony provider.
- Optional. Click Edit to edit the generated request. For example, you can edit the user profile or the phone number before sending the request.
- 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.
- In the Admin Console, go to .
- Find the Active telephony inline hook and click .
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).
- In the Admin Console, go to .
- Find the active telephony inline hook and click .