# 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](https://developer.okta.com/signup/)
- [Sinch account](https://dashboard.sinch.com/signup) with enough credits


## Collect Sinch application key and secret

Go to `Apps` in the `Verification` section in [Sinch dashboard](https://dashboard.sinch.com/).
Grab the `Key` and `Secret` of the application you intend to use with Okta. You will need them in the next steps.

![sich-dashboard](/assets/sinch-dashboard.9d575ae56e8bfd9fd363c8463828d5e627c7fc7b7bebc3e6c5bab96eabb83f2c.7702d8e2.png)

## 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](/assets/okta-workflow-create.d817d262fbb30d0c52a6d48bb385cfbf89a1c346d11edde5b3bd5eb1c7c2441f.7702d8e2.png)

In the `Create Inline Hook` form that appears next:

| Field | Description |
|  --- | --- |
| `Name` | Can be any value, but we suggest something that makes sense to you. |
| `URL` | Must have the value of `https://okta.verification.api.sinch.com/hook`. |
| `Authentication field` | Must have the value of `Authorization`. |
| `Authentication secret` | Must 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:


```pwsh
$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](/assets/inline-hook-form.eb3252a50ca0c42995c7a77a2882a69be48cb5250a098a288fa1f3c45a99d3a5.7702d8e2.png)

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](/assets/hook-preview.9733f87f3a8b7df65178f5de76a73f79cfda8e01c051902fa0ab4ddafabf30e8.7702d8e2.png)

### Setup Phone Authenticator

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

![Add Authenticator](/assets/okta-add-authenticator.117d0777f391797a91f2ac85e3c8cc6d852b0e524871530bf85df307426ebaa7.7702d8e2.png)

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

![Add Phone Authenticator](/assets/okta-add-phone.7c1f23c20508a9697154cde43f5a6a9523b2e8bb0ea3e264c730e57e4f4a2101.7702d8e2.png)

### Setup Authentication Policies

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

![Configure Enrollment](/assets/authenticator-enrollment.bd3d84ad97a40372f5fa80b47e332b4ddd2b18e31fe655abb9c0612561af10ae.7702d8e2.png)

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

![Edit Authentication Policies](/assets/edit-authentication-policies.5d8f3525aa450823b7851bd2da12f1e0f371dd497f166ed58a2d4fb787e5ef0f.7702d8e2.png)

Make sure that the `Authentication methods` section includes Phone Authenticator.

![Edit Policy Configuration](/assets/okta-policy-config.20c540c137104754abdadc2dcc130b2c7e9287c3701d84a075227a81165967dd.7702d8e2.png)

## 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.