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.

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.

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

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:

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:

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.