Okta integration guide

This document will guide you through process of configuring Sinch as a telephony provider for your Okta organization.

What you need

• Okta Developer Edition organization
• Sinch account with enough credits

Collect Sinch application key and secret

Go to Apps in the Verification section in Sinch dashboard. Grab the Key and Secret of the application you intend to use with Okta. You will need them in the next steps.

Setup Okta account

Setup Telephony Inline Hook

In the Okta Admin Console, navigate to Inline Hooks in the Workflow section. Click Add Inline Hook and select Telephony in the dropdown that appears.

In the Create Inline Hook form that appears next:

The rest of this guide assumes Sinch was used for Name.

Obtaining Authentication secret

The Basic authentication standard dictates that key and secret must be encoded as Basic base64(key:secret), where Basic is a literal, key and secret are Sinch credentials collected earlier, and base64 is an encoding function.

Avoid using base64 encoding tools available online as they might leak your secrets. As a safe alternative, operating system, native tools can be used. For instance on Windows using Powershell:

$ApplicationKey="key from Sinch dashboard"
$ApplicationSecret="secret form Sinch dashboard"

$Token=$("${ApplicationKey}:${ApplicationSecret}" | % { [Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes($_)) })

Write-Host "Basic ${Token}"

Preview and test SMS

In the Preview tab:

1. Select a user to test the hook with.
2. Select MFA Verification .
3. Click Generate request .
4. Review data in generated JSON:
   • phoneNumber must include country calling code,
   • code in the msgTemplate must match otpCode ,
   • deliveryChannel must be SMS .
5. Click View response .

Preview and test Voice

In the Preview tab:

1. Select a user to test the hook with.
2. Select MFA Verification .
3. Click Generate request .
4. Review data in generated JSON:
   • phoneNumber must include country calling code,
   • deliveryChannel must be Voice ,
   • locale should specify desired language.
5. Click View response .

The Customization section at the end of this document provides more information about configuring both delivery methods.

Setup Phone Authenticator

To use the created hook in the authentication pipeline, navigate to Authenticators and click Add authenticator.

Select Phone and review the options in the Add Phone dialog.

Setup Authentication Policies

Configure the newly added Authenticator in the Enrollment tab according to your needs.

In the Authentication Policies configure selected policies to use Phone Authenticator by clicking Edit as shown in the screenshot below.

Make sure that the Authentication methods section includes Phone Authenticator.

Customization

SMS

In SMS delivery, Sinch will respect the message template provided by Okta, excluding selected countries for legal reasons:

• Kuwait
• United States
• Singapore
• United Arab Emirates
• Libya

In those countries sending business messages requires preregistering them within the government. Sinch will use one of the approved SMS templates, instead of arbitrary ones provided by Okta. To customize SMS messages for those destinations, contact Sinch support.

Voice

To customize voice messages, contact Sinch support.

Other considerations

Failover to Okta telephony provider

If processing fails on the Sinch side or if your account lacks sufficient credits, Okta will attempt to send the OTP using its telephony providers.