Menu

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

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.

Add RPT Step 2

In the next step, select Enter data about the relying party manually.

Add RPT Step 3

Provide a display name (e.g., Twilio Flex).

Add RPT Step 4

There's no need to specify a certificate, so you can skip to configuring your URL. Check Enable support for SAML 2.0 WebSSO protocol. The Relying party SAML 2.0 SSO Service URL should contain:

https://iam.twilio.com/v1/Accounts/ACXXXXXXXXXXXX/saml2

Replace AC with your AccountSID.

Add RPT Step 6 (Five skipped for simplicity)

Enter https://iam.twilio.com/v1/Accounts/ACXXXXXXXXXXXX/saml2/metadata as the relying party trust identifier and click add. Be sure to replace ACXXX with your AccountSID.

002 Add RPT Step 7
Continue on and permit everyone for the Access Control Policy

Add RPT Step 8

And click next to add the Trust

Add RPT Step 9

Finally, click Close to finish setting up the Trust.

Add RPT Step 10

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 Outgoign 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 Outgoign 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. Our team 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/<runtime-domain>. Your runtime domain can be found in the Twilio Console in Functions, Assets, and other parts of the Twilio Runtime. 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/<runtime-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 browsing the Twilio tag on Stack Overflow.