Rate this page:

Thanks for rating this page!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

Integrating with OKTA

Step one: Create an application

Screenshots have been made using Classic UI.

Within Okta, create an Application. Choose SAML 2.0

Okta setup 1 modified

Give the Application a name - for example Twilio Flex. Upload a descriptive logo if needed.

Okta setup 2

Step Two: Configure your Application

Create Basic Settings for the Application. Please note that

  • The SAML Single Sign On URL will be Replace the Account SID (ACxxxx) with your real Account SID.
  • Set Audience URI to match the Single Sign On URL.
  • The Default RelayState should be left blank
  • The Application username can be an email, Okta username or something else unique.

Twilio Flex SSO General Settings

Please ensure that both Response and Assertion are Signed (in Okta you will find them under Advanced Settings).

We do not currently support Assertion Encryption so please set that as Unencrypted.

Step Three: Configure claims

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

All the information supplied from the Identity Provider to Twilio is stored inside Twilio TaskRouter Worker Attributes. Consider local regulations for storing data and only provide data relevant for Flex usage. Learn more about Twilio's Privacy policy here.

You can configure claims by defining a "roles" attribute statements via the Okta console, like so:

Twilio Flex SSO Attribute Statements

For the full_name value, you will need to leverage Okta's "Okta Expression Language" syntax to combine a first and last name in one of the following ways:

  • String.join(" ", user.firstName, user.lastName)
  • ${user.firstName} ${user.lastName}

Okta will pass the following attributes to Flex:

  • full_name
  • image_url (for use in the Agent avatar)
  • roles
  • email

You do not need to specifically claim a UserId, as it is already in the request itself. After you've defined your role, Flex will update the Worker attributes with each successful SSO authentication.

Once a user is created, you should add a role value to their userType attribute in Okta. You can find this under the User/People menu, and in the Profile tab of each user. Available roles are agent, admin, and supervisor.

Define a userType role for your new users

You may add multiple roles for a user by separating their various roles with commas.

Want to learn more? See the documentation on Identity Attributes for further information about naming Attributes and other possible Worker attributes.

Step Four: Save Application information and copy Application details.

After completing the setup on the main page of your Application.

If you are using an older version of Flex UI prior to 0.7.0 follow step 1. If not skip to step 2.

1. Copy the App embed link. This is what you use to trigger Login/SSO and that you configure in your Flex Agent UI.

Okta setup 5 new

2. Select tab Sign On. Click View Setup instructions.

Copy Identity Provider Single Sign-On URL, Identity Provider Issuer and Certificate information. You need this information to configure Flex to use this Application.

Okta setup 6

Step Five: Ensure Users in Directory are assigned to the Application.

Okta setup 7

In this example we override the default username as email to a custom username.

Okta setup 8

Step Six: Configure Flex with your new SAML credentials

Configure SSO in Twilio Console:

Using the details gathered in Step Four, save your SSO configuration with Twilio.

Single Sign-On

Additional Configuration

Our Configuring SSO page has additional detail on how to initiate login from your Identity Provider, how to login to a self-hosted domain, and details on attributes that can be defined for each identity.

Rate this page:

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.