Have you already configured SSO using the
preview.twilio.com endpoint? Learn how to update your existing configuration with the Flex SSO Migration Guide.
Navigate to https://developer.okta.com/ and create a free developer account.
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.
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.
Give the Application a name - for example Twilio Flex. Upload a descriptive logo if needed.
Create Basic Settings for the Application. Please note:
- Set SAML Single Sign On URL to
https://iam.twilio.com/v1/Accounts/ACxxxx/saml2. Replace the Account SID (ACxxxx) with your real Account SID.
- Set Audience URI to
https://iam.twilio.com/v1/Accounts/ACxxxx/saml2/metadata. 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.
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.
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.
You can configure claims by defining a "roles" attribute statements via the Okta console under ‘Attribute Statements’ group, like so:
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)
With the provided setup Okta will pass the following attributes to Flex:
image_url(for use in the Agent avatar)
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
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.
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.
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.
To assign your newly created application to a user navigate to ‘Applications/Applications’ menu and click ‘Assign Applications’ button:
In this example as the part of the assignment process we override the default username as email to a custom username.
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 preview.twilio.com URL to iam.twilio.com see our migration guide.
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.