Configure Azure Active Directory with Flex
We recommend running Flex UI 0.7.0 or greater in order to follow this guide.
Have you already configured SSO using the preview.twilio.com endpoint? Learn how to update your existing configuration with the Flex SSO Migration Guide.
Create an application in the Azure Portal
In the Microsoft Azure Portal, 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.
After selecting the non-gallery option for your application's purpose, click Create.
Configure your application
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
| SAML Section | Field | Values |
| Basic SAML Configuration | Reply URL (Assertion Consumer Service URL) |
Replace |
| Basic SAML Configuration | Identifier (Entity ID) |
Replace |
| Attributes & Claims | Twilio Flex required claims | See Configure claims section. |
| SAML Signing Certificate | Signing Option | Select "Sign SAML response and assertion". |
| SAML Signing Certificate | Signing Algorithm | Leave "SHA-256" selected. |
| SAML Signing Certificate | Notification Email Addresses | Enter email address(es) for receiving Azure AD notifications. |
Configure claims
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.
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. Learn more about Twilio's Privacy policy.
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 Claim | Value |
|
|
|
| full_name |
|
| roles |
|
As of the time of writing, your Attributes & Claims setttings should look like the following:
Configure roles
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:
- select "+Create app role".
- Enter the required fields.
- Make sure to select "Users/Groups" as your allowed member type.
- Make sure enabling the app role checkbox is selected.
Click Apply. Your "App roles" page should look like this:
Note for Insights Users
You will need to create separate entries for each Insights role you expect to assign to your agents:
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).
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
Next, configure SSO on the Flex Console Single Sign-on settings page. You will need the following fields from the Azure AD Single sign-on page:
|
Twilio SSO Field |
Azure AD Setup Instructions Field |
|
X.509 Certificate |
Certificate (Base64) |
|
Identity Provider Issuer |
Azure AD Identifier |
|
Single Sign-on URL |
Login URL |
Ensure users in Directory are assigned to the application
Navigate back to your app overview page, then select Users and Groups from the left nav.
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 indvidual assignments for your agents.
Additional Configuration
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.
Test your SSO
Navigate to the Flex Console Single Sign-on settings page. You can click "Login with SSO", or copy the login link and paste it into your browser address bar, which will redirect you to the identity provider (IdP) login page.
Use the credential of the test user you created in the previous steps. Depending on the user settings, you may be requested to set your password. Once the authentication is completed, you will be redirected to the Flex UI. What you can see depends on the Flex role(s) set in the IdP user profile.
You can validate the worker full name display in the Flex UI, or navigate to the Worker page in the TaskRouter Dashboard to review other attributes such as email and assigned role(s).
Troubleshooting
To help troubleshoot, install the SAML Tracer Chrome Extension. This tool will parse SAML responses for easy review during troubleshooting.
Attributes are not mapped to the TaskRouter Worker
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:
<Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/email">
<AttributeValue>jdoe@example.com</AttributeValue>
</Attribute>However the following attribute will be correctly interpreted by Flex:
<Attribute Name="roles">
<AttributeValue>wfo.full_access</AttributeValue>
<AttributeValue>admin</AttributeValue>
</Attribute>Next steps
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?
We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.
