Enabling Federation to AWS Using Windows Active Directory, ADFS, and SAML 2.0 With Amazon Connect

Swwapnil Pawar
10 min readNov 28, 2019

--

AWS Blog

To download ADFS, go to https://www.microsoft.com/en-in/download/details.aspx?id=10909 and Install it.

Configuring ADFS

The next step is to configure ADFS. You can get to the window from Start > All Programs > Administration Tools > AD FS 2.0 Management (Similar procedure with ADFS 3.0). When ADFS is launched, it looks like this:

AWS Blog

To launch the configuration wizard, you click AD FS 2.0 Federation Server Configuration Wizard. If you want to follow along with my configuration, do this:

  1. Select Create a new Federation Service.
AWS Blog

2. Select the New Standalone federation server farm.

3. Select an SSL certificate. In my instance, I had an existing certificate I could use. If you don’t have a certificate, you can create a self-signed certificate using IIS. Self-signed certificates are convenient for testing and development. For production use, you’ll want to use a certificate from a trusted certificate authority (CA).

4. Check the service account, click next. I just need to confirm your settings and click Next.

6. Nothing left but to click Close to finish.

After you finish installing, you will see the list of metadata, services enabled in the federation server.

In the end, you will see the metadata section where you can consume the URL for further processing.

If all goes well you get a report with all successful configurations. If so, skip ahead to the Configuring AWS section.

— — — — — — — — — — — — — — — — — — — — — — — — — — — — — — —

The first step is to create a SAML provider. If you’ve never done this, I recommend taking a look at the IAM user guide.

Before you create a SAML provider, you need to download the SAML metadata document for your ADFS federation server. By default, you can download it from the following address:

https://<yourservername>/FederationMetadata/2007–06/FederationMetadata.xml

Go to AWS IAM documentation, to know how to configure Identity providers using SAML.

Check step 1 at Configure SAML.

Check step 2 at Configure SAML — Create an IAM role for SAML 2.0 federation with the AWS Management Console. For more information, see Creating a Role for SAML 2.0 Federation (Console).

Once you are done with the configuration, Find the ARNs for the SAML provider and for the roles that you created and record them. You’ll need the ARNs later when you configure claims in the IdP.

That’s it for the AWS configuration steps.

— — — — — — — — — — — — — — — — — — — — — — — — — — — — — — —

Configuring AWS as a Trusted Relying Party

Federation using SAML requires setting up a two-way trust. In the preceding section, I created a SAML provider and some IAM roles. This is one half of the trust relationship, where the ADFS server is trusted as an identity provider. Similarly, ADFS has to be configured to trust AWS as a relying party. I configured this by returning to the AD FS Management Console. To recreate my setup, perform the following:

1. From the ADFS Management Console, right-click ADFS 2.0 and select Add Relying Party Trust.

2. In the Add Relying Party Trust Wizard, click Start.

3. Check Import data about the relying party published online or on a local network, type https://signin.aws.amazon.com/static/saml-metadata.xml, and then click Next. The metadata XML file is a standard SAML metadata document that describes AWS as a relying party.

AWS Blog

4. Set the display name for the relying party and then click Next.

AWS Blog

5. Choose your authorization rules. For my scenario, I chose Permit all users to access this relying party. When you’re done, click Next.

AWS Blog

6. Review your settings and then click Next.

AWS Blog

7. Check Open the Edit Claim Rules dialog for this relying party trust when the wizard closes and then click Close.

You’re done configuring AWS as a relying party.

— — — — — — — — — — — — — — — — — — — — — — — — — — — — — — —

Configuring Claim Rules for the AWS Relying Party

Right-click on the relying party (in this case Amazon Web Services) and then click Edit Claim Rules:

AWS Blog

You need to click on “Add Rule”.

Here are the steps used to create the claim rules for NameId, RoleSessionName, GroupMembership, Roles & Session Duration.

Adding NameId:

  1. In the Edit Claim Rules for <relying party> dialog box, click the Add Rule.

2. Select Transform an Incoming Claim and then click Next.

3. Use the following settings:

a. Claim rule name: NameId

b. Incoming claim type: Windows Account Name

c. Outgoing claim type: Name ID

d. Outgoing name ID format: Persistent Identifier

e. Pass through all claim values: checked

4. Click Finish.

Adding a RoleSessionName

1. Click Add Rule

2. In the Claim rule template list, select Send LDAP Attributes as Claims.

3. Use the following settings:

a. Claim rule name: RoleSessionName

b. Attribute store: Active Directory

c. LDAP Attribute: E-Mail-Addresses

d. Outgoing Claim Type: https://aws.amazon.com/SAML/Attributes/RoleSessionName

4. Click Finish

Adding Role Attributes

Unlike the two previous claims, here I used custom rules to send role attributes. This is done by retrieving all the authenticated user’s AD groups and then matching the groups that start with to IAM roles of a similar name. I used the names of these groups to create Amazon Resource Names (ARNs) of IAM roles in my AWS account (i.e., those that start with AWS-).

We want to take the Group Membership of the person who has authenticated and match it to a role in AWS. Example the AD Group named “theITHollow-Admins” will map to the AWS role “theITHollowAdmins”.

Sending role attributes required two custom rules. The first rule retrieves all the authenticated user’s AD group memberships and the second rule performs the transformation to the roles claim. Here’s how I did it.

Ref Link: http://www.molikop.com/2014/04/adfs-claim-rules-filtering-groups/

Click Add Rule:

2. In the Claim rule template list, select Send Claims Using a Custom Rule and then click Next.

This custom rule uses a script in the claim rule language that retrieves all the groups the authenticated user is a member of and places them into a temporary claim named http://theITHollow/groups. (Think of this as a variable you can access later.) I use this in the next rule to transform the groups into IAM role ARNs.

4. Click OK.

5. Click Add Rule.

6. Repeat the preceding steps, but this time, type Roles for Claim rule name and use the following script:

This rule uses a custom script to get all the groups from the temporary claim () and then uses the name of the group to create the principal/role pair, which has this format:

ARN of SAML provider,ARN of role to assume

In my example, it comes out this way:

arn:aws:iam:261633966051:saml-provider/adfs,arn:aws:iam:261633966051:role/theITHollow

In the example, I used an account number of 261633966051. Make sure you change this to your own AWS account.

7. Click OK.

Adjusting Session Duration:

By default, the temporary credentials that are issued by AWS IAM for SAML federation are valid for an hour. Depending on your organization’s security stance, you may wish to adjust. You can allow your federated users to work in the AWS Management Console for up to 12 hours. This can be accomplished by adding another claim rule in your ADFS configuration. To add the rule, do the following:

1. Access ADFS Management Tool on your ADFS Server.

2. Choose Relying Party Trusts, then select your AWS Relying Party configuration.

3. Choose Edit Claim Rules.

4. Choose Add Rule to configure a new rule, and then choose Send claims using a custom rule. Finally, choose Next.

5. Name your Rule “Session Duration” and add the following rule syntax.

6. Adjust the value of 28800 seconds (8 hours) as appropriate.

Rule language:

=> issue(Type = “https://aws.amazon.com/SAML/Attributes/SessionDuration", Value = “28800”);

Once you’ve run that you can go to your ADFS portal and try to log in. Go to

  1. https://[YOURADFSSERVERNAME.DOMAIN.NAME]/adfs/ls/IdpInitiatedSignOn.aspx
  2. Select Sign in to one of the following sites, select Amazon Web Services from the list, and then click Continue to Sign In.
  3. If you are mapped to only a single IAM role, you skip the role selection step and are automatically signed in to the AWS Management Console.

— — — — — — — — — — — — — — — — — — — — — — — — — — — — — — -

Now, if you want to Use SAML to Automatically Direct Federated Users to a Specific AWS Management Console Page.

Configure the relay state of your identity provider to point to your Amazon Connect instance. The URL to use for the relay state is comprised as follows:

https://region-id.console.aws.amazon.com/connect/federate/instance-id

Replace the region-id with the Region name where you created your Amazon Connect instance, such as us-east-1 for US East (N. Virginia). Replace the instance-id with the instance ID for your instance.

See Point №5 at Configure SAML.

— — — — — — — — — — — — — — — — — — — — — — — — — — — — — — —

Enabling RelayState

Before you continue, verify that your ADFS supports the RelayState parameter, and then enable it. This parameter was introduced in Update Rollup 2 for ADFS 2.0. This parameter is supported in ADFS 3.0, but it is not enabled by default.

Check For More Details: ADFSEnableRelayState

Below parameters are required to configure the relay parameter:

IDP URL String = https://ADFSSERVER/adfs/ls/idpinitiatedsignon.aspx

Relying Party Identifier = urn:amazon:webservices

Relay State/Target App = https://region-id.console.aws.amazon.com/connect/federate/instance-id

Checkout the Link to generate the ADFS Relaystate URL: https://jackstromberg.com/adfs-relay-state-generator/

— — — — — — — — — — — — — — — — — — — — — — — — — — — — — —TroubleShooting:

There are chances that you will encounter an error:

Error: Your Request Included an Invalid SAML Response. To Logout, Click Here.

https://docs.aws.amazon.com/IAM/latest/UserGuide/troubleshoot_saml.html#troubleshoot_saml_invalid-response

You need to check the valid SAML response to see the SAML assertion values.

https://docs.aws.amazon.com/IAM/latest/UserGuide/troubleshoot_saml_view-saml-response.html

You will find the steps to decode the SAML response. Once you decode it, You will get an XML response.

The next step is to analyze & check the Required values from SAML Assertion documentation is present in your XML.

Check out more about it Configuring SAML Assertions for authenticating a response.

— — — — — — — — — — — — — — — — — — — — — — — — — — — — — — —

If you don’t see anyone of the SAML Assertions value in the SAML response XML (Decoded) file, then you need to check below Steps:

Go to ADFS user management on the windows server instance,

  1. If you have an existing user-created using which you’re trying to connect to the amazon connect to the instance, then right-click on <user-name> ⇒ Properties
  2. Once you open properties, you will see a tab called “MemberOf”.
  3. Now, If you go back to our Claims Rule page, We are mapping ADFS group name with the AWs role name, so in order to work,
  4. First, you need to create a group named “” and then add a user to the group “theITHollow-admin”.
  5. Also, check if you have added email to the user profile, if its empty, it will throw an error because we are mapping Email-address to the RoleSessionName saml assertions rule.
  6. Once done, Now you can hit the relaystate URL from the browser and it will successfully redirect you to the amazon connect page.
  7. Any users with membership in the Active Directory security group will now be able to authenticate to AWS using their Active Directory credentials and assume the matching AWS role.

--

--

Swwapnil Pawar

Entrepreneur, Cloud Evangelist, AWS/Google Certified Architect, Building Cool Things With Serverless. Avid Reader