Enabling Federation to AWS Using Windows Active Directory, ADFS and SAML

Posted in AWS Blog
24/11/2015 Pauwel Rummens

Enabling Federation to AWS Using Windows Active Directory, ADFS and SAML


Jeff Wierer has written this documentation in Oktober 2014. This is a 2015 update containing windows server 2012R2 and ADFS 3.x

AWS added support for SAML, an open standard used by many identity providers. This new feature enables federated single sign-on (SSO), which lets users sign into the AWS Management Console or make programmatic calls to AWS APIs by using assertions from a SAML-compliant identity provider (IdP) like ADFS.

Many of you are using Windows AD for your corporate directory and since Windows Server includes ADFS, it makes sense that you might use ADFS as your IdP.
To set up my domain, I used Amazon EC2 because that made it easy to access the domain from anywhere.
My EC2 instance used Windows Server 2012 R2 running, AD, and ADFS. (Remember that the IIS dependency was removed in ADFS 2012 R2.)

If you want to do the same, I encourage you to use a nifty CloudFormation template that creates a Windows instance and sets up a domain for you.


How Integration Between AD FS and AWS Works

Before we get too far into the configuration details, let’s walk through how this all works.

  1. The flow is initiated when a user (let’s call him Bob) browses to the ADFS sample site () inside his domain. When you install ADFS, you get a new virtual directory named adfs for your default website, which includes this page
  2. The sign-on page authenticates Bob against AD. Depending on the browser Bob is using, he might be prompted for his AD username and password.
  3. Bob’s browser receives a SAML assertion in the form of an authentication response from ADFS.
  4. Bob’s browser posts the SAML assertion to the AWS sign-in endpoint for SAML (https://signin.aws.amazon.com/saml). Behind the scenes, sign-in uses the AssumeRoleWithSAML API to request temporary security credentials and then constructs a sign-in URL for the AWS Management Console.
  5. Bob’s browser receives the sign-in URL and is redirected to the console.

From Bob’s perspective, the process happens transparently. He starts at an internal web site and ends up at the AWS Management Console, without ever having to supply any AWS credentials.
Now that we understand how it works, let’s take a look at setting it all up.
BTW this post is fairly long. The next couple sections cover installing and configuring ADFS.

If you already have ADFS in your environment, you may want to skip ahead to the Configuring AWS section.


Configuring Active Directory

If you want follow along with my description, you’re going to need a Windows domain.
If you don’t already have one, I recommend that you take advantage of the CloudFormation template I mentioned earlier to quickly launch an Amazon EC2 Windows instance as a Windows AD domain controller.

For demonstration purposes, I used a single user (Bob) who is a member of two AD groups (AWS-Production and AWS-Dev) and a service account (ADFSSVC) used by ADFS. Note that the names of the AD groups both start with AWS-. This is significant, because Bob’s permission to sign in to AWS will be based on a match of group names that start with AWS-, as I’ll explain later.

If you follow along with the instructions, make sure you use exactly the same names we do for users, AD groups, and IAM roles, including uppercase and lowercase letters.

Perform the following in your domain:

  1. Create two AD Groups named AWS-Production and AWS-Dev
  2. Give Bob an email address (e.g., bob@example.com)
  3. Add Bob to the AWS-Production and AWS-Dev groups
  4. Create another user named ADFSSVC. This account will be used as the ADFS service account later on.


Installing ADFS

With my accounts and groups set up, I moved on to installing ADFS. On the Windows Server 2012 R2 i’m using we can install adfs 3.0 out of the box so i used this one. Open up the server manager and use the “install roles and features”.


Select the ADFS role


Confirm the changes you are going to make and install ADFS, no reboot is needed


Configuring ADFS

The next step is to configure ADFS.
Launch the console by → Start > All Programs > Administration Tools > AD FS Management

To launch the configuration wizard, select AD FS Federation Server Configuration Wizard

If you want to follow along with my configuration, do this:

1. Select Create a new Federation Server in a server farm


2. Select a domain admin account, i used the default administrator in this demo.


3. Select a SSL certificate. On 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. Remember the service account I mentioned earlier? This is where you use it.


5. Select the internal database, or a sql server if you have one available


6. Review the options and then check the prereqs, click configure to begin the installation


7. When it’s done, the following will appear:


If so, skip ahead to the Configuring AWS section.

During my testing, I went through this wizard on several different Windows servers and didn’t always have 100% success. In some cases I encountered the following error message:


It turns out this is a known issue that can be fixed by running the following at the command line (Make sure you run the command window as an administrator):

Note that is the name of the service account I used.
If the command is successful, you see output like this:


Configuring AWS

You’ve finished configuring AD FS. The next step is to configure the AWS end of things.

To do this, I used the AWS Management Console

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 following address:


You can also use the following powershell script :

I named my SAML providerFederation-Demo. When you have the SAML metadata document, you can create the SAML provider in AWS. As part of that process, you upload the metadata document.
When I finished creating the SAML provider, I created two IAM roles. Once again the IAM documentation has a great walkthrough of these steps, so I won’t repeat them here.

I created two roles using the Grant Web Single Sign-On (WebSSO) access to SAML providers role wizard template and specified the ADFS SAML provider that I just created.

I named the two roles ADFS-Production and ADFS-Dev. Do these names look familiar? They should.

They are the complement to the AD groups created earlier. During the SAML authentication process in AWS, these IAM roles will be matched by name to the AD groups (AWS-Production and AWS-Dev) via ADFS claim rules.

Note: Remember that if you’re following along with this description, you need to use exactly the same names that we use. Make sure that you name the IAM roles ADFS-Production and ADFS-Dev.

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 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 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, enter 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.


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


5. We will ignore the MFA settings for now


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


7. Review your settings and then click Next.


You’re done configuring AWS as a relying party.


Configuring Claim Rules for the AWS Relying Party

In these steps we’re going to add the claim rules so that the elements AWS requires and ADFS doesn’t provide by default (NameId, RoleSessionName, and Roles) are added to the SAML authentication response.

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


Here are the steps I used to create the claim rules for NameId, RoleSessionName, and Roles.

Adding NameId

1. In the Edit Claim Rules for <relying party> dialog box, click 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. ClickFinish.


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:
  Claim rule name: RoleSessionName
  Attribute store: Active Directory
  LDAP Attribute: E-Mail-Addresses
  Outgoing Claim Type: https://aws.amazon.com/SAML/Attributes/RoleSessionName

4. Click Finish


Adding Role Attributes

I’ll pause here to provide a little more context because for these steps it might not be as obvious what’s going on.

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-).
Sending role attributes requires 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.

1. Click Add Rule.

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

3. For Claim Rule Name, select Get AD Groups, and then in Custom rule, enter the following:

I use this in the next rule to transform the groups into IAM role ARNs.

4. Click OK.

5. Click Add Rule.

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://temp/variable. (Think of this as a variable you can access later.)


6. Repeat the preceding steps, but this time enter 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:

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

7. Click OK.


Testing the configuration

1. In your adfs server, browse to the following address: https://localhost/adfs/ls/IdpInitiatedSignOn.aspx

If you’re using a locally signed certificate from IIS, you might get a certificate warning.
On any other server/client, you need to replace localhost with the actual hostname of your adfs server.

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 prompted, enter in a username and password (remember to use Bob’s account).

You will be redirected to the Amazon Web Services Sign-In page.

4. Select a role and then click Sign In. (If you are mapped to only a single IAM role, you skip the role selection step and are automatically signed into the AWS Management Console.)





Ever since I published this blog post, some readers have asked how to configure the AD FS claims using multiple AWS accounts. Those of you with multiple AWS accounts can leverage ADFS and SSO without adding claim rules for each account.

Though there may be other ways to do this, one approach recommended by AWS Senior Solutions Architect Jamie Butler is to use Regex and a common Active Directory security group naming convention.

Then, ADFS can provide cross-account authentication for an entire enterprise.

When using this approach, your security group naming convention must start with an identifier (for example,AWS-). This will distinguish your AWS groups from others within the organization. Next, include the 12-digit AWS account number. Finally, add the matching role name within the AWS account. Here is an example.


Next, update the Roles ADFS claim rule that you created earlier, by using the following code.

This new claim rule limits scope to only Active Directory security groups that begin with AWS- and any twelve-digit number. The claim rule then constructs the SAML assertion in the proper format using the AWS account number and the role name from the Active Directory group name. All AWS accounts must be configured with the same IdP name (in this case Federation-Demo) as described in the “Configuring AWS” section earlier in this post.

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. If a user is associated with multiple Active Directory groups and AWS accounts, they will see a list of roles by AWS account and will have the option to choose which role to assume.

Read Jeff Wierer’s original article here: http://blogs.aws.amazon.com/security/post/Tx71TWXXJ3UI14/Enabling-Federation-to-AWS-Using-Windows-Active-Directory-ADFS-and-SAML-2-0

Leave a Reply

Your email address will not be published. Required fields are marked *