How to Bring Your Own Keys for Okta Telephony with Twilio Verify

Okta BYOK blog

Okta requires companies to bring their own telephony (BYOT) if they want to send SMS one-time passcodes (OTPs) or phone calls for multi-factor authentication or account recovery. Twilio Verify is an out-of-the-box solution for sending OTPs, and now Okta makes it straightforward to get set up with Verify in just a few steps.

This post will cover how to provide Okta with the necessary API keys to configure your telephony and be up and running in no time.

Prerequisites for Adding Twilio Verify to your Okta Org

Before you get started, you'll need the following account details:

• A Twilio Account ( login or create one for free if you don’t have one yet)
• Twilio Account SID (ACxxx…, find it at twilio.com/console)
• Twilio Auth Token (also find it at twilio.com/console)
• Verify Service SID (VAxxx…, find or create one here: twilio.com/console/verify/services)
• Enable Custom Code on your Verify Service.

Custom code allows Okta to set the verification code in the request. This is necessary for integrating with Okta's telephony workflows.

Bring your own key

Inside your Okta admin console, navigate to Customizations >> Telephony Providers. Select Twilio and paste in your Account SID, Auth Token, and Verify Service SID.

Okta encrypts and securely stores your credentials.

Send feedback to Twilio Verify

Implementing Twilio Verify Feedback allows you to use Verify Fraud Guard and populate your Insights Dashboard. Practically, you will send an API request for each approved verification to update a Verification status.

This setup uses an Okta Event Hook (hosted on a Twilio Function) to notify Twilio of successful MFA events.

Before starting, determine the best way to retrieve user phone numbers from your Okta instance. This tutorial uses the Okta User API but you can also use the Okta Factor API.

Prerequisites to sending feedback from Okta

• Create Okta API Token: Generate a token in the Okta Admin Console. Copy it immediately, as it will not be shown again.
• Security: Save this token in a secure password manager; you will need it for your Twilio environment variables.

Create a Twilio Function

The Function acts as the endpoint for Okta’s Event Hook. Use the following steps to create and deploy the Twilio Function:

• Create a Function Service: In the Twilio Console, create a new Function Service, call it "Okta" (or anything you like).
• Create Function: add a new function (e.g., /OktaEventHook) to your service.
• Set Visibility: Change the access level from Protected to Public.
• Configure Dependencies : Add the @okta/okta-sdk-nodejs module (you can find latest release here).
• Add Code:Copy the code or from this repo to your function /OktaEventHook and save it.
• Configure Environment Variables: Add the following keys:
  • okta_auth_token: The API token created in the prerequisites.
  • okta_org_baseurl: Your Okta URL (without -admin, e.g., https://your-org.okta.com).
  • auth_secret: A random string used for Basic Authentication.
  • VERIFY_SID: Your Twilio Verify service identifier. Starts with VA.
• Save and Deploy: Save and deploy the function. Keep Live Logs open for troubleshooting.

Configure the Okta Event Hook

This connects Okta events to your new Twilio Function. Follow the steps in Okta's documentation to create an event hook.

• Navigate: In Okta, go to Workflow > Event Hooks and click Create Event Hook.
• Endpoint Details:
• Name: e.g., "Twilio Verify Feedback".
• URL: Your Twilio Function URL (e.g., https://your-service.twil.io/OktaEventHook).
• Authentication: Use HTTP Basic Authentication.
• Authentication field: auth_secret
• Authentication secret: The random string you saved in your function's environment variables.
• Subscribe to Events: Add User's MFA factor activated and Authentication of user via MFA.
• Verify: Click Save & Continue

Test and run

After you've saved your telephony details, you can add SMS and Voice as MFA and recovery options to your Okta configuration. Learn more about configuring telephony in the Okta documentation.

Then add a phone number to your user and test the end to end flow following Okta's instructions for configuring end user phone authentication.

After end to end testing with a real login, head to the Twilio Console Verify Logs. Select a Verification ID to open its Verification details page and view more comprehensive information such as different actions and outcomes that happened during the Verification's lifecycle and any related error codes, if applicable.

Once you have the feedback enabled, you will have access to the Verify SMS Fraud Insights dashboard on Twilio Console. The dashboard illustrates the impact fraud could have had without intervention, and also allows you to discover trends and insights that you can use to better optimize your product against fraud.

To view your dashboard, go to Twilio Console and navigate to Monitor > Insights > Verify > Fraud which will open the Overview tab. There, you'll find several sections relating to your Fraud metrics

Customize your Okta telephony with Twilio Verify implementation

If you need a more customized approach, learn how to set up Twilio Verify with Okta inline hooks. The inline hook approach requires more configuration but allows you more flexibility to do things like Lookup a phone number before sending an OTP or anything else you might want to do in code.

That's it! Now you can monitor performance of your Verify OTPs with the insights dashboard and explore more options in the Verify API documentation.