How to Set Up Uninterrupted, Federated User Access to AWS Using AD FS

Microsoft Active Directory Federation Services (AD FS) is a common identity provider that many AWS customers use to give federated users access to the AWS Management Console. AD FS uses multiple certificates to ensure secure communication between servers and to act as authentication mechanisms. One such mechanism is called the token-signing certificate.

When the token-signing certificate expires, or is changed, the trust relationship between the claim provider, AD FS, and the relying party, AWS Security Token Service (AWS STS), is broken. Without a valid certificate to prove the calling server’s identity, the receiving party cannot verify the certificate, which terminates the request and thus prevents federated users from being able to access the AWS Management Console. Luckily, this can be avoided!

In this blog post, I explain how you can use the AutoCertificateRollover feature in AD FS to enable uninterrupted connections between your claim provider and your relying trust. I also show how to set up a secondary certificate manually in AD FS to avoid service interruption when a server certificate expires.

This post assumes that you have a working AD FS configuration. If you do not, you can follow the steps in the following blog posts to get you up and running:

• Enabling Federation to AWS Using Windows Active Directory, AD FS, and SAML 2.0
• How to Set Up SSO to the AWS Management Console for Multiple Accounts by Using AD FS and SAML 2.0

Let’s start by taking a quick look at how AD FS uses the token-signing certificate.

Background

The token-signing certificate is used by AD FS to sign the Security Assertion Markup Language (SAML) assertion—also known as an AuthN response—that AD FS sends to a relying party to authenticate to Active Directory (AD) its information, such as Role, RoleSessionName, and X509 certificates. For this post’s use case, the relying party is AWS STS, which AD FS uses to provide federated users access to the AWS Management Console and AWS APIs. The following diagram illustrates the authentication process.

1. The flow is initiated when a user—let’s call him Bob—browses to the AD FS sample site (https://Fully.Qualified.Domain.Name.Here/adfs/ls/IdpInitiatedSignOn.aspx) inside his domain. When Bob installed AD FS, he was given a new virtual directory named adfs for his default website, which includes this sample site.
2. The sign-on page authenticates Bob against Active Directory. Depending on the browser Bob is using, he might be prompted for his Active Directory user name and password.
3. Bob’s browser receives an AuthN response in the form of an authentication response from AD FS.
4. Bob’s browser posts the AuthN response to the AWS sign-in endpoint for SAML (https://signin.thinkwithwp.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 AWS Management Console.

For a more complete description of the certificates that AD FS uses, see Understanding Certificates Used by AD FS.

Key AD FS settings and how to change them

AD FS has default settings to help ensure that your certificates never expire. You can see these default settings by opening a Windows PowerShell window with administrative rights on your AD FS server, and then running Get-ADFSProperties.

If you are using AD FS 2.0, you first need to import the AD FS cmdlets for Windows by running the following commands. If you are using AD FS 3.0, these cmdlets will already be installed for you.

Add-PSSnapin Microsoft.Adfs.PowerShell
Get-ADFSProperties

The output should resemble what the following screenshot shows.

The output shows you the settings for your AD FS properties, and it tells you whether or not AutoCertificateRollover is enabled, the host name of your server, timeouts, and so on. These settings are handy to know for AD FS server administration tasks, such as checking certificate settings, timeouts, domain, and containers. However, for the purposes of this post, the settings and values I will focus on in the output are the following:

AutoCertificateRollover                    : True
CertificateGenerationThreshold             : 20
CertificatePromotionThreshold              : 5
CertificateRolloverInterval                : 720

To explain these settings:

• When set to True, AutoCertificateRollover enables the automatic generation of a new self-signed certificate to sign your AuthN response.
•  There is also a default CertificateGenerationThreshold of 20 days that creates the secondary certificate 20 days before the original certificate expires. This certificate will not be used until the CertificatePromotionThreshold is reached.
• The default setting for CertificatePromotionThreshold is 5 days. 5 days after the secondary certificate is created, it will automatically be promoted to primary. This gives your relying parties a 5-day window to update the federation metadata so that zero downtime is experienced. After this 5-day window, the primary certificate is set to secondary and will then expire on the original expiration date. You must download the metadata document again so that it contains the newly created certificate.

Because the relying parties count on having a valid certificate to verify identity, they need a copy of this new metadata document to validate requests. This allows you to minimize the concern of the certificate expiring and having downtime. The relying trusts still need to upload the new metadata document to ensure that a copy of the new certificate is readily available for authentication purposes. If the relying trust does not update the metadata document, downtime with connection to that service could be experienced after the original primary certificate expires.

• AD FS checks the certificate status every CertificateRolloverInterval, which is in minutes. The default value is 720 minutes (12 hours).

You can change the aforementioned AD FS properties by using the Set-ADFSProperties cmdlet. For example, you can change the CertificatePromotionThreshold from 5 to 10 days by running the following command.

Set-ADFSProperties -CertificatePromotionThreshold 10

This change gives you more time to deal with the relying party update.

If certificate rotation is something you would like to handle manually because you want to have full control, you can disable the rollover feature by running the following command.

Set-ADFSProperties –AutoCertificateRollover:$false

To avoid service interruption, you must download the new metadata document and upload it to the relying parties that use it, before the primary certificate expires.

Next, you will change permissions on a certificate so that AD FS has access to it.

Change permissions on the private key of the certificate

A prerequisite for completing this section is that you acquire a new, unexpired certificate. You can do this by creating a self-signed certificate as explained in Enabling Federation to AWS Using Windows Active Directory, ADFS, and SAML 2.0, or you can purchase a Secure Sockets Layer (SSL) certificate from the third-party provider of your choice. Manual rotation is required if you purchase an SSL certificate from a trusted third party because AD FS does not have a rollover feature for these certificates.

After you have installed a new, unexpired certificate on your AD FS server, you must ensure that the AD FS service account has access to the private key for this new server certificate.

To change the permissions on the private key of the certificate:

1. On your AD FS server, open the MMC Console. Click Start, type MMC, and then press Enter.
2. In the MMC Console, click File and then click Snap-in Add/Remove. Then click Certificate, Local Computer, and then OK.
3. Under Certificates (Local Computer), expand Personal, and then click Certificates (as shown in the following screenshot).

4. Right-click the new certificate you just installed, and then click All Tasks – Manage Private Key.
5. On the Permissions tab, select Add User and grant the AD FS service account full control. Do this by searching for the service account name you selected when setting up your AD FS server, clicking OK, and then selecting the check box for Full Control under Allow (as shown in the following screenshot). Then click Apply.
   
6. If you are not sure about which account name to run as, you can retrieve this information by clicking Start and Run, and then typing services.msc. As shown in the following screenshot, check the Log On As column for Active Directory Federation Service. In my case, the account is ADFSSVC$. Windows adds a $ to the end of managed service accounts, such as accounts that are used to run services like AD FS. User accounts do not have such a suffix added to them.

Now that AD FS has access to the private key of the new certificate, you can open the AD FS console and configure the server to add this new certificate as a secondary certificate when signing the SAML AuthN response. This is to ensure that a secondary certificate is available for identity authentication when the primary certificate expires.

Manually add the new certificate as the secondary certificate

As explained previously in this post, the only certificate that AWS needs from AD FS is the token-signing certificate.

To add the new certificate manually for AD FS server authentication:

1. Open the AD FS console, click the Service folder, and then click the Certificates folder, as shown in the following screenshot.

2. Click Add Token-Signing Certificate and select the certificate you wish to use as the secondary certificate. After you upload it, this certificate is listed as Secondary.

Note: In order to complete this process, you must disable any self-signed, autorotating certificates you may have configured.

3. Open Windows PowerShell as an Administrator and run the following commands. If you are using AD FS 3.0, you can skip the first command, which adds the PSSnapin that is already installed in AD FS 3.0.

Add-PSSnapin Microsoft.ADFS.PowerShell
Set-ADFSProperties –AutoCertificateRollover $false

4. Download the new copy of the metadata document from the following link (placed in a browser on your AD FS server): https://<yourservername>/FederationMetadata/2007-06/FederationMetadata.xml.

You are still using the soon-to-expire certificate (the original primary certificate), but the new certificate is set as a secondary certificate. If you look at your FederationMetadata.xml file now, you will see that both certificates are included. The trust with your relying party is based on the information shared in the FederationMetadata.xml file, so the final step is to update your relying parties with this new metadata document.

To update your relying parties with the new metadata document:

1. Sign in to the AWS Management Console.
2. Click Services and then click IAM to go to the IAM console.
3. Click Identity Providers in the left pane.
4. Select the name of the identity provider (IdP) you created for your SAML SSO.
5. Click Upload Metadata and select the file you downloaded from your AD FS server via the federation metadata link just provided in the previous section.
6. Click Upload. The IdP now has an updated FederationMetadata.xml document to validate authentication requests from your claims provider

Updating the metadata document in AWS after creating and adding the secondary certificate ensures there is no downtime later when transitioning from the primary certificate to the secondary certificate.

Update the AWS configuration before the primary certificate expires

When you have the new federation metadata with the soon-to-expire (primary) certificate and the new (secondary) certificate that was either automatically generated by AD FS or one that you installed, you must update the relying party configuration before the primary certificate expires.

To update the AWS configuration:

1. Sign in to the AWS Management Console as an IAM user that has access to update IdPs.
2. In the IAM console in the Identity Providers section, select the IdP you want to update.
3. Click Upload Metadata and then click Choose File. Navigate to the directory into which you downloaded the new FederationMetadata.xml file and choose the file. Click Upload.

Test it!

Now that you have uploaded the new metadata document with both certificates listed, you can test a sign-in to the AWS Management Console through your normal means of federation. This sign-in should complete without issue. However, if you experience any errors, you can check a few things:

1. Is the primary certificate still listed in the AD FS console?
2. Did the relying party upload the certificate correctly?
3. Check the FederationMetadata.xml file to ensure all security information is still being passed as before (Role, RoleSessionName, X509 certificate, and so on).

If you are using autorollover, the process is complete. No further action is required on your part to ensure a valid certificate is used for identity validation between your claims provider and relying trust. If you manually set the certificate, to ensure zero downtime you must rotate the secondary certificate to become the primary certificate before it expires.

To rotate the secondary certificate to be the primary certificate:

1. Open the AD FS console and click Certificates.
2. Right-click the new certificate you uploaded, and then click Primary.

To help keep your setup “clean,” follow these steps to remove the expired certificates from your server:

1. Open the AD FS console and click Certificates.
2. Select the old certificate under Token-Signing Certificate, and then click Delete.

Going forward, server certificate expiration should not affect your ability to connect with AWS via your SAML setup.

If you have comments about this blog post, please add them to the “Comments” section below. If you have questions about this blog post, start a new thread on the IAM forum.

– Tracy

Want more AWS Security how-to content, news, and feature announcements? Follow us on Twitter.