Skip to main content
Sponsor @cloudposse

The AWS SAML component allows you to authenticate with AWS via a federated identity. This is an alternative to using AWS SSO, that provides lower-level control over the authentication process and supports multiple concurrent IdPs, but with more complexity and a reduced user experience.

As an alternative to AWS SSO, the AWS SAML creates an Identity Provider (IdP) to authenticate with AWS via a federated identity. You can use this federated identity to connect directly to a given AWS Team.

Export an Identity Provider (IdP) metadata file from the chosen provider.

1 Export an Identity Provider (IdP) metadata file from the chosen provider.​

The creation of metadata files will be different for each IdP.

Here are some example setup references:

  1. Open the AWS documentation for GSuite
  2. Follow Steps 1 through 7. This document refers to Appstream, but the process will be the same for AWS.
  3. Once you have completed the setup, download the metadata file.

2 Import the metadata file from the chosen provider.​

Download and save the metadata file with the aws-saml component directory.

  1. Place this file inside the aws-saml component directory (components/terraform/aws-saml/)
  2. The filename should match the variable configured in the aws-saml stack catalog (stacks/catalog/aws-saml.yaml).
  3. Commit this to version control.

Make sure the var.saml_providers map key ends with -okta. We filter by this suffix to determine whether or not to set up a dedicated user for Okta. This is only necessary for Okta.

saml_providers:
  acme-okta: "OktaIDPMetadata-acme.com.xml"

3 Deploy the SAML Integration​

Deploy the aws-saml component to your Identity account.

atmos terraform apply aws-saml -s core-gbl-identity

4 Complete the Identity Provider (IdP) setup​

If necessary, complete the integration setup in your chosen IdP. This will vary depending on the provider.

Follow the steps in the official Okta documentation to complete the setup. Please review the following tips, as we've encountered these issues in the past:

  • Deploying the aws-saml component will create an AWS IAM User, which Okta will be used to discover roles in AWS. This user's access key and secret key are stored in AWS SSM Parameter Store in the same account and (default) region as the aws-saml component. This is unique for Okta.
  • In the "Provisioning" tab for the integration in Okta, you must check the "Update User Attributes" box. This does not appear in documentation but is necessary for the roles to populate in Okta.

5 (Optional) Download AWS Extend Switch Roles Browser Extension​

We suggest using the AWS Extend Switch Roles browser extension to simplify role-switching in the AWS Console. This is optional but particularly helpful if you’re not using AWS IAM Identity Center.

Please see the AWS Extend Switch Roles plugin.

Once you've downloaded the plugin, take the aws-config file from within the rootfs/etc/aws-config directory in your infrastructure repository. Paste this into the AWS Extend Switch Roles plugin configuration.