Menu

Configure Azure Active Directory with Flex

Have you already configured SSO using the preview.twilio.com endpoint? Learn how to update your existing configuration with the Flex SSO Migration Guide.

Step One: Create an application

In the Microsoft Azure Portal select Azure Active Directory followed by Enterprise Applications.

Azure Setup 1

Select Create New Application and choose Non-Gallery Application and give your Application a name.

Azure setup 2

Step Two: Configure your application

Select Single sign-on from the Application menu and pick SAML as the sign-on method.

Azure setup 3

Select Basic SAML Configuration.

Azure setup 4

Edit Settings as follows.

  • Set your Entity ID to https://iam.twilio.com/v1/Accounts/ACxxxx/saml2/metadata. Replace ACxxxx with your real Account SID.
  • Set your Reply URL to https://iam.twilio.com/v1/Accounts/ACxxxx/saml2. Replace ACxxxx with your real Account SID

Microsoft Flex SSO (IAM v1)

Under point 3 - SAML Signing Certificate click edit and change Signing Option to Sign both Response and Assertion.

Azure setup 9

Step Three: Configure roles

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.

Start by ensuring 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. You'll want to use a GUID Generator to generate GUIDs for the Flex SAML app roles.

In Azure Active Directory go to App Registrations and click into the Flex SAML app.

You may find it helpful to download the Manifest and edit it, then upload the updated one. You can also copy the edited JSON into the manifest editor, replacing the original version.

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)

In the Manifest, the default role's isEnabled property must be set to false, like so:

{
  "allowedMemberTypes": [
    "User"
  ],
  "description": "User",
  "displayName": "User",
  "id": <GUID>,
  "isEnabled": false,
  "lang": null,
  "origin": "Application",
  "value": null
}

Add the Flex-specific app roles like so:

{
  "allowedMemberTypes": [
    "User"
  ],
  "description": "Agent",
  "displayName": "agent",
  "id": <GUID>,
  "isEnabled": true,
  "lang": null,
  "origin": "Application",
  "value": "agent"
},
{
  "allowedMemberTypes": [
    "User"
  ],
  "description": "Supervisor",
  "displayName": "supervisor",
  "id": <GUID>,
  "isEnabled": true,
  "lang": null,
  "origin": "Application",
  "value": "supervisor"
},
{
  "allowedMemberTypes": [
    "User"
  ],
  "description": "Admin",
  "displayName": "admin",
  "id": <GUID>,
  "isEnabled": true,
  "lang": null,
  "origin": "Application",
  "value": "admin"
}

Save the changes.

Step Four: Configure Claims

From the Enterprise Applications section of the Azure website, click into the Flex SAML app and visit the Single Sign-On Section -> User Attributes & Claims

Add a new claim.

Azure setup 6

  • In the above example, Azure passes to Flex the following attributes (full_name, email, and roles). These are the minimum attributes Flex requires.
  • Directory attribute user.employeeid will be used as the unique Flex user identifier.
  • We are also setting roles=agent for all users here but if you've configured the roles GUIDs, you can simply assign the role property with the key user.assignedroles
  • Please ensure that you do not set any Namespace with these attributes.
  • Flex will merge update the Worker attributes with each successful SSO authentication.

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

Step Five: Save Application information and copy Application details.

Azure setup 7

  1. Download the BASE64 Certificate - this will be added to Twilio Flex Console as X.509 CERTIFICATE
  2. Make a note of the Login URL - this is the SINGLE SIGN-ON URL in Flex Console.
  3. And Azure AD identifier - this is the IDENTITY PROVIDER ISSUER in Flex Console.

Step Six: Ensure Users in Directory are assigned to the Application.

Azure setup 7

Inside the Flex Saml App configuration go to Users and Groups -> Add user. As you add/edit users, you can assign a single role, or add multiple roles based on the earlier role GUIDs you created.

Please ensure that you have users assigned to your Application.

Step Seven: Configure Flex with your new SAML credentials

Screen Shot 2019-10-31 at 5.26.49 PM.png

Using the details gathered in Step Four, save your SSO configuration on the Flex Console Single Sign-on settings page. Make sure you check the USES IAM.TWILIO.COM radio button. To learn more about migrating from the preview.twilio.com URL to iam.twilio.com see our migration guide.

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.

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>
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?

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.