In this blog post, we explore how to set up Security Assertion Markup Language (SAML) 2.0 for single sign-on (SSO) to the AWS Management Console across multiple accounts. SAML is widely utilized by various identity providers (IdPs) for identity federation, allowing users to authenticate into the AWS Management Console or make programmatic calls via AWS APIs through assertions from a SAML-compliant IdP. Many organizations manage multiple AWS accounts (like production, development, and testing) and seek guidance on using SAML for identity federation. This article will walk you through enabling federated access for users to the AWS Management Console across various AWS accounts using SAML.
If you’re utilizing Microsoft Active Directory in your organization, you may already understand how Active Directory and AD FS (Active Directory Federation Services) function together to facilitate federation. For this guide, we will leverage Active Directory alongside AD FS as the example IdP.
To streamline the installation and configuration of AD FS and Active Directory, we’ll be using Windows PowerShell. By employing PowerShell, you can bypass tedious manual setups and concentrate on higher-level processes.
If you are looking to manage access to all your AWS accounts through Active Directory and AD FS, you are in the right place!
Background
When setting up your Windows Active Directory domain, you have several options. You can utilize an Amazon EC2 instance to create your domain through dcpromo or by installing the Active Directory role (for Windows Server 2012 and later). You can even automate this process using an AWS CloudFormation template that provisions a Windows instance and configures a domain for you. Alternatively, you might consider creating a Simple AD with AWS Directory Service. Our documentation provides details on managing these directories, joining EC2 instances to the domain, and creating users and groups.
Initial Steps
When implementing SAML federation, AWS mandates that the IdP issues a SAML assertion containing certain essential attributes known as claims. AWS documentation offers guidance on configuring these SAML assertions. In summary, the assertion should include:
- An attribute named
https://aws.amazon.com/SAML/Attributes/Role, which should have a value of at least one role/provider pair as a comma-separated list of their Amazon Resource Names (ARNs). As the ARNs are unique to each AWS account, this information specifies the account to which you want to federate. - An attribute named
https://aws.amazon.com/SAML/Attributes/RoleSessionNamewith a string value, which serves as the federated user’s friendly name in AWS. - A name identifier (NameId) to identify the subject of the SAML assertion.
AWS has also published troubleshooting steps in our documentation for debugging SAML responses from your IdP. Common issues often relate to the aforementioned attributes: they may be absent, misspelled (case sensitivity is crucial!), or may not include the expected values. If you encounter challenges with SAML federation, start by gathering a copy of the SAML response sent to AWS.
If you’re unsure how to collect a copy of the SAML response, check our documentation, and then decode and troubleshoot the response.
Use Case
Consider a company, Sample Corp., which seeks:
- Federated identity access for select user groups within its organization.
- Management of federation across multiple AWS accounts.
- Support for three user categories:
- Users with access to 1 account and 1 role (1:1).
- Users accessing multiple accounts with 1 role (N:1).
- Users accessing multiple accounts with multiple roles (N:M).
Sample Corp. is utilizing Active Directory and aims to manage federation centrally through AD FS. They intend to federate to two AWS accounts: 123456789012 and 111122223333.
Preparing Your Environment
The blog post, Enabling Federation to AWS Using Windows Active Directory, AD FS, and SAML 2.0, illustrates how to set up Active Directory and install AD FS 2.0 on Windows Server 2008 R2. In this post, we will be installing AD FS 3.0 on Windows Server 2012 R2. Remember, AD FS 3.0 cannot be installed on Windows Server 2008 R2 or earlier, so ensure you select the correct Windows Server version. The installations and configurations for AD FS 2.0 and 3.0 are quite similar, allowing us to illustrate the process using Windows PowerShell. I will also outline the steps from the GUI for further reference at the conclusion of the post.
I appreciate how Windows PowerShell simplifies the configuration process. To ease your experience, I have adopted the same naming conventions for claim rules, Active Directory groups, and IAM entities from Jeff Wierer’s blog post.
The .zip file containing related scripts includes:
- Two folders: Logs (for log file storage) and Utilities (where the PowerShell script is saved).
- The following scripts:
00-Configure-AD.ps1: Simplifies Active Directory group and user creation along with the configuration needed for the federation solution discussed in this post.01-Install-ADFS.ps1: Installs AD FS 3.0 on Windows Server 2012 R2 and downloads the federation metadata.02-Configure-IAM.ps1: Creates an identity provider and two IAM roles in the chosen AWS account.03-Configure-ADFS.ps1: Establishes a relying party trust to AWS using the templates:auth.txtandclaims.txt.
Unzip the file on the designated Windows Server 2012 R2 computer for the AD FS 3.0 installation. Additionally, install AWS Tools for Windows PowerShell on that machine, as it is required for completing the IAM configuration from the command line. At this stage, you do not need to configure a credential profile.
General Workflow
The typical workflow follows these steps:
- The user navigates to the AD FS sign-in page for authentication.
- AD FS authenticates the user against Active Directory.
- Active Directory returns the user’s details.
- AD FS dynamically constructs ARNs using Active Directory group memberships for the IAM roles and user attributes for the AWS account IDs, sending a signed assertion to AWS STS.
- The user arrives at the AWS role selection page, where they can choose which account to access and which role to assume.
AWS STS serves as the single access point for all SAML-federated access. The ARNs in the SAML response are utilized to identify your SAML provider and IAM role within your target account. The next section clarifies how to streamline administration for the ARNs on your AD FS server, including examples of custom claim rule code.
The Solution in Action
To illustrate the user experience, let’s consider a user named Alice, who is a member of two Active Directory groups: AWS-Dev and AWS-Production.
For more insights on this topic, you may find it helpful to read another blog post here. Additionally, this resource is an authority on this subject. Lastly, you can refer to this excellent resource for further information.
Leave a Reply