Configure Microsoft ADFS with Flex
Microsoft Active Directory Federation Services (ADFS) is a software component developed by Microsoft that can run on Windows Server operating systems. It provides users with single sign-on access to systems and applications located across organizational boundaries
This guide will walk through the steps to configure ADFS as the Identity Provider (IdP) for Twilio Flex, and assumes that you've already deployed your ADFS server role. You can learn more about deploying an ADFS server farm in the Microsoft Documentation.
This guide was written using ADFS for Server 2019. While we anticipate that these steps will be relatively stable between versions, if you run into any issues, feel free to let your Twilio team know using the feedback widget in the top right corner of the page.
Running the ADFS Configuration Wizard
If ADFS has never been configured on this server, the configuration wizard may need to be run. These settings are not specific to Twilio.
1. Assuming you have no servers, you'll want to creat the first federation server in a federation server farm.
2. In the next step, you'll need to specifiy which account should be used during the server configuration.
3. Next you'll need to specify the properties of the Service. Since users will see the display name on sign-in, you may want to use this to brand your contact center for agents, and other people logging in to your Flex contact center.
4. Specify the domain user account of your choosing.
5. Finally, specify or create a database.
All of your prerequisite checks should pass successfully. Once they do, click "Configure" to complete the installation.
Configuring the Relying Party Trust
- In the ADFS interface, add a Relying Party Trust.
- Make sure that
Claim Awareis selected on the Welcome screen, and then click Start.
- In the next step, select
Enter data about the relying party manually.
- Provide a display name (e.g.,
- There's no need to specify a certificate, so you can skip to configuring your URL:
- Check "Enable support for the SAML 2.0 WebSSO protocol".
- The Relying party SAML 2.0 SSO Service URL should contain:
ACXXXXXwith your Account SID.
- On the next step, enter
https://iam.twilio.com/v1/Accounts/ACXXXXX/saml2/metadataas the relying party trust identifier and click Add.
- Be sure to also replace
ACXXXXXwith your Account SID.
- Continue on and select "Permit everyone" for the Access Control Policy.
- Click Next to add the Trust.
- Finally, on the Finish screen, check "Configure claims issuance policy for this application". Click Close to finish setting up the Trust.
Editing the Claims Issuance Policy/Claim Rules
In the Actions pane, choose to Edit the Claim Issuance Policy. In the window that pops up, add a new Rule.
For Claim rule template, select Send LDAP Attributes as Claims. Then click Next.
The Configure Rule page appears.
Provide a claim name.
Roles are set by adding: “agent or admin” to the Department of the user profile.
|LDAP Attribute||Outgoing Claim Type|
If the Department field is already in use, Group assignment can also be used for passing roles. This configuration would use Token-Groups instead of Department, like so
|LDAP Attribute||Outgoing Claim Type|
|Token-Groups - Unqualified Names||roles|
These are the mandatory Flex fields, but you can visit the Flex SSO configuration docs to see a complete list of possible fields that can be added.
Click the Finish button when you're done, and add another rule.
Transforming Incoming Claims
For this rule, select
Transform an Incoming Claim.
Configure the claim rule like so:
|Claim rule name||Name ID|
|Incoming claim type||E-Mail Address|
|Outgoing claim type||Name ID|
|Outgoing name ID format|
Pass through all claim values, and then Finish configuring the rule.
By default, only the assertion is signed, but in order for the integration to work, the assertion and the message need to be signed. This setting can be configured via Powershell.
In all commands, replace the
ACXXX with your account SID.
In the Administrator Powershell, run the following command:
Set-AdfsRelyingPartyTrust -TargetIdentifier https://iam.twilio.com/v1/Accounts/ACXXXXXX/saml2/metadata -SamlResponseSignature MessageAndAssertion
You can verify the configuration using the following command:
Get-AdfsRelyingPartyTrust -Identifier https://iam.twilio.com/v1/Accounts/ACXXXXX/saml2/metadata
The SamlResponseSignature will be set to
Gather Data from ADFS
Get your ADFS Certificate
Now you'll need to get some data from ADFS that you'll use to configure the Twilio side of the IdP integration.
First, go to Service -> Certificates and right click on the
Token-signing certificate. View the certificate. In the Details tab, click
Copy to File. Export as
Base-64 encoded X.509 (.CER). Provide a name and select a place to export this. You'll need to copy the contents of the certificate, so make sure you can find it for the next steps!
Capture the Identity Provider URL
By default, your Identity Provider URL should look like
http://<FQDN>/adfs/services/trust, where FQDN is the Fully Qualified Domain Name associated with your account.
To validate this, open the following XML file from the ADFS server:
Note the EntityID attribute; this should be your Identity Provider URL.
Now you're ready to configure Twilio to log people in to Flex using ADFS. Log into the Twilio Console and navigate to the Flex -> Single Sign On page.
Fill in the form as follows:
|Friendly Name||A name of your choice (e.g., ADFS)|
|X.509 Certificate||Copy and paste the contents of the X.509 certificate you opened earlier using a tool like Notepad. This should be a long string of text.|
|Identity Provider Issuer||The Identity Provider URL you received earlier, e.g.,
|Single Sign-On URL||
|Default Redirect URL||
|Twilio SSO Url||Select
|Login using popup||This is optional. Your SSO integration should work with or without this enabled.|
If everything was set up properly, you can now navigate to
flex.twilio.com/<function-domain>, and you'll be redirected to the ADFS sign-in page.
Sign In, you should be redirected to Flex!
To help troubleshoot, install the SAML Tracer Chrome Extension. This tool will parse SAML responses for easy review during troubleshooting.
Redirected to a Twilio Username / Password dialog box
This error typically occurs when the Claim Transformation was not properly set. The SAML response will show something like:
</ds:X509Certificate> </ds:X509Data> </KeyInfo> </ds:Signature> <samlp:Status> <samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Requester"> <samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:InvalidNameIDPolicy" /> </samlp:StatusCode> </samlp:Status> </samlp:Response>
InvalidNameIDPolicy Value in the Requester StatusCode.
If the SAML response looks valid, check that the Identity Provider Issuer field in the Flex SSO Console page is correct.
SAML response doesn't have a "role" attribute
This response is caused by the roles not being passed to the claims. Check your claims configuration in ADFS and review the roles attribute.
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.