Okta telephony - Write your own code for your Telesign inline hook

📘

NOTE:

To add this product to your account, contact us. This product is available for full-service accounts only.

Telesign offers the ability to code your own integration using our full-service APIs to deploy your own code to help you "bring-your-own-platform" to Okta, replacing Okta's previous internal platform for SMS and voice telephony. This process allows you to build a telephony inline hook for your Okta account, enabling delivery of one-time passcodes (OTPs) via SMS and voice. If you are new to Telesign and have not yet signed up for an account, contact us. Telesign offers easy migration and scalability for existing Okta customers choosing a new telephony service provider to enable channels to send OTPs.

📘

NOTE:

Telesign also offers a no-code solution, Okta Telephony - Telesign no-code inline hook, which provides a user-friendly integration. The no-code option simplifies integration without sacrificing functionality. It is ideal for most users and scenarios.

Understand Okta telephony service changes

In August of 2023, Okta stopped offering out-of-the-box telephony services for new customers. Effective September 15, 2024, at time of renewal, all Okta customers must bring-their-own telephony provider via Okta’s telephony inline hook to continue to send SMS and voice messages for both multi-factor authentication (MFA) and non-MFA use cases (e.g. authentication, account unlock, and password reset).

Before their first post-September 15, 2024 renewal, Okta customers currently using SMS or voice provided by Okta must implement a bring-your-own telephony provider, such as Telesign, using your Okta telephony inline hook.

Telesign Okta telephony inline hook solution

The Okta telephony inline hook allows you to integrate your own custom code into Okta flows that send SMS or voice call messages. You can integrate this inline hook with Okta's enrollment, authentication, and recovery flows that involve phone authenticators. Okta uses an external provider, such as Telesign, to deliver the OTP to your end user. Status commands indicate if the delivery was successful. The Telesign Okta telephony inline hook solution offers:

• Delivery of verification messages over SMS or Voice to end users.
• Synchronous response to Okta (success/error).
• Status callbacks and Get status for getting more insights of the delivery status of your transaction (Optional).

See the Basic usage to understand how to use the Telesign Okta telephony inline hook solution.

Configure your Telesign account

When you contact us, request that our Customer Support team enable the following Telesign products in your account:

Messaging - Enabled.

• Callback status - Enabled (Optional).
• Get status - Enabled (Optional).

SMS - Enabled.

• Sender ID - Purchased from Telesign and enabled.

Voice - Enabled.

• Voice caller ID - Purchased from Telesign and enabled.

📘

NOTE:

A Sender ID, a dedicated phone number purchased from Telesign, is required for SMS. This article has details on how to get a dedicated phone number. Similarly, customers interested in using voice will need to purchase a dedicated phone number from Telesign to use as a Voice Caller ID. Contact our Customer Support Team for assistance.

Before you write your own code

To write your own code for your Telesign Okta telephony inline hook, you will need:

• PaaS: An on-premise platform or a platform as a service (PaaS) provider such as AWS, Azure, Google Cloud Platform, Heroku, or Netlify. This example uses Netlify as the PaaS account. If you wish to follow our example, use this page to create a Netlify account if you do not already have one.
• Git repository provider: A Git repository provider such as Bitbucket or GitHub. This procedure uses GitHub as the source code repository service. Create a GitHub account if you do not already have one.
• Programing language: A programming language of choice. Telesign provides JavaScript, Python, Java, and other SDKs. This procedure uses JavaScript to develop the inline hook.

📘

NOTE:

This page is an example of how to write your own code to implement a Telesign Okta telephony inline hook solution if you elect not to use our Telesign no-code inline hook solution. Please modify accordingly if your developer environment differs from these details or you have different integration requirements. This example uses the following:

• MacOS
• NodeJS version 22.2.0

Write your code

Map Okta's request to Telesign Messaging

Messaging provides a complete solution to Okta’s Bring Your Own Telephony Required for SMS and Voice requirement. Consult the following tables on how to map Okta’s request object to Messaging.

Use this table when the data.messageProfile.deliveryChannel property of an Okta request is "SMS".

Use this table when the data.messageProfile.deliveryChannelproperty of an Okta request is "voice call”.

Integrate with Netlify

Once you have the code to map Okta’s request to Messaging, you need to integrate your code with a serverless provider. In our example, we use Netlify. This JavaScript code illustrates how you can integrate with Netlify.

import { messagingApiHandler } from '../../src/messaging-api.js';
import { OktaRequest, OktaResponse, OktaError } from '../../src/okta-types.js';
const telesignHost = 'rest-ww.telesign.com';
/**
 * Handles incoming requests to the Netlify function and interacts with the Telesign API.
 *
 * @param {Request} req - The incoming HTTP request.
 * @param {object} _context - A Netlify Context object. See https://docs.netlify.com/functions/api/
 * @return {Promise<Response>} - A promise that resolves to an HTTP response.
 */
export default async (req, _context) => {
    // Set the response content type
    const responseHeaders = { 'Content-Type': 'application/json' };
    // Validate the request contents
    /** @type {Object} */
    let bodyObject = null;
    try {
        bodyObject = await req.json();
    } catch (error) {
        const oktaResp = {"error":{"errorSummary":"Not a valid Okta request"}}
        return new Response(JSON.stringify(oktaResp), { status: 200, headers: responseHeaders });
    }

    // NOTE: this is an example of a pass-through of API credentials. Please follow your company's
    // security protocols regarding API credentials.
    const authorizationHeader = req.headers.get('authorization');
    if (!authorizationHeader) {
        const oktaResp = new OktaResponse({
            error: new OktaError('Missing header: authorization'),
        });
        return new Response(JSON.stringify(oktaResp), { status: 200, headers: responseHeaders });
    }

    // Integrate with Telesign Messaging
    const oktaReq = new OktaRequest(bodyObject);
    const oktaResp = await messagingApiHandler({
        oktaReq: oktaReq,
        host: telesignHost,    
    });
    return new Response(JSON.stringify(oktaResp), { status: 200, headers: responseHeaders });
};

Set up a Netlify Account

This guide uses Netlify as the PaaS service provider and GitHub for the source code repository to deploy the inline hook code.

Sign up for a Netlify account

If you do not have a Netlify account, go to https://app.netlify.com/signup to sign up for an account.

Connect your GitHub repository to Netlify

1. Open your Netlify dashboard.
2. Navigate to Sites.
3. Select Import an existing project from the Add your site to Netlify section of the dashboard.
4. Select GitHub as your source code provider on the next screen.
5. Netlify will redirect you to GitHub's OAuth login flow. Select Authorize Netlify to authenticate with GitHub.
6. Select Install Netlify to grant Netlify access to your GitHub repository. When prompted on which repositories to allow Netlify access, we recommend you choose Only select repositories and then select the repository that contains your inline hook source code.

Deploy your connected repository

Now that your GitHub repository is connected, you can begin the deployment process through Netlify.

1. Select the repository you just added to Netlify.
2. Enter a site name for your inline hook and configure any other GitHub integration settings if needed when prompted on the next screen.
3. Select Deploy [site name] to start the deployment process.
4. Confirm that your deployment of your Netlify site was successful by checking the confirmation screen for a message that states that you successfully set up a site on Netlify.

Locate the URL to your inline hook in Netlify

Before you close Netlify, find the endpoint to your deployed inline hook by navigating to logs > functions > [name of your function] in the Netlify console.

In our example, the endpoint is https://oktahook0001.netlify.app/.netlify/functions/telesign.

Configure your Okta telephony inline hook

🚧

CAUTION:

You are subject to all compliance rules as appropriate for your transaction. Note that each country has its own rules and regulations so please follow them carefully.

Before you configure your inline hook

This checklist is crucial for a successful integration process. Please read it thoroughly and ensure you have completed each item before proceeding. Following this checklist will help streamline your implementation.

• Authentication credentials: Your Customer ID and API Key.

• Authorization secret for HTTP header: Generate the authentication secret for the HTTP header. See Basic authentication for more information.

• Your Okta telephony inline hook endpoint: See Locate the url to your inline hook in Netlify for more information.

• Okta Administration access privileges: Access to Okta console including administration access privileges and the Okta Verify App on your mobile device to sign into the account are required.

• Okta Phone authenticator: Configure the Okta phone authenticator in the Okta admin console using the "Add the phone authenticator" procedure listed on this page.

• Add phone to the Okta enrollment policy: Go to Security in the Okta admin console and then select Authenticators. Select the Enrollment tab to add the authenticator to a new or an existing authenticator enrollment policy.

• Understand the basic usage and end user experience: Review Basic usage and the paragraph titled "End-user experience" on Okta's Configure the phone authenticator page.

Steps

📘

NOTE:

Okta only allows one active telephony inline hook.

Follow these steps to configure your Telesign Okta telephony inline hook endpoint.

1. Sign into the Okta console using your administration access privileges.

2. Select Inline hooks from Workflow in the left sidebar.

3. Select Telephony as the type of hook from the Add inline hook menu.

4. Enter a descriptive name for the inline hook name in the Name field.

5. Enter the URL from the Netlify console for your Okta inline hook in the URL field.

6. We recommend that you secure your endpoint using robust authentication methods. You may utilize the Authentication field to transmit your custom secrets. Please ensure that these secrets are different from the REST API key used to call Messaging.

7. Select Save. This activates your telephony inline hook.

Preview and test your inline hook

One option for previewing and testing your inline hook is to use the Okta console after you have configured your Telesign Okta telephony inline hook. For more information about this process, see Preview and test your inline hook.

During inline hook testing, A SUCCESSFUL or an UNSUCCESSFUL status is sent to Okta. An OTP is not generated if the telephony provider fails during the test.

Once you have completed the procedures discussed on this page, see Okta telephony - Send SMS and voice using Messaging for information on how to deliver SMS and voice messages using Messaging.

📘

NOTE:

To quickly see the response from your Telesign Okta telephony inline hook endpoint, you can go to the View service's response section of the Preview tab in the Okta console to see this information.

Successful response

Okta expects a successful response to look like this:

{
  "commands": [
    {
      "type": "com.okta.telephony.action",
      "value": [
        {
          "status": "SUCCESSFUL",
          "provider": "Telesign",
          "transactionId": "0123456789ABCDEF0123456789ABCDEF",
          "transactionMetadata": ""
        }
      ]
    }
  ]
}

Note that transactionId is your Telesign reference ID.

Unsuccessful response

Okta expects an unsuccessful response to look like this:

{
  "error": {
    "errorSummary": "3110",
    "errorCauses": [
      {
        "errorSummary": "3110",
        "reason": "Invalid request",
        "location": "EN-US"
      }
    ]
  }
}

📘

NOTE:

Messaging callback service is an optional feature that is available if you want to receive asynchronous delivery statuses. The Get Status feature can be enabled to receive transaction statuses on demand. Contact our Customer Support Team for assistance and to enable this feature.

Telesign Okta inline hook documentation

• Okta telephony - Generate authentication secret using API explorer
• Okta telephony - Send SMS and voice using Messaging
• Okta telephony - Supported languages for voice text-to-speech
• Okta telephony - Status codes

Additional resources

Contact us

• Contact us to get started with integrating with Okta
• Get started with Telesign and create your trial account

Documentation for related Telesign products

• Verify API
• Messaging
• Intelligence
• Phone ID

Additional Okta resources

• Okta Developer - Telephony inline hook reference
• Okta Docs - Connect to an external telephony service provider
• End user's experience Okta recommends that you review its documentation so you can provide the end user with instructions on how to navigate successfully.