Skip to contentSkip to navigationSkip to topbar
On this page

Configure Microsoft Entra ID with Flex



Create an application in the Entra admin center

create-an-application-in-the-entra-admin-center page anchor
  1. Open the Microsoft Entra admin center(link takes you to an external page).
  2. In the left navigation, click Applications, and then click Enterprise applications.
  3. Click New Application, and then click Create your own application.
  4. On the Create your own application page:
    1. Give your application a name.
    2. For the app's purpose, leave the Integrate any other application you don't find in the gallery (Non-gallery) option selected.
    3. Click Create.
application-creation.width-800.

Configure your application

configure-your-application page anchor
  1. From your application's overview page, in the left navigation, click Single sign-on.
  2. For the single sign-on method, click SAML.
  3. In each section, click Edit, and then enter the following settings.
SAML SectionFieldValues
Basic SAML ConfigurationReply URL (Assertion Consumer Service URL)Enhanced SSO configuration: Copy this value from the Set up your identity provider page, which provides the specific value for your account. Your value will look similar to this: https://login.flex.us1.twilio.com/login/callback?connection=JQxxxx

Legacy SSO configuration: Replace ACxxxx with your real Twilio Account SID. https://iam.twilio.com/v1/Accounts/ACxxxx/saml2
Basic SAML ConfigurationIdentifier (Entity ID)Enhanced SSO configuration: Copy this value from the Set up your identity provider page, which provides the specific value for your account. Your value will look similar to this: urn:flex:JQxxxx

Legacy SSO configuration: Replace ACxxxx with your real Twilio Account SID. After adding your unique entity ID, remove Microsoft's default entry. https://iam.twilio.com/v1/Accounts/ACxxxx/saml2/metadata
Attributes & ClaimsTwilio Flex required claimsSee Configure claims section.
SAML Signing CertificateSigning OptionSelect "Sign SAML response and assertion".
SAML Signing CertificateSigning AlgorithmLeave "SHA-256" selected.
SAML Signing CertificateNotification Email AddressesEnter email address(es) for receiving Entra ID notifications.

Claims are key-value pairs that the identity provider asserts are true to the application. Flex uses these to determine the critical information about each Flex User.

(warning)

Warning

All the information the identity provider supplies 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(link takes you to an external page).

  1. From the SAML-based Sign-on page, in the Attributes & Claims section, click Edit.
  2. Under Required claims, update the required claim to use user.mail as its value.
  3. Add the following claims using a user attribute in the Source attribute field. Don't set a namespace for any of the claims.
    Required claimValue
    emailuser.mail
    full_nameuser.displayname
    rolesuser.assignedroles
  4. Under Additional claims, remove the default additional claims.

Your Attributes & Claims settings should look similar to this:

Attributes & Claims.

Make sure that the Flex SAML roles have a globally unique identifier (GUID). GUIDs are a long string of letters and numbers that Entra ID can use to identify each Flex roles.

  1. From the admin center left navigation, click Applications, and then click App registrations.
  2. Under All registrations, click on your app (for example, Twilio Flex).
  3. From the app registrations page for your application, in the left navigation, click App roles.
    Twilio Flex requires the following roles:
    • admin
    • supervisor
    • agent

To create an app role:

  1. Click Create app role.
  2. Enter the required fields:
    1. Under Allowed member types, select Users/Groups.
    2. Leave the Do you want to enable this app role? box selected.
  3. Click Apply . Your App roles page should look similar to this:
    app-roles.

Note: If you use Flex Insights, you must create separate entries for each Insights role you expect to assign to your agents:

Add Azure Insights Roles.

(error)

Danger

All the information the identity provider supplies to Twilio is stored inside Twilio TaskRouter Worker attributes. Consider local regulations for storing data, and only provide data relevant for Flex usage (see the Twilio Privacy policy for more information).

(information)

Info

Please see the Identity Attributes section of the SSO Configuration docs for more information about naming attributes and other possible Worker attributes.


Configure Flex with your new SAML credentials

configure-flex-with-your-new-saml-credentials page anchor
  1. From Flex Console, configure SSO on the Single sign-on (SSO) page(link takes you to an external page). You will need the following fields from the Entra SAML-based Sign-on page:
Twilio SSO fieldEntra ID field
X.509 CertificateCertificate (Base64)
Identity Provider IssuerMicrosoft Entra Identifier
Single Sign-on URLLogin URL

Ensure users in the directory are assigned to the application

ensure-users-in-the-directory-are-assigned-to-the-application page anchor
  1. Return to the admin center home page, and then go to your appliation's overview page.
  2. From the left navigation, click Users and Groups .
    azure-users.
  3. Click Add user/group. You can assign one role to each user. Make sure that all users are assigned to your application.

Note: If you use Flex Insights, you must add each role you created previously as individual assignments for your agents.

Azure Flex Insights App Roles.


Additional Configuration

additional-configuration page anchor

See Configuring SSO for more details about the following topics:

  • Initiating login from your identity provider
  • Logging in to a self-hosted domain
  • Attributes you can define for each identity

To test your SSO setup:

  1. Navigate to the Flex Console Single sign-on (SSO) page(link takes you to an external page).
  2. Do one of the following:
    • Click Login with SSO.
    • Copy the login link and paste it into your browser address bar. This redirects you to the IdP login page.
  3. Log in using the credentials of the test user. Depending on the user settings, the IdP may ask you to set your password.

    Once authentication completes, the IdP redirects you to the Flex UI. What you can see in the UI depends on the Flex roles set in the IdP user profile.
  4. Validate the worker full name display in the Flex UI, or navigate to the Worker page in the TaskRouter Dashboard(link takes you to an external page) to review other attributes, like email and assigned roles.

If you need to pass custom attributes to your Flex users, refer to Pass Custom Azure AD Attributes as Twilio Flex SAML Claims.