Enabling SAML 2.0 federation with AWS IAM Identity Center and AWS GovCloud (US)

**Note as of 10-27-22: AWS IAM Identity Center is now available in the AWS GovCloud (US-West) Region. This solution described in this blog may still be an option for customers with an existing AWS IAM Identity Center instance in a standard region who want users to access all AWS accounts (both standard and AWS GovCloud (US)) from a single access portal URL. The solution is also only suitable for customers with a small number of AWS GovCloud (US) accounts.

AWS IAM Identity Center (successor to AWS Single Sign-On) helps administrators centrally manage access to multiple AWS accounts that are members of an AWS Organization. End users can authenticate and then access all their AWS accounts from a single interface. Using IAM Identity Center as a SAML identity provider for your AWS accounts also has security benefits: user credentials provided via federation are temporary. These credentials can be configured to last for a few minutes to several hours. After the credentials expire, Amazon Web Services (AWS) no longer recognizes them or allows any kind of access from API requests made with them.

AWS GovCloud (US) Regions are physically isolated and have logical network isolation from all other AWS Regions. As a result, IAM Identity Center does not automatically detect AWS GovCloud (US) accounts associated with standard AWS accounts in your AWS Organization. IAM Identity Center is also not currently available in AWS GovCloud (US) (see note at top of post). As a result, IAM Identity Center cannot be used to automatically provision access for your users into an AWS GovCloud (US) account.

However, this functionality can be extended to enable federation into AWS GovCloud (US) with a “custom SAML 2.0 application” in IAM Identity Center. This allows end users to assume an AWS Identity and Access Management (AWS IAM) role in AWS GovCloud (US) using SAML federation, with the same credentials and interface they use to access standard AWS accounts.

NOTE: Because IAM Identity Center does not yet provide APIs to automate creation and configuration of custom SAML 2.0 applications, many of the steps in this blog are manual and must be completed using the AWS Management Console. The following instructions are best suited for customers who already use IAM Identity Center with their standard AWS accounts and wish to configure federation for a small number of AWS GovCloud (US) accounts. Customers with large, multi-account AWS GovCloud (US) environments should consider other federation solutions.

Prerequisites

1. Administrator access to an AWS GovCloud (US) account. This is necessary to create roles and an identity provider in IAM. If you do not already have admin access configured in your account, “Creating your first IAM admin user and group” provides step-by-step instructions.

2. You should already be using IAM Identity Center in a standard AWS account (or you meet the prerequisites for IAM Identity Center and have set it up prior to going through these steps). If you need to setup IAM Identity Center, you can follow the steps provided in Getting Started.

3. Sufficient IAM access to create and configure applications in IAM Identity Center. “Using Identity-Based Policies (IAM Policies) for AWS SSO” provides an example permissions policy for users who need to work with IAM Identity Center.

Configure IAM Identity Center

Start by creating a custom SAML 2.0 application in IAM Identity Center. This application represents your AWS GovCloud (US) account.

1. Go to the IAM Identity Center console and select Applications.

2. Select Add a new application and then select Add a custom SAML 2.0 application.

3. On the configuration page, provide a suitable name like “AWS GovCloud Account” and a description.

4. Under Application metadata, select If you don’t have a metadata file, you can manually type your metadata values and then enter the following values:

a. Application ACS URL: https://signin.amazonaws-us-gov.com/saml

b. Application SAML audience: urn:amazon:webservices:govcloud

5. Then select Save changes at the bottom of the page.

6. On the Attribute mappings tab, modify the existing Subject attribute to have a mapped value of “${user:name}” and a Format or “persistent.” Then select Save changes.

7. Under the Configuration tab, select Edit configuration. Under the IAM Identity Center metadata section, select Copy URL to copy the URL for the IAM Identity Center SAML metadata file. Use this URL in the next section.

Configure IAM in AWS GovCloud (US) Account

Now create the Identity and Access Management (IAM) resources necessary for SAML federation from IAM Identity Center. Provision these resources with an AWS CloudFormation template inside your AWS GovCloud (US) account (the URL for the template is provided in the following steps). Specifically, the template creates an identity provider and IAM role, which users assume. To complete these steps using the AWS Management Console or AWS Command Line Interface (AWS CLI), refer to the additional instructions at the end of this section.

1. Log into your AWS GovCloud (US) account as an IAM user or role with Administrator privileges.

2. Navigate to the AWS CloudFormation console. Either AWS GovCloud (US) Region (US-Gov-East or US-Gov-West) can be used for these steps.

3. Select Create stack.

4. Download the CloudFormation template. Under Specify template, select Upload a template file and then Choose file. Select the template from your local filesystem and the select Next.

5. Provide a Stack name like “AWS-SSO-Roles-IdP”

6. Provide input for each Parameter:

a. For the AWSSSOMetadataUrl field, enter the IAM Identity Center metadata URL that you copied in the final step at the end of the previous section.

b. For SAMLProviderName, enter a name like “IAM-Identity-Center”. Note: Provide a unique name that does not match the name of an existing identity provider in your account. Otherwise, the CloudFormation stack creation process fails.

c. By default, this template creates three sample IAM roles: Administrator, Power User, and Read Only. You can select true or false above each role to control whether that role will be created by the CloudFormation template. You can also change the name of each role if you wish. Note: rename these roles if you already have IAM roles in your account with the same names.

7. Select Next and then Next again on the Configure stack options page.

8. At the bottom of the Review page, select the box next to I acknowledge that AWS CloudFormation might create IAM resources with custom names and select Create stack. The creation process takes around 1 minute.

9. Once your stack has a status of “CREATE_COMPLETE”, select the Outputs tab and copy the IdentityProviderArn and just one of the RoleArn* values. You need this in the next section.

Equivalent Steps in AWS Console

1. Log into your AWS GovCloud (US) account as an IAM user with Administrator privileges.

2. Navigate to the Identity and Access Management console and select Identity providers.

3. Select Create Provider.

a. For Provider Type, choose SAML

b. Specify a suitable Provider Name like IAM-Identity-Center

c. For the Metadata Document, choose the IAM Identity Center metadata XML file you downloaded in the previous section.

4. Finally, select Next Step and then Create. On the Summary page, copy the Provider ARN. You need it in a later step.

5. In the IAM console, select Roles and then Create role.

6. Under Select type of trusted entity, select SAML 2.0 federation.

a. Select the SAML provider you created previously in the drop down.

b. Select Allow programmatic and AWS Management Console access.

c. Finally, select Next: Permissions.

7. Select the type of policy you’d like to grant users who federate from IAM Identity Center into your AWS GovCloud (US) account. In this example, I chose the ViewOnlyAccess managed policy.

8. Complete the steps to create the role, providing a suitable Role name in the final step like “IAM-Identity-Center-ViewOnlyAccess”.

9. Once the role has been created, select it and copy the Role ARN, which you need in the next section.

Equivalent Steps in AWS CLI

You can also complete Steps 1-9 using the AWS CLI:

1. Create your SAML identity provider in IAM. Replace <SAML_METADATA_URL> in this command with the URL of the metadata document you copied from IAM Identity Center in the previous section:

aws iam create-saml-provider --saml-metadata-document <SAML_METADATA_URL> --name AWS-SSO

Copy the Provider ARN that is returned as a response. You need it for the next step.

2. Create your IAM role. Modify the trust policy document in this command to include your own SAML Provider ARN:

aws iam create-role --role-name "AWS-SSO-ViewOnlyAccess" --assume-role-policy-document '{"Version":"2012-10-17","Statement":[{"Effect":"Allow","Action":"sts:AssumeRoleWithSAML","Principal":{"Federated": "<PROVIDER-ARN>"},"Condition":{"StringEquals":{"SAML:aud":["https://signin.amazonaws-us-gov.com/saml"]}}}]}'

3. Attach the appropriate policy to your role:

aws iam attach-role-policy --role-name "AWS-SSO-ViewOnlyAccess" --policy-arn "arn:aws-us-gov:iam::aws:policy/job-function/ViewOnlyAccess"

Complete Configuration in IAM Identity Center

Finally, we complete configuration of your application in IAM Identity Center and then assign some users who you want to have access to AWS GovCloud (US).

1. In the IAM Identity Center console, return to the configuration page for your AWS GovCloud (US) Account application

2. On the Attributes mapping tab, add two new attribute mappings and then select Save changes. The <PROVIDER-ARN> and <ROLE-ARN> are values we copied in the previous section when configuring IAM resources in your AWS GovCloud (US) account:

Attribute: https://aws.amazon.com/SAML/Attributes/Role
- Mapped value: <PROVIDER-ARN>,<ROLE-ARN>
Attribute: https://aws.amazon.com/SAML/Attributes/RoleSessionName
- Mapped value: ${user:email}

NOTE: The value you choose for RoleSessionName and Subject depends on the attributes available for your users. Available attributes vary depending on whether you’re using AWS Managed Microsoft AD, the built-in IAM Identity Center default store, or an External Directory for your identity source. In this tutorial, users are located in the IAM Identity Center default store. See Attribute Mappings for more detail on available attributes in each case.

3. Assign some users who you want to log into AWS GovCloud (US). Select the Assigned users tab, and select Assign users.

4. Select the user(s) or group(s) you’d like to be able to sign into AWS GovCloud (US) via IAM Identity Center. Then select Assign users.

5. Now when assigned users log into your IAM Identity Center User Portal URL, they should see an AWS GovCloud (US) application. When they select the application, they are federated into your AWS GovCloud (US) account:

If you receive any error during the federation process, search for the specific error in Troubleshooting SAML 2.0 federation with AWS to determine the issue.

Conclusion and next steps

In this blog, we configured a cloud application in IAM Identity Center so that users can federate into an AWS GovCloud (US) account using SAML 2.0. This provides end users with a consistent authentication experience, whether they’re signing into standard AWS accounts or AWS GovCloud (US) accounts. It also improves security posture of AWS GovCloud (US) accounts by reducing reliance on IAM users for authentication.

Please note that the application we configured in IAM Identity Center allows a user to assume a single IAM role in a specific AWS GovCloud (US) account. If you’d like to allow users to log into multiple AWS GovCloud (US) accounts or assume different IAM roles in the same account, you will need to create additional custom SAML 2.0 applications in IAM Identity Center.

If your organization already relies on an existing identity provider for single sign on (like Azure AD, Okta, or OneLogin), IAM Identity Center now provides customers with the ability to authenticate identities from external identity providers. This means that administrators can still get the benefits of configuring access to AWS accounts centrally in IAM Identity Center, while end users can authenticate through their familiar identity provider.

Once you’ve configured federation from your external identity provider to IAM Identity Center, you can still follow the steps in this blog to provide access to AWS GovCloud (US). Check out these articles for configuring an external identity provider with IAM Identity Center:

Subscribe to the AWS Public Sector Blog newsletter to get the latest in AWS tools, solutions, and innovations from the public sector delivered to your inbox, or contact us.