Federating Amazon Connect with Azure AD

Naturally with any large organisation, they’re only going to be interested in your software if you make it easy for them to integrate it into their workflows. To that end, let’s have a look at how we get an Amazon Connect CCP working with Azure as an IdP.

Set Up your Amazon Connect Instance

The first step is to set up your Connect instance to use SAML. This is set when creating a new instance and cannot be changed later, so make sure you do this correctly first go

Do the rest of your set up as normal.

Set up your Azure AD Application

I’m using the free tier with my default directory because I’m a cheapskate, so there may be better options than what I’m about to do. This should work, though.

Click onto Enterprise Applications in the left hand panel

Click New Application

Give it a reasonable name and click the radio button that says Integrate any other application you don't find in the gallery

Click the Set up Single Sign On button and select the SAML option on the next page

We’re going to want to hit the Edit button in Basic configuration and set the following values:

• Identifier set to urn:amazon:webservices
• Reply URL set to https://signin.aws.amazon.com/saml
• Relay State set to https://ap-southeast-2.console.aws.amazon.com/connect/federate/INSTANCE_ID?destination=%2Fconnect%2Fccp-v2 where INSTANCE_ID is the Connect instance ID, found in the Instance ARN arn:aws:connect:REGION:ACCOUNT_ID:instance/INSTANCE_ID

Click on the edit button for the SAML Signing Certificate section, click New Certificate, then click save

In SSO settings screen, download the provider data XML

Set up AWS IdP and Roles

Put your AWS hat back on and head to IAM. Click Identity Providers and then the Create Provider button

Select SAML from the type dropdown and upload the metadata file

Next, still in IAM, click Roles on the left hand side and create yourself a new role

Select SAML as the type of trusted entity, and select the IdP you just created

You’ll need to create a new policy which allows the role to federate with the Connect instance. You can enable this by granting connect:GetFederationToken permission and restricting it to the username that’s trying to log in.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "connect:GetFederationToken",
            "Resource": "arn:aws:connect:ap-southeast-2:${ACCOUNT_ID}:instance/${INSTANCE_ID}/user/${aws:userid}"
        }
    ]
}

Attach this to the IdP role above either in the create role console or manually in the edit screen.

Note down the ARNs for both the identity provider and role before switching back to Azure and clicking the Edit button for the application attributes

Add two new claims:

• https://aws.amazon.com/SAML/Attributes/Role will be set to your AWS identity provider ARN, followed by a comma, followed by the AWS role ARN, eg arn:aws:iam::ACCOUNT_ID:saml-provider/AzureIdP,arn:aws:iam::ACCOUNT_ID:role/azure-federation
• https://aws.amazon.com/SAML/Attributes/RoleSessionName should be set to user.userprincipalname

Go back to the Azure application Properties screen, and note down the User access URL

There, we’re federated!

There’s one more step until you can get the CCP up, and that’s adding our user into Connect. Go through the normal process and create a user with the AD user’s email address

After this, you should be able to navigate to your Azure access URL (I’d recommend in an incognito window, it steals your AWS session) and log in properly. If you’re lucky, you should see something like this

That’s all for now. This took me two days to work out, so if I can save someone a bit of grief I’ll be happy. A quick summary of gotchas:

• A SAML Connect login will steal your AWS session, so use another profile or private window when logging in
• Azure AD will only allow you to have a single urn:amazon:webservices audience per directory. You can remedy this by passing in an audience=urn:amazon:webservices as a query parameter in the access URL
• Users must be present in Connect, otherwise they will not be able to access the CCP
• If you’re using the CCP in an iframe, you’ll need to switch to open a modal first, because of the X-Frame-Options header being set to sameorigin. Thanks Microsoft, I hate it
• I was able to also federate a Cognito user pool on top of this. You can follow this tutorial to get that sorted