Access AWS GovCloud (US) through the CLI with Azure AD credentials

Many government customers use AWS GovCloud (US) because it provides an environment for sensitive data and regulated workloads by addressing a number of U.S. government security and compliance requirements. In a previous post, I detailed how to use AWS single sign-on (SSO) with Microsoft Azure AD to federate to AWS GovCloud (US). In that post, the AWS Management Console using AWS SSO provided access. However, customers often find that having console access to AWS GovCloud (US) is not enough and need to use the Command Line Interface (CLI) or Application Programming Interfaces (APIs).

Providing access through Azure AD to AWS GovCloud (US) reduces the number of credentials administrators need to manage and use for access to AWS GovCloud (US) and can also increase security to the account by using the same Multi-Factor Authentication (MFA) mechanism used with Azure AD. This access also allows the use of scripts and programs to help manage resources in the AWS accounts. This post is a walkthrough of using an open-source utility called saml2aws to provide programmatic access to Amazon Web Services (AWS) for Azure AD users.

Note that this walkthrough uses saml2aws, which is a popular choice, but isn’t a unique option. The internet contains hundreds of derivative forks, most stemming from the blog, “How to Implement a General Solution for Federated API/CLI Access Using SAML 2.0.” Even though saml2aws eliminates a large number of technical steps, it is open source code that must be properly evaluated before using in production.

Prerequisites

For this walkthrough, you should have the following prerequisites:

• An AWS account
• An AWS GovCloud (US) account
• A Microsoft Azure account

Solution overview

The end result of this solution allows a user to obtain a set of Access Keys for an AWS GovCloud (US) account using their credentials from Azure AD.

Walkthrough

Configuring the Azure SAML provider with AWS GovCloud (US)

This walkthrough configures a single account and assumes you already configured a SAML Provider from an Azure AD tenant in the AWS GovCloud (US) account. For configuring a large number of AWS accounts with Azure, refer to “How to automate SAML federation to multiple AWS accounts from Microsoft Azure Active Directory.” Once you configured the Azure Provider in your AWS GovCloud (US) and created a role, follow these next steps to install and configure saml2aws.

Configuring CLI access to AWS GovCloud (US) for Azure AD users

1. Make sure the AWS CLI is installed on the host. You can find directions at Installing the AWS CLI.

2. First, determine the current version of saml2aws and download a copy to your linux host. Windows and Mac version of saml2aws are available at this Install location. At the time of this writing, version 2.27.1 was available.

$ CURRENT_VERSION=2.27.1
$ wget https://github.com/Versent/saml2aws/releases/download/v${CURRENT_VERSION}/saml2aws_${CURRENT_VERSION}_linux_amd64.tar.gz

3. Once downloaded, create a directory to extract the tarball and change the execution settings:

$ mkdir -p ~/.local/bin
$ tar -xzvf saml2aws_${CURRENT_VERSION}_linux_amd64.tar.gz -C ~/.local/bin
saml2aws
$ chmod u+x ~/.local/bin/saml2aws

4. Confirm that it is working and accessible. Then, reload the environment variables and use the following two commands:

$ saml2aws --version
$ exec -l bash

5. To configure saml2aws, you need two pieces of information. First, from Azure, you need to get the Application ID from the AWS GovCloud (US) Application configured in Azure:

6. Next, you need to get the Amazon Resource Name (ARN) for the role used for the Federation. Browse to the AWS Identity and Access Management (IAM) role in the AWS Management Consol, and use the copy button found here:

7. To configure saml2aws, take the Application ID and ARN from the previous two steps, and use them in the following command. You will also want to replace <YOUR-AZURE-AD-USER-NAME> with your Azure AD username but it is not required:

$ saml2aws configure \
     --idp-provider='AzureAD' \
     --mfa='Auto' \
     --profile='saml' \
     --url='https://account.activedirectory.windowsazure.com' \
     --username='<YOUR-AZURE-AD-USER-NAME>' \
     --app-id='<YOUR-APPLICATION-ID>' \
     --skip-prompt \
     --role='<YOUR-IAM-ROLE-ARN>' \
     --idp-account='saml' \
     --aws-urn='urn:amazon:webservices:govcloud' \
     --region='us-gov-west-1'

Note that profile and idp-account are both specified so that the default is not overwritten in the AWS credential file and the saml2aws configuration file, respectively. For multiple US GovCloud (US) accounts, change these entries to create multiple profiles.

8. To be able to get a set of temporary keys using federation, run the following command:

$ saml2aws --idp-account='saml' login

9. At this point, you should get prompted for your Azure AD credentials and a one-time password if MFA is configured with Azure AD:

Using IDP Account saml to access AzureAD https://account.activedirectory.windowsazure.com
To use saved password just hit enter.
? Username dmitryk@dmitryk.onmicrosoft.com
? Password **********
Authenticating as dmitryk@dmitryk.onmicrosoft.com ...
Selected role: arn:aws-us-gov:iam::<AWS-ACCOUNT-ID>:role/kagansky-azure-sso
Requesting AWS credentials using SAML assertion
Logged in as: arn:aws-us-gov:sts::<AWS-ACCOUNT-ID>:assumed-role/kagansky-azure-sso/dmitryk@dmitryk.onmicrosoft.com
Your new access key pair has been stored in the AWS configuration
Note that it will expire at 2020-10-08 14:25:17 +0000 UTC
To use this credential, call the AWS CLI with the --profile option (e.g. aws --profile saml ec2 describe-instances).

Once you successfully authenticate, you can use the profile specified with an AWS CLI command. It lasts for the session length specified during the federation setup. If you have an account with list-buckets permissions in Amazon Simple Storage Service (Amazon S3), you can run this statement to confirm the profile is properly configured:

aws s3api --profile 'saml' --region us-gov-west-1 list-buckets

Conclusion

AWS GovCloud (US) is a separate set of Regions allowing U.S. customers to adhere to a number of regulations and programs. Before using this solution, please review your specific compliance and regulatory requirements against the current AWS Services in Scope. Providing programmatic access with Azure AD for end users allows easier administration and usage of AWS GovCloud (US) by reducing the number of credentials each user has to manage.

Learn more about AWS GovCloud (US) and check out other recent blog posts and resources on AWS GovCloud (US).