Menu

Expand
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

Register a developer account at Okta

Navigate to https://developer.okta.com/ and create a free developer account.

Create an application on Okta

Screenshots have been made using Okta.com Classic UI. You can switch to classic appearance with a drop-down in the top left corner. In case you prefer not to switch to Classic UI, your experience might be different from what is described in the following article and some functionality might not be accessible.

Default 'Developers Console' appearance:

Developers Console UI

Classic UI:

Classic UI

Staying within Okta, create an Application. Navigate to “Applications” tab and click “Add application” and then “Create New App”. Choose a SAML 2.0 sign on method.

Create a new application

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

Okta setup 2

Configure your Application

Create Basic Settings for the Application. Please note:

  • The SAML Single Sign On URL will be preview.twilio.com. Replace the Account SID (ACxxxx) with your real Account SID.
    • https://preview.twilio.com/iam/Accounts/<YOUR ACCOUNT SID HERE>/saml2
  • 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.

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 under ‘Attribute Statements’ group, 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}

With the provided setup 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 by going to the 'Directory/People' (for Classic UI) or 'Users/People' (for default ‘Developer Console’ UI) menu, and then navigating to 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.

Save Application information and copy Application details.

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

Ensure Users in Directory are assigned to the Application

To assign your newly created application to a user navigate to ‘Applications/Applications’ menu and click ‘Assign Applications’ button:

Assign an application

In this example as the part of the assignment process we override the default username as email to a custom username.

Okta setup 7

Okta setup 8

Configure Flex with your new SAML credentials

Configure SSO in Twilio Console: https://www.twilio.com/console/flex/users/single-sign-on

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.