How to bring your own telephony to Okta with Twilio Verify (2024)

Okta now requires Bring Your Own Telephony (BYOT), enabling you to integrate any telephony service provider with Okta's authentication and verification systems. This document will cover how to BYOT with the Twilio Verify API for SMS or Voice calls using Okta's telephony inline hook for its workforce identity cloud. The code for this project can also be found on GitHub .

Learn more about the benefits of using the Verify API.

How does telephony inline hook with Twilio Verify work?

The sequence of events for SMS/Voice one-time passcode (OTP) authentication includes:

• A user logs in to an application page using Okta credentials.
• [Optional] Okta sends the end user’s phone number to the Twilio Lookup API to utilize various Twilio lookup packages , including formatted number and line type intelligence. This step is optional and applies only if the Twilio lookup package is purchased.
• The Twilio Lookup API returns the correctly formatted “To Number,” if applicable.
• Okta sends a request to Twilio's Verify API with the custom code and the formatted phone number .
• The Twilio Verify API sends the custom code to the end user based on the selected channel in the API request
• The user enters this information onto a form on the application’s Okta login page.
• Okta performs a verification check using its own logic and redirects the user to the protected application.
• Okta provides feedback to Twilio indicating whether the user verified the code, enabling proactive monitoring of global routing and operational status.

Prerequisites for sending OTPs with Okta and Twilio Verify

This tutorial requires:

• An Okta account
• A Twilio Account. Log in or create one for free here .
• A Twilio Verify Service. Create one in the Twilio Console . Please note down the following details used for configuration:
• Twilio Account SID (ACxxx….….)
• Twilio Auth Token (you can locate both Account SID and Auth Token at the home page after you login your Twilio account)
• The newly created Verify service SID (VAxxx……)
• "Custom Code" enabled on your Verify Service. File a ticket with Twilio Support to enable the Custom Code feature for Verify SMS and Voice OTPs. Include your Verify Service SID in the request.

Step 1 - Create a Twilio Function to send verification codes

Twilio Functions is a serverless environment that empowers developers to quickly and easily create production-grade, event-driven Twilio applications that scale with their businesses. Twilio Functions provide a complete runtime environment for executing your Node.js scripts. Functions integrates popular package managers like NPM, and provides a low latency Twilio-hosted environment for your application.

If you want to host your own code, Twilio has SDKs in 7 popular languages. Learn more about the Verify API in the documentation .

To create a function, go to the Twilio Console :

• Create a new Function Service , call it "Okta" (or anything you like).
• Add a new function and give it a name, for example, Okta_MFA.
• Change the function's visibility from protected to public .
• Copy the following code to your function Okta_MFA and save it.

exports.handler = async function(context, event, callback) { try { console.log(event.request.headers); if (context.auth_secret !== event.request.headers.auth_secret) { throw new Error("Authentication failed"); } let client = context.getTwilioClient(); // https://developer.okta.com/docs/reference/telephony-hook/#data-messageprofile let to = event.data.messageProfile.phoneNumber; let customCode = event.data.messageProfile.otpCode; let channel = event.data.messageProfile.deliveryChannel.toLowerCase() === "sms" ? "sms" : "call"; let verification = await client.verify.v2 .services(context.VERIFY_SID) .verifications.create({ to, channel, customCode }); console.log(verification); console.log(verification.sendCodeAttempts); let response = { commands: [{ type: "com.okta.telephony.action", value: [{ status: "SUCCESSFUL", provider: "Twilio Verify", transactionId: verification.sid, transactionMetadata: verification.sendCodeAttempts.at(-1).attempt_sid, }, ], }, ], }; return callback(null, response); } catch (error) { console.error("Error: " + error); let errorResponse = { error: { errorSummary: error.message, errorCauses: [{ errorSummary: error.status || error.message, reason: error.moreInfo || error.message, }, ], }, }; return callback(null, errorResponse); }};

• Setup the following Environment variables:

• Save and Deploy
• Take a note of your Twilio Function URL, in this example, it will be something like https://Okta-xxxx.twil.io/Okta_MFA . This is the URL that you will use when setting up the Okta telephony inline hook
• Make sure Live Logs is toggled on for troubleshooting purposes.

Everything in Twilio has now been set up. Now head over to the Okta admin dashboard.

Step 2 - Configure Okta Inline Hook

If you don't have an Okta Account you can create one for freehere.

Add a telephony inline hook

• In the Admin dashboard, go toWorkflow -> Inline Hooks.
• ClickAdd Inline Hook, and then selectTelephony.
• Name -something like "Twilio"
• URL -paste your Function URL
• Add theAuthentication fieldandAuthentication secretvalues. This example usesHTTP Basic Authentication.

Authentication field= auth_secret {environment variable stored in Twilio function above}

Authentication secret= xxxxx { random string created and stored as auth_secret environment variable above)

Please note: the Authentication field and Authentication secret will be used to authenticate the API call from Okta. Make sure that these values are matched with the key/value pair created in Twilio Function above.

• Optional. AddCustom Headers. In this blog I didn't add any custom headers.
• ClickSave. This activates the telephony inline hook.

Please note that there can only be one active telephony inline hook at a time in Okta.

Step 3 - Preview and test the telephony inline hook

If you haven't already, enable phone authentication in your admin dashboard underSecurity > Authenticators > Phone.

To test the integration, use the Inline Hooks Preview feature.

• InWorkflow > Inline Hooks, find theActivetelephony inline hook and clickActionsPreview. ThePreviewtab of the inline hook opens.
• In the tab, go toConfigure inline hook requestand 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.
• InPreview example inline hook request, clickGenerate request. This generates the JSON request that Okta sends to your telephony provider.

• ClickEditto edit the generated request. For example, you can edit the user profile or the phone number before sending the request. (replace the default phone number (9876543210) with a user’s mobile number inE164 format)

• In the Viewservice's response, clickView response. This triggers the hook and displays the response from Twilio.

Please note that Okta will not generate an OTP if the connection between Okta and Twilio fails during the test. Successful completion of the Twilio Function will include logs with verification attempt details.

You also have the option to access fundamental metrics for this telephony inline hook, aiding in the monitoring of your telephony service provider's performance within Okta. More detailscan be found in Okta's documentation.

What’s Next?

Congratulations! Your users can now log in to your application with multi-factor authentication enabled, receiving a one-time password via Twilio Verify.Interested to know more about Twilio Verify? Check outTwilio Verify API documentation. We can't wait to see what you build and secure!

Dr Mingchao Ma has more than 15 years’ experience in Cybersecurity. In the account security team at Twilio he helps customers build solutions using Twilio Cloud security APIs. He previously worked at Microsoft UK helping financial sector customers adopt Microsoft Cloud security technologies. Before this he was a lead security architect at IBM UK. Mingchao has a PhD in information security, and cybersecurity certifications such as CISSP-ISSAP, CISM, SABSA etc. He is a Microsoft Certified Azure Solutions Architect Expert, Microsoft 365 Certified Enterprise Administrator Expert and Microsoft Certified Azure DevOps Engineer Expert.

Yukti Ahuja is a Principal Solutions Engineer at Twilio. As an SE she isa problem solver extraordinaire, blending technical expertise with communication skills to bridge the gap between complex technology and practical solutions for customers.