Menu

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.

ADFS Wizard Step 1

2. In the next step, you'll need to specifiy which account should be used during the server configuration.

ADFS Wizard Step 2

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.

ADFS  Wizard Step 3

4. Specify the domain user account of your choosing.

ADFS Wizard Step 4

5. Finally, specify or create a database.

ADFS Wizard Step 5

All of your prerequisite checks should pass successfully. Once they do, click "Configure" to complete the installation.

ADFS Wizard Step 6

Configuring the Relying Party Trust

  • In the ADFS interface, add a Relying Party Trust.

Add RPT 1

  • 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.

Claims Issuance Step 1

For Claim rule template, select Send LDAP Attributes as Claims. Then click Next.

Claims Issuance Step 2

The Configure Rule page appears.

Claims Issuance Step 3

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 email
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.

Transform Incoming Claim Step 1

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 Email

Transform Incoming Claim Step 2

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!

ADFS Certificate Details Tab

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

ADFS XML Entity ID

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.

Twilio Flex SSO 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.

Rate this page:

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.

Thank you for your feedback!

Please select the reason(s) for your feedback. The additional information you provide helps us improve our documentation:

Sending your feedback...
🎉 Thank you for your feedback!
Something went wrong. Please try again.

Thanks for your feedback!

thanks-feedback-gif