Configure Okta IdP with Flex

Have you already configured SSO using the endpoint? Learn how to update your existing configuration with the Flex SSO Migration Guide.

Register a developer account at Okta

Navigate to and create a free developer account.

Create an application on Okta

Screenshots have been made using 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:

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

Okta SSO Flex (IAM v1)

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

Grab the URLs you noted in step four and configure SSO on the Flex Console Single Sign-on settings page. Be sure that the Twilio SSO URL field matches the value you provided in Okta for SAML Single Sign On URL. To learn more about migrating from the URL to see our migration guide.

Twilio Console SSO Config for Okta

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 by visiting Twilio's Community Forums or browsing the Twilio tag on Stack Overflow.

Thank you for your feedback!

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

Sending your feedback...
🎉 Thank you for your feedback!
Something went wrong. Please try again.

Thanks for your feedback!

Refer us and get $10 in 3 simple steps!

Step 1

Get link

Get a free personal referral link here

Step 2

Give $10

Your user signs up and upgrade using link

Step 3

Get $10

1,250 free SMSes
OR 1,000 free voice mins
OR 12,000 chats
OR more