Automate SAML 2.0 federation for AWS multi-account environments that use Azure AD - AWS Prescriptive Guidance

Automate SAML 2.0 federation for AWS multi-account environments that use Azure AD

Created by Adam Spicer (AWS)

Environment: Production

Technologies: Security, identity, compliance; Infrastructure; Management & governance; Hybrid cloud

Workload: Microsoft

AWS services: AWS CloudFormation; AWS Identity and Access Management; AWS Organizations; AWS Secrets Manager; AWS Control Tower

Summary

Organizations that operate a multi-account strategy in Amazon Web Services (AWS) with AWS Control Tower or AWS Organizations might have a requirement to use Microsoft Azure Active Directory (Azure AD) single sign-on (SSO) for federation into the AWS Management Console. In situations where AWS Single Sign-On might not fit into an organization’s requirements, federation is achieved by using an enterprise application within Azure AD named AWS Single-Account Access, which is deployed within Azure AD for each AWS account. 

As described in a Microsoft tutorial on integrating Azure AD SSO with AWS, programmatic access to each integrated account must be configured by using an AWS Identity and Access Management (IAM) user in each account. Azure AD uses the IAM user to retrieve IAM roles to synchronize with Azure AD. Domain administrators map those synchronized roles to groups of users within Azure AD to enable those users to federate into AWS with the appropriate IAM role. 

If you have a multi-account strategy, the process of manually deploying the integration steps can be cumbersome and can slow down the process of enabling federation into a new AWS account. As each new AWS account gets created, domain administrators often rely on their cloud administrator to create the IAM user, generate the programmatic access keys, and provide the keys to domain administrators in a secure manner. This is often a manual process that prolongs the time from account creation until users can federate into the account. The solution provided in this pattern accelerates this process by providing prescriptive guidance and automation to enable domain administrators to directly obtain the IAM user programmatic access keys in a least privileged manner, without having to involve a third party. As a result, configuring federation for a new AWS account is streamlined through an improved process and automation.

Prerequisites and limitations

Prerequisites 

  • An AWS multi-account configuration that uses AWS Control Tower or AWS Organizations

  • Azure AD Enterprise Applications (EA) created for AWS management and member accounts, with the identity provider (IdP) configured by using the EA metadata

Limitations 

  • The accounts in scope must be a member of the management account's AWS organization.

  • All accounts in scope must be within an AWS organizational unit (OU).

Architecture

Target technology stack  

After you implement this pattern, resources will be deployed into the management account and each member account. The following tables list these resources. 

Management account 

AWS resource Name Description
IAM role AzureAdFederationAdminRole

An IAM role with a trust policy configured for the SAML identity provider (IdP) that allows the role to be assumed only by a companion role for member accounts in the organization.

This IAM role acts as an intermediate role so that users can be configured to federate into the management account with this role and then assume the appropriate role in member accounts.
AWS CloudFormation stack set AzureAdFederationStackSet A stack set that enables you to deploy a stack to all accounts within the organization.
IAM user AzureADAutomationUser The IAM user to be used by Azure AD SSO to synchronize the roles for federation.
IAM group AzureADAutomationGroup The IAM group that contains the IAM user AzureADAutomationUser.
IAM managed policy AzureADAllowIAMListRoles A policy that allows the iam:ListRoles action on all resources. The policy is attached to the IAM group AzureADAutomationGroup to enable Azure AD to synchronize IAM roles.
AWS Secrets Manager secret access key AzureAdFederation / CFNUserSecretAccessKey The programmatic access keys for the IAM user AzureAdAutomationUser, which are generated and stored as a secret within Secrets Manager.

Member accounts

The resources deployed into the member accounts are created from the stack set (AzureAdFederationStackSet) that is configured in the management account.

AWS resource Name Description
IAM role AzureAdFederationAssumeRole

An IAM role with a trust policy that is configured to allow to be assumed by a companion role created in the management account.

The role allows access only to get the secret value that is stored in Secrets Manager.
IAM user AzureADAutomationUser The IAM user to be used by Azure AD SSO to synchronize the roles for federation.
IAM group AzureADAutomationGroup The IAM group that contains the IAM user AzureADAutomationUser.
IAM managed policy AzureADAllowIAMListRoles A policy that allows the iam:ListRoles action on all resources. The policy is attached to the IAM group AzureADAutomationGroup to enable Azure AD to synchronize IAM roles.
Secrets Manager secret access key AzureAdFederation / CFNUserSecretAccessKey The programmatic access keys for the IAM user AzureAdAutomationUser, which are generated and stored as a secret within Secrets Manager.

Target architecture 

The solution deploys a target architecture that uses AWS CloudFormation stacks and stack sets to create the federation components in all accounts. The following diagram illustrates the target architecture.

The following diagram shows the workflow for enabling and configuring the synchronization of member account IAM roles.

After member accounts have been created (step 1 in the diagram), a domain administrator can obtain the IAM user programmatic access keys to all member accounts by following these remaining steps:

  • Step 2. Federate into the management account by using the IAM role AzureAdFederationAdminRole.

  • Step 3. In the AWS Management Console, switch role to a new member account by using the IAM role AzureAdFederationAssumeRole.

  • Step 4. Navigate to Secrets Manager and retrieve the keys in the AzureADFederation / CFNUserSecretAccessKey secret.

  • Step 5. In the appropriate AWS enterprise application within Azure, configure the provisioning administrator credentials by using the retrieved secrets. 

Tools

AWS services

  • AWS CloudFormation – AWS CloudFormation enables you to create and provision AWS infrastructure deployments predictably and repeatedly.

  • IAM – AWS Identity and Access Management (IAM) helps you secure access to AWS services and resources. With IAM, you can centrally manage users, security credentials such as access keys, and permissions that control which AWS resources users and applications can access.

  • AWS Organizations – AWS Organizations is an account management service that lets you consolidate multiple AWS accounts into an organization that you create and centrally manage.

  • AWS Control Tower – AWS Control Tower provides the easiest way to set up and govern a secure, compliant, multi-account AWS environment based on best practices established by working with thousands of enterprises.

  • AWS Secrets Manager – AWS Secrets Manager enables you to rotate, manage, and retrieve database credentials, API keys, and other secrets throughout their lifecycle.

Code 

This pattern includes two CloudFormation templates (YAML files) that you can use to deploy the target architecture (see attached). The epics and stories in the next section provide detailed instructions for using these templates.

Epics

Task Description Skills required
Run the CloudFormation template to create the administrator role and IAM user in the management account.

From the management account, run the CloudFormation script named cfn-azuread-fed-admin-role.yaml (see attachment). You will need to specify your AWS organization ID and the name of the SAML provider that exists in the management account.

CloudFormation
Task Description Skills required
Create a CloudFormation stack set for all member accounts.

From the management account, use the cfn-azuread-fed-stackset.yaml template (see attachment) to create a new stack set with the following stack set deployment options: 

Deploy stacks in organization units: 

  • Specify all top-level parent OUs for member accounts that will receive this stack.

  • Be sure that the management account and all other core accounts are within one of these top-level OUs.

Regions: Choose one AWS Region where the IAM secrets will be stored within Secrets Manager.

CloudFormation
Task Description Skills required
Configure Azure AD Federation synchronization for the management account

The new role named AzureAdFederationAdminRole in the management account needs to be mapped within the Azure AD AWS enterprise application to enable an Azure AD administrator to configure the role synchronization process for all member accounts. Follow these steps: 

  1. Obtain the IAM user programmatic access keys for AzureADAutomationUser in the management account by navigating to Secrets Manager and accessing the secret named AzureADFederation / CFNUserSecretAccessKey

  2. Within the AWS enterprise application for the management account, configure the administrator credentials in the provisioning area by using the IAM user programmatic access keys you obtained in the previous step, test the connection, and enable provisioning. 

  3. Wait for the synchronization to complete. Then map the AzureAdFederationAdminRole role to the appropriate Azure AD administrator users within the AWS enterprise application for the management account, to give them access to the role for the management account. 

  4. Test the AWS enterprise application by federating into the management account using the AzureAdFederationAdminRolerole. Test your access to one of the member accounts by using the following process:

    1. Choose Switch Roles from the account menu, and provide one of the member account IDs and the AzureAdFederationAssumeRole role name. 

    2. After you switch roles, make sure that you can access the secret named AzureADFederation / CFNUserSecretAccessKey in Secrets Manager.

Azure AD administrator, Secrets Manager
Configure Azure AD federation synchronization for all member accounts.

As an Azure AD administrator, first federate into the management account by using the AzureAdFederationAdminRole role. For each member account, follow these steps: 

  1. From the management account, choose Switch Roles from the account menu, and provide one of the member account IDs and the AzureAdFederationAssumeRole role name. Then choose Switch Role

  2. In the member account, access the IAM user programmatic access key secret named AzureADFederation / CFNUserSecretAccessKey in Secrets Manager. 

  3. Within the given member account AWS enterprise application, configure the IAM user credentials in the provisioning area by using the IAM user programmatic access keys obtained earlier, test the connection, and enable provisioning. 

  4. Verify that any federation IAM roles are synchronized to the given AWS enterprise application. Map the roles appropriately to Azure AD users. 

Repeat these steps for each member account.

Azure AD administrator, Secrets Manager

Attachments

attachment.zip