Skip to contentSkip to navigationSkip to topbar
On this page

Configure Azure Active Directory with Flex



Create an application in the Azure Portal

create-an-application-in-the-azure-portal page anchor

In the Microsoft Azure Portal(link takes you to an external page), search for Azure Active Directory then select Enterprise Applications from the left nav. Select + New Application > Create your own application and give your application a name.

application-creation.width-800.

After selecting the non-gallery option for your application's purpose, click Create.


Configure your application

configure-your-application page anchor

Select Single sign-on from the left nav and pick SAML as the sign-on method.

Pick your SAML section, click Edit and enter the following settings:

General SAML Settings

general-saml-settings page anchor
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 Azure AD 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).

From your application overview page (Enterprise applications > Twilio Flex in this example), click Single sign-on -> Attributes & Claims.

First, update the required claim to use user.mail as its value. Remove the default additional claims.

Next, add the following claims using a user attribute as the "Source attribute". Do not set a namespace for any of the claims.

Required ClaimValue
emailuser.mail
full_nameuser.displayname
rolesuser.assignedroles

As of the time of writing, your Attributes & Claims settings should look like the following:

Attributes & Claims.

Ensure that the Flex SAML roles have a Globally Unique Identifier (GUID). GUIDs are a long string of letters and numbers that Azure will use to identify each of the Flex roles.

Navigate to Azure Active Directory > App Registrations > All applications. Click on your app ("Twilio Flex" in this example) and select App roles from the left nav. Twilio Flex requires the following roles:

  • admin
  • supervisor
  • agent

To create an app role in Azure:

  1. Select "+Create app role".
  2. Enter the required fields.
  3. Make sure to select "Users/Groups" as your allowed member type.
  4. Make sure enabling the app role checkbox is selected.

Click Apply. Your "App roles" page should look like this:

app-roles.

Note for Insights Users

You will need to create separate entries for each Insights role you expect to assign to your agents:

Add Azure Insights Roles.
(error)

Danger

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 (further information about Twilio Privacy policy).

(information)

Info

Please see the Identity Attributes section of the SSO Configuration docs for further 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

Next, configure SSO on the Flex Console Single Sign-on settings page(link takes you to an external page). You will need the following fields from the Azure AD Single sign-on page:

Twilio SSO FieldAzure AD Setup Instructions Field
X.509 CertificateCertificate (Base64)
Identity Provider IssuerAzure AD Identifier
Single Sign-on URLLogin URL
azure-sso-twilio-console.

Ensure users in Directory are assigned to the application

ensure-users-in-directory-are-assigned-to-the-application page anchor

Navigate back to your app overview page, then select Users and Groups from the left nav.

azure-users.

As you add/edit users, you can assign a single role. Please ensure that you have users assigned to your application.

Note for Insights Users

You will need to add each role you created previously as individual assignments for your agents.

Azure Flex Insights App Roles.

Additional Configuration

additional-configuration page anchor

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.


To test your SSO setup:

  1. Navigate to the Flex Console Single Sign-on 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're looking to pass custom attributes to your Flex users, refer to Pass Custom Azure AD Attributes as Twilio Flex SAML Claims.

Need some help?

Terms of service

Copyright © 2024 Twilio Inc.