# How to Configure Okta as a Frontline Identity Provider

Twilio Frontline integrates with your existing Identity Provider to authenticate users and enable single sign-on (SSO). Frontline can work with any Identity Provider (IdP) that supports SAML (Security Assertion Markup Language) 2.0, enabling you to use your primary corporate account as the Identity Provider for Frontline.

This guide will walk through the steps to set up Okta so that it can be used as the IdP for Frontline.

> \[!NOTE]
>
> An **Identity Provider (IdP)** is a trusted entity that lets you enable SSO to access other websites or services such as Twilio Frontline with a single login. Your users can keep using their corporate user identities without having to remember lots of passwords or having to retype passwords each time they access a different service connected to the same Identity Provider.

## 1. Register a developer account at Okta

If you already have an Okta developer account, jump straight to Step 2. Otherwise, navigate to [https://developer.okta.com/](https://developer.okta.com/) and create a free developer account.

## 2. Create an application on Okta

OK, let's create an Application in Okta. Just follow these steps:

1. Navigate to the **Applications** tab, click **Applications**, and then **Create App Integration**:

   ![Create a new app integration with SAML 2.0 selected for sign-in method.](https://docs-resources.prod.twilio.com/d7ca9d495b284c4eaa457ba804f6343ef0bab2e2728360464d50bde1069b551c.png)
2. On the **Create a New Application Integration** panel, choose the **SAML 2.0** sign on method and then click **Next**.
3. You'll be taken to the **Create SAML Integration** page. Under **General Settings**, give the Application a name; for example, `Twilio Frontline`. You can also upload a logo if you like:

   ![Okta SAML integration feedback form with options for customer type, app type, and contact details.](https://docs-resources.prod.twilio.com/402f34adeba724dfea76a4379e465a59f70b14e210d31d7dd54d4a1e67f8efb7.png)
4. Click **Next** when you're done.

## 3. Configure your Application

Okta will now show you the **Create SAML Integration** page's **SAML Settings** tab. Just fill out the form that's displayed as follows:

1. Set the **Single sign on URL** to `https://iam.twilio.com/v2/saml2/authenticate/JBxxxx`. Just replace the example Realm SID, `JBxxxx`, with your own Realm SID, which you can find on the [Frontline Console SSO configuration page](https://www.twilio.com/console/frontline/sso).
2. Set the **Audience URI** to `https://iam.twilio.com/v2/saml2/metadata/JBxxxx`. Again, replace the Realm SID (`JBxxxx`) with your own Realm SID.
3. Leave the **Default RelayState** field blank.
4. The **Application username** can be an email address, an Okta username, or any other unique value:

   ![SAML settings with HTTPS added to Issuer ID field.](https://docs-resources.prod.twilio.com/8c0064b201a6c53ff001028013e28dc83e7257b705bc75327a764b74a6e27573.png)
5. Please go to **Advanced Settings** and ensure that both **Response** and **Assertion Signature** are **Signed**. We do not currently support **Assertion Encryption** so please set that as **Unencrypted**.

   ![Add https to SAML Issuer ID.](https://docs-resources.prod.twilio.com/2222c66bccc9b83b33c0f5ffe97133c63145ca1f618868e26ed576ba00b19116.png)

## 4. Configure Claims

Claims are key-value pairs that the Identity Provider asserts to the application to be true. Frontline uses these to determine the key information it requires about each Frontline User.

You configure claims by defining a "roles" attribute statements in the Okta console under **Attribute Statements**, like so:

![Attribute statements with email and roles mapped to user.email and user.userType.](https://docs-resources.prod.twilio.com/89ec655514593c1fd7f2cd0789c3dc7cdd319f6ef5397dc8e3387e8a741a969e.png)

The value for each attribute is:

`user.email`

`user.userType`

With the provided setup Okta will pass the following attributes to Frontline:

* `email`
* `roles`

You do not need to explicitly claim a `UserId`, as it is already in the request itself.

After adding attributes, press **Next.**

On the next screen select "I'm an Okta customer adding an internal app" and optionally complete the details requested by Okta and click **Finish**. These are not required by your App.

![Okta Feedback.](https://docs-resources.prod.twilio.com/ec4d659d6a7ebbe0faa4608da360bc35433fbaf18b7ca5943b01883cfc4b3cfa.png)

You can now add users by going to **Directory > People** and clicking the "Add Person" button or importing users as needed by selecting the More Actions button.

Once a user(s) has been created, you should add a role value to their `userType` attribute in Okta. This is done by selecting the user (click their name) and then navigating to the user's **Profile** tab. Click **Edit** and set `agent` as the role for the user in the `userType` attribute.

![Form fields for timezone, user type set as agent, and employee number.](https://docs-resources.prod.twilio.com/4e831b3cbe1a71029338432aa12d619f8e1194d79963a09a7fce05ce6e97be10.png)

> \[!NOTE]
>
> Only the `agent` role is available for selection.

See documentation on [Identity Attributes](/docs/frontline/sso#identity-attributes-and-frontline-roles) for additional information about naming Attributes.

## 5. Copy Application details

Click **Applications** in the main menu and select **Applications**. Now click on your application and select the **Sign On** tab. Click the **View SAML Setup Instructions** button.

You'll be presented with a new screen of Application information. Copy the following information to a safe location:

* Identity Provider Single Sign-On URL,
* Identity Provider Issuer, and
* Certificate information.

You will need this information to [configure Frontline to use this Application](#7-configure-frontline-with-your-new-saml-credentials).

## 6. Assign Users to the Application

To assign your newly created Application to one or more users, go back to the previous page or click Applications and then select the **Assignments Users to Apps** button.

1. Select your Application on the left-hand side, under **Applications**. On the right, under **People**, select one or more users:

   ![Okta interface for assigning Twilio Frontline app to John Smith using SAML 2.0.](https://docs-resources.prod.twilio.com/d57c309fe3c5b63e127dfeac3dcd69abdb569046dcd73c90119a91a500b62f4b.png)
2. Now click **Next**.

## 7. Configure Frontline with your new SAML credentials

Grab the URLs you noted in [Step Five](#5-copy-application-details) and configure SSO on the [Frontline Console SSO configuration page](https://www.twilio.com/console/frontline/sso) as follows.

1. Under **Workspace ID**, enter your preferred name.
2. Under **SSO URL**, enter the **Identity Provider Single Sign-On URL** field you had copied from Okta.
3. Under **X.509 Certificate**, paste the certificate you had copied from Okta.

![SSO configuration page for Twilio Frontline with fields for Workspace ID, Realm SID, and SSO URL.](https://docs-resources.prod.twilio.com/5d5ea55643984f6a107b8712c23d860463146bd250788ed871ef3bd6ccdd5f43.png)

Click **Save** and you're done!