Skip to content
Verification/
/
Okta
Last updated

Okta integration guide

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

What you need

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.

sich-dashboard

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.

Create Inline Hook in Okta Workflow

In the Create Inline Hook form that appears next:

FieldDescription
NameCan be any value, but we suggest something that makes sense to you.
URLMust have the value of https://okta.verification.api.sinch.com/hook.
Authentication fieldMust have the value of Authorization.
Authentication secretMust adhere to the Basic authentication standard using the Sinch application key and secret.

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}"

Configure Sinch Telephony hook

Important!

Pay special attention to leading and trailing whitespace (space, tab, line break) characters when filling in the form!

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.

Hook Preview

Setup Phone Authenticator

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

Add Authenticator

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

Add Phone Authenticator

Setup Authentication Policies

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

Configure Enrollment

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

Edit Authentication Policies

Make sure that the Authentication methods section includes Phone Authenticator.

Edit Policy Configuration

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.

Previous page
Next page