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?

Configuring Single Sign-on and Identity Provider integration

Twilio Flex integrates with your existing Identity Provider in order to authenticate users (agents, supervisors or administrators) and enable Single Sign-On. 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.


  • Identity Provider (IdP) is a trusted entity that lets you enable single sign-on (SSO) 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) - Twilio Flex in this context is the service provider configured as an Application on an Identity Provider to enable single sign-on.

Steps to configure your Identity Provider to support Twilio Flex.

In order to configure your Identity Provider to provide service to a Service Provider (in this case Flex), the integration has to be defined. Usually in Identity Provider terms it means we need to create an Application.

Configure Identity Provider

Please see below example setup with different Identity Providers.

Identity Attributes and Flex Roles

Your Identity Provider can provide any number of claims (key value pairs) to Flex. Only 4 of these are mandatory: Unique ID/User ID, list of Roles, Full Name and Email. (Unique ID is provided in the request header thus it is not needed to be explicitly set).

Everything provided from the Identity Provider is stored in the TaskRouter Worker Attributes. This allows you to easily adapt the Flex UI to details from your Identity Provider, as well as trigger certain behavior based on these values. Attributes are updated with every successful SSO authentication by merging attributes with existing ones.

The Attributes can be divided in 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 - WFO: These parameters are highly recommended if you are using the WFO capabilities of Flex (powered by Ytica).

Attribute conversion and data types

By default all attributes will be transformed as strings to TaskRouter attributes with the exception of roles attribute which defaults to stringarray (comma as separator).

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


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


Attribute Name Type Example Value
name.string String Mary Integer 1
sales.boolean Boolean true
languages.stringarray String Array en,de,fr
skills.intarray Integer Array 1,2,3,4

Incorrectly defining the attribute type and value (example defined as "a" or 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 Attribute

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 ( or to 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 dequeueing the call to an international number please ensure the destination country is enabled in Twilio Console > Programmable Voice > Calls and Geo Permissions.

Mandatory Attributes

Attribute Name Type Value / Example






Bob Bobson



Flex - Agent

Attribute Type Value / Example



Flex - WFO (powered by Ytica)

Attribute Type Value / Example











Adam Shepherd












Sales VIP





How does Twilio Manage Identities?

Each user that logs in to Twilio Flex via SAML Identity Provider will automatically become a Flex User.

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 Identity Provider-initiated login? (ex: Okta tile)

Yes. The SSO Configuration 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, then provide:

where dancing-owl-1234 is your account's Runtime Domain (found here). Otherwise, you would use your own self-hosted Flex URL.

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

Twilio console users (designated as admin role) will be able to test and validate the Agent Desktop by logging in through Twilio Console Flex section.

How do I login to a self-hosted domain?

For your security, all self-hosted domains must be whitelisted with Twilio to enable SSO login. These Trusted Domains can be provided alongside your SSO Configuration within the Twilio Console. The following patterns can be used when providing a Trusted Domain: allows but not allows but not
* allows or, but not or or ::1 allows the IP address

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

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.