AWS Public Sector Blog

Enabling SAML 2.0 federation with AWS SSO and AWS GovCloud (US)

AWS Single Sign-On (AWS SSO) 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 AWS SSO 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, AWS SSO does not automatically detect AWS GovCloud (US) accounts associated with standard AWS accounts in your AWS Organization. AWS SSO is also not currently available in AWS GovCloud (US). As a result, AWS SSO 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 AWS SSO. 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.

SAML AWS SSONOTE: Because AWS SSO 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 AWS SSO 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 AWS SSO in a standard AWS account (or you meet the prerequisites for AWS SSO and have set it up prior to going through these steps). If you need to setup AWS SSO, you can follow the steps provided in Getting Started.

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

Configure AWS SSO

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

1. Go to the AWS SSO console and select Applications.

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

SAML AWS SSO 2

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.

SAML AWS SSO 3

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

SAML AWS SSO 4

Configure IAM in AWS GovCloud (US) Account

Now create the Identity and Access Management (IAM) resources necessary for SAML federation from AWS SSO. 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 AWS SSO metadata URL that you copied in the final step at the end of the previous section.

b. For SAMLProviderName, enter a name like “AWS-SSO”. 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.

SAML AWS SSO 5

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 AWS-SSO

c. For the Metadata Document, choose the AWS SSO 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.

SAML AWS SSO 6

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.

SAML AWS SSO 7

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

SAML AWS SSO 88. Complete the steps to create the role, providing a suitable Role name in the final step like “AWS-SSO-ViewOnlyAccess”.

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

SAML AWS SSO 9

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 AWS SSO 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 AWS SSO

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

1. In the AWS SSO 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 AWS SSO default store, or an External Directory for your identity source. In this tutorial, users are located in the AWS SSO default store. See Attribute Mappings for more detail on available attributes in each case.

SAML AWS SSO 10

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 AWS SSO. Then select Assign users.

SAML AWS SSO 115. Now when assigned users log into your AWS SSO 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 AWS SSO 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 AWS SSO 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 AWS SSO.

If your organization already relies on an existing identity provider for single sign on (like Azure AD, Okta, or OneLogin), AWS SSO 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 AWS SSO, while end users can authenticate through their familiar identity provider.

Once you’ve configured federation from your external identity provider to AWS SSO, 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 AWS SSO:

Spencer DeBrosse

Spencer DeBrosse

Spencer DeBrosse is a senior solutions architect at Amazon Web Services (AWS). He helps state and local government customers migrate to the cloud. He specializes in end user computing and helping customer implement security and governance policies in AWS.