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 Aware
is 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.,
Twilio Flex
). - 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:
https://iam.twilio.com/v1/Accounts/ACXXXXX/saml2
- Replace
ACXXXXX
with your Account SID.
- On the next step, enter
https://iam.twilio.com/v1/Accounts/ACXXXXX/saml2/metadata
as the relying party trust identifier and click Add. - Be sure to also replace
ACXXXXX
with 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
LDAP Attributes
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 |
E-Mail-Addresses | E-Mail Address |
E-Mail-Addresses | |
Display-Name | full_name |
Department | roles |
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:
Field | Value |
Claim rule name | Name ID |
Incoming claim type | E-Mail Address |
Outgoing claim type | Name ID |
Outgoing name ID format |
Finally, select Pass through all claim values
, and then Finish configuring the rule.
Powershell
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 MessageAndAssertion
.
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: https://localhost/FederationMetadata/2007-06/FederationMetadata.xml
Note the EntityID attribute; this should be your Identity Provider URL.
Twilio Configuration
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:
Field | Value |
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., http://<FQDN>/adfs/services/trust |
Single Sign-On URL | https://<FQDN>/adfs/ls |
Default Redirect URL | https://flex.twilio.com/<function-domain> . Your domain can be found in the Twilio Console in Functions, Assets, and other parts of Twilio Serverless. It will be in the format of random-noun-1234 . |
Twilio SSO Url | Select Uses iam.twilio.com |
Login using popup | This is optional. Your SSO integration should work with or without this enabled. |
Testing
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.
After clicking Sign In
, you should be redirected to Flex!
Troubleshooting
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>
Note the 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.