Skip to contentSkip to navigationSkip to topbar
Rate this page:
On this page

Configuring SSO and IdP in Flex


Twilio Flex integrates with your existing Identity Provider to authenticate users (agents, supervisors or administrators) and enable single sign-on (SSO). Flex allows for integration with any Identity Provider that supports SAML 2.0 (such as Google, Active Directory, Okta, etc.), enabling you to use your primary corporate account as the identity provider for Flex.


Definitions

definitions page anchor
  • Identity Provider (IdP) is a trusted entity that lets you enable single sign-on to access other websites or services such as Twilio Flex with a single login. Your users can keep using their corporate user identities without having to remember many passwords or having to retype passwords each time they access a different service connected to the same Identity Provider. An example Identity Provider is Okta.
  • Security Assertion Markup Language (SAML) is an open standard for exchanging authentication and authorization data between parties, in particular, between an Identity Provider and a Service Provider. SAML is an XML-based markup language for security assertions (statements that service providers use to make access-control decisions). Twilio Flex uses SAML version 2.0.
  • Service Provider (SP) is configured as an Application on an Identity Provider to enable single sign-on. In this context, Twilio Flex is the Service Provider.

Enhanced and legacy SSO configuration

enhanced-and-legacy-sso-configuration page anchor

Your Flex instance uses either enhanced or legacy SSO configuration, depending when you created your Flex account. Both configuration types provide a reliable way to use your existing IdP to authenticate users with SSO.

Enhanced SSO configuration

  • Provides a simplified setup experience and enhanced SSO based on the OAuth 2.0 authorization framework
  • Applies to Flex accounts that are using Flex UI 2.5.x or later and are configuring SSO in Flex for the first time
  • Migration available for existing Flex accounts that are using Flex UI 2.7.x or later
  • Available for self-hosted Flex accounts that are using Flex UI 2.7.x or later

Legacy SSO configuration

  • Provides a traditional setup experience
  • Applies to for Flex accounts that meet either (or both) of these conditions:

    • Set up SSO in Flex before January 29, 2024
    • Use Flex 2.4.x or earlier
(information)

Info

All Flex customers using the legacy SSO configuration need to migrate to the enhanced SSO configuration prior to June 2025.

How can I tell which SSO configuration type I have?

how-can-i-tell-which-sso-configuration-type-i-have page anchor

If you're not sure whether you have enhanced or legacy SSO configuration, compare your Single sign-on page to the following screenshots:

Enhanced SSO configurationLegacy SSO configuration
Single sign-on has not yet been set up.


or

Single sign-on info page for enhanced SSO configuration.




Single sign-on info page for legacy SSO configuration.

Configure your Identity Provider to support Twilio Flex

configure-your-identity-provider-to-support-twilio-flex page anchor

The steps to configure Flex as an application (Service Provider) within your Identity Provider will be different depending on which Identity Provider your organization uses. Below, you can find documentation required to set up Flex as a Service Provider in a few popular Identity Providers:


Identity Attributes and Flex Roles

identity-attributes-and-flex-roles page anchor

Your Identity Provider can provide any number of claims (key-value pairs) to Flex. Four of these are mandatory: Unique ID/User ID, list of User's Roles, Full Name and Email. The Unique ID should be provided in the request header, so it's likely you won't need to explicitly set it.

Flex includes the following roles:

RoleDescription
adminGrants access to all of the pages in the UI. Admins can use the Flex Admin, Agent Desktop, Teams, Queue Stats, Dashboard, Analyse and also Questionnaires (Flex Insights features) and the Flex Dialpad (if enabled).
supervisorGrants access to Agent Desktop, Teams, Queue Stats and Dialpad (if enabled).
agentGrants access to Agent Desktop and Dialpad (if enabled)

The user data sent to Flex from the Identity Provider is stored in the TaskRouter Worker attributes. This allows you as the contact center developer to adapt the Flex UI using data about the logged in user from your Identity Provider. The Worker attributes created for the logged-in user are updated on every successful SSO login, so any changes to user data made in your Identity Provider will also be represented as worker attributes.

The Attributes can be divided into 3-categories.

  • Mandatory: The list of mandatory parameters required for Authentication and Authorization
  • Flex - Agent: These are parameters used by the Agent Desktop of Flex
  • Flex Insights: These parameters are highly recommended if you are using the Flex Insights capabilities of Flex

Attribute conversion and data types

attribute-conversion-and-data-types page anchor

By default, all attributes will be transformed as strings to TaskRouter attributes except for roles attribute which defaults to stringarray (comma as separator).

It is possible to state the attribute type in the attribute name as follows:

name[.type]

where type is one of {string | int | boolean | array | stringarray | intarray | booleanarray}

Examples

examples page anchor
Attribute NameTypeExample Value
name.stringStringMary
skill.intInteger1
sales.booleanBooleantrue
languages.stringarrayString Arrayen,de,fr
skills.intarrayInteger Array1,2,3,4

Incorrectly defining the attribute type and value (example skill.int defined as "a" or skill.int defined as "1.23") will result in Flex throwing a - 400 Error invalid attribute format. No TaskRouter changes will be made if the attribute definition(s) are incorrect.

Note that roles is a special attribute that accepts a comma-separated list of roles and does not require casting to stringarray.

contact_uri is used by TaskRouter and Twilio Voice SDK to dequeue a call (additional information). By default, the call is dequeued to the worker's contact_uri attribute using Twilio's JavaScript Voice Client (example: client:userId). The contact_uri is automatically configured by Flex and does not need to be set within your Identity Provider. The specific identity value will be escaped to only include alphanumeric and underscore characters.

The incoming call can also be dequeued to a SIP interface (sip:someone@somedomain.com) or a phone number by setting contact_uri as a phone number (+14151112222 - E.164 format). To dequeue to these identities, the contact_uri should be set within your Identity Provider.

When dequeuing the call to an international number please ensure the destination country is enabled in Twilio Console > Programmable Voice > Calls and Geo Permissions.

Attribute NameTypeValue / Example
rolesStringarrayagent, admin
full_nameStringBob Bobson
emailStringjohn@company.com
AttributeTypeValue / Example
departmentStringSales
emailStringmary.smith@company.com
locationStringLondon
managerStringAdam Shepherd
phoneString+15555555555
rolesStringarraywfo.team_leader
team_idString1
team_nameStringSales VIP
team_name_in_hierarchyStringLondon,Sales,VIP

You can also define the TaskRouter capacity per channel via these attributes. For example, a new user added to Flex may be available for voice tasks and have a default chat capacity of 1. These can be modified using custom attributes:

AttributeTypeValue / Example
channel.voice.availabilityBooleanfalse
channel.chat.capacityInteger3

These special attributes can be formed for any of the TaskChannels that you have defined within your Flex TaskRouter Workspace.


How does Twilio Manage Identities?

how-does-twilio-manage-identities page anchor

Each user that logs in to Twilio Flex via SAML Identity Provider will automatically become a Flex User. To learn more, see Manage Flex UI users.

(warning)

Warning

When enabling new Flex users via SSO, you will incur charges as soon as they log in. The pricing is noted on your Twilio contract if you're working with the Twilio sales team. For general information on Flex pricing, see How Does Twilio Flex Pricing Work?(link takes you to an external page)

Flex will also auto-provision a TaskRouter Worker for this identity - TaskRouter is at the core of Flex and is required to enable intelligent skills-based routing of tasks to Agents or Supervisors.

Whenever a user logs in to Flex, all claims passed are checked and updated if necessary, using the Identity Provider as the source of truth. If you would like to update a specific Worker attribute directly then please do not configure it in the Identity Provider claims/attributes.

Can I log into Flex using an identity provider-initiated login, like an Okta tile?

can-i-log-into-flex-using-an-identity-provider-initiated-login-like-an-okta-tile page anchor

Yes, with the exception of Google Workspace single sign-on. The SSO Configuration(link takes you to an external page) in Twilio Console has an optional Default Redirect URL field. When provided, this allows IdP-initiated login to route into Flex. If your agents use Flex from flex.twilio.com, then provide the login link listed in your SSO Configuration(link takes you to an external page). For example:


_10
https://flex.twilio.com/dancing-owl-1234

Otherwise, you would use your own self-hosted Flex URL.

How do I log in to a self-hosted domain?

how-do-i-log-in-to-a-self-hosted-domain page anchor

For your security, all self-hosted domains must be registered with Twilio to enable SSO login. These Trusted Domains can be provided alongside your SSO Configuration within the Twilio Console(link takes you to an external page). The following patterns can be used when providing a Trusted Domain:

example.comallows example.com but not email.example.com
flex.example.comallows flex.example.com but not example.com
*.example.comallows one.example.com or two.example.com, but not example.com or one.two.example.com
127.0.0.1 or ::1allows the IP address
localhostallows localhost

The * can only be used to wildcard subdomains. For example, example.*.com or example*.com are not supported.

(warning)

Warning

If you are using Flex's enhanced SSO configuration and have a custom domain, your Flex account must be running Flex UI 2.7.x or later.

Can I log into Flex Agent Desktop without an Identity Provider?

can-i-log-into-flex-agent-desktop-without-an-identity-provider page anchor
(warning)

Warning

If you have logged in through Twilio Console, avoid logging in using an SSO provider to prevent a secondary account created that will incur charges overtime. Likewise, logging in with your SSO provider and then logging into Twilio Console will grant you two separate profiles that will each be billed.

Yes, Twilio Console users (except those that only have the Billing role within Console(link takes you to an external page)) have access to Flex. They can launch Flex from within the Twilio Console, and they log in with the Flex Administrator role. Support users log in with the Read-only Administrator role. (For more details, see Manage Flex UI users.) We recommend this approach for your admins and developers when your application is under development.

Note that Flex creates different users depending on the login method. For example, a user with the same email address will create two Flex personas if they log in using two alternate methods, for instance, if they log in with SSO and then again directly via the Console using Twilio credentials.

You can trigger the 'Login with Twilio' option in two ways:

  1. By selecting ' Launch Flex ' from within the Twilio Console. This is available on the Flex Overview(link takes you to an external page) page.
  2. By selecting ' Login with Twilio ' on the default Flex login view.
Runtime Login View.

Option 1 will always log into Flex at flex.twilio.com. If you are self-hosting the Flex UI, this will not load your private destination.

Option 2 is available for self-hosted locations and for local development, such as logging into localhost when developing plugins.

(information)

Info

As mentioned in the FAQ for logging into a self-hosted domain, you must register your destination as a Trusted Domain(link takes you to an external page). Otherwise, both SSO login and the 'Login with Twilio' option will not work.

Loading the Flex login view

loading-the-flex-login-view page anchor

The login view only loads if you have not provided the sso attribute within your application configuration. If the sso attribute is provided (or you are using your flex.twilio.com Login Link(link takes you to an external page)), then you will bypass the login view and immediately trigger SSO login.

After logging out, users will always be sent to the Flex login view. You cannot use the afterLogout action to redirect to another page.

Can I use the SessionNotOnOrAfter attribute from my Identity Provider?

can-i-use-the-sessionnotonorafter-attribute-from-my-identity-provider page anchor

The SessionNotOnOrAfter attribute can be configured within your Identity Provider to ensure a maximum TTL (time-to-live) for an authenticated session. After the configured time, a user will be forced to authenticate within their Identity Provider in order to extend their session with connected applications.

We do not recommend using this attribute alongside Twilio Flex. When a user is logged into the Flex UI application, Flex will regularly refresh the user's Flex Token (the authenticated token which grants access to the UI). If the Identity Provider session expiration comes before the Flex Token's expected refresh period, Flex will be unable to refresh the user's session. Any active communications may be prematurely closed once the user's authentication expires, and the user will need to refresh the Flex application and re-authenticate through their Identity Provider.

If you choose to use SessionNotOnOrAfter, you must use a value greater than 1 hour (the default TTL of the user's authenticated Flex Token). We recommend setting this value above the shift time for an agent (e.g. 8-10 hours), otherwise the agent may be logged out of Flex unexpectedly. Even if you use a long TTL, the user may be impacted if they first login to Flex mid-way through their active authenticated session.


To help troubleshoot, install the SAML Tracer Chrome Extension(link takes you to an external page). This tool will parse SAML responses for easy review during troubleshooting.

Unable to log in to Flex due to incorrect SSO URL

unable-to-log-in-to-flex-due-to-incorrect-sso-url page anchor

The first time you try to log in to Flex through your newly configured SSO connection, you might encounter the following error message: "This XML file does not appear to have any style information associated with it. The document tree is shown below."

This error appears from your IdP when the single sign-on URL is not configured correctly. Your IdP provides your single sign-on URL, and you enter it on the Flex SSO configuration page. First, confirm that you entered the URL correctly in Flex. If so, search your IdP documentation to ensure you have located the correct URL for this field.

Attributes are not mapped to the TaskRouter Worker

attributes-are-not-mapped-to-the-taskrouter-worker page anchor

Each claim that you define in your Identity Provider should map to an attribute on the provisioned TaskRouter Worker. If an attribute is not appearing, this may be the result of a namespace that is being applied to your claims. You can identify this if the attribute name in the SAML is a URL schema. For example:


_10
<Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/email">
_10
<AttributeValue>jdoe@example.com</AttributeValue>
_10
</Attribute>

However the following attribute will be correctly interpreted by Flex:


_10
<Attribute Name="roles">
_10
<AttributeValue>wfo.full_access</AttributeValue>
_10
<AttributeValue>admin</AttributeValue>
_10
</Attribute>

Redirected to a Twilio Username / Password dialog box

redirected-to-a-twilio-username--password-dialog-box page anchor

This error typically occurs when the Claim Transformation was not properly set. The SAML response will show something like:


_10
</ds:X509Certificate>
_10
</ds:X509Data>
_10
</KeyInfo>
_10
</ds:Signature>
_10
<samlp:Status>
_10
<samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Requester">
_10
<samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:InvalidNameIDPolicy" />
_10
</samlp:StatusCode>
_10
</samlp:Status>
_10
</samlp:Response>

Note the InvalidNameIDPolicy Value in the Requester StatusCode.

If the SAML response looks valid, check that the Identity Provider Issuer field in the Flex SSO Console page(link takes you to an external page) is correct.

SAML response doesn't have a "role" attribute

saml-response-doesnt-have-a-role-attribute page anchor

This response is caused by the roles not being passed to the claims. Check your claims configuration and review the roles attribute.



Rate this page: