Using AWS SAML to Access AWS

AWS SAML provides federated identity access to AWS, allowing users to authenticate via their Identity Provider and assume IAM roles directly. While the reference architecture defaults to AWS IAM Identity Center with Permission Sets, AWS SAML remains fully supported for organizations that prefer or require direct SAML federation.

When to Use AWS SAML

AWS SAML is an alternative to AWS IAM Identity Center that provides:

1. Lower-level control — Direct SAML federation to IAM roles without the Identity Center abstraction
2. Multiple concurrent IdPs — Support for multiple Identity Providers simultaneously
3. Legacy compatibility — Works with existing SAML-based authentication workflows

Requirements

Using AWS SAML instead of IAM Identity Center requires modifications to your Atmos Auth configuration:

1. Configure profiles for IAM roles — Map Atmos profiles to IAM roles instead of Permission Sets
2. Deploy the aws-saml component — Create the SAML Identity Provider in AWS
3. Configure your IdP — Set up SAML federation in your Identity Provider

Setup

1 Export IdP Metadata

Export a metadata file from your Identity Provider. The process varies by provider:

Google Workspace

1. Open the AWS documentation for GSuite
2. Follow Steps 1 through 7 (the process is the same for any AWS service)
3. Download the metadata file

Okta

1. Create an "Amazon Web Services Account Federation" application in Okta
2. Select "SAML 2.0" from the Sign-On Method
3. View and download the identity provider (IdP) metadata file

For details, see the official Okta documentation.

JumpCloud

Follow the JumpCloud documentation and download the metadata file.

Microsoft Entra ID

The setup for Microsoft Entra ID (formerly Azure AD) has some nuances. See our Microsoft Entra ID guide for detailed instructions.

2 Import the Metadata File

Place the metadata file in your infrastructure repository:

1. Save the file to components/terraform/aws-saml/
2. Update stacks/catalog/aws-saml.yaml to reference the filename
3. Commit to version control

Okta

For Okta, ensure the var.saml_providers map key ends with -okta. This suffix triggers creation of a dedicated IAM user for Okta role discovery:

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

3 Deploy the SAML Integration

Deploy the aws-saml component to your root account:

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

4 Complete IdP Setup

Complete the integration in your Identity Provider:

Okta

Follow the official Okta documentation to complete setup.

Important notes:

• The aws-saml component creates an IAM User for Okta to discover roles. Access keys are stored in AWS SSM Parameter Store.
• In Okta's "Provisioning" tab, check "Update User Attributes" for roles to populate correctly.

5 Configure Atmos Auth for SAML

Update your Atmos Auth configuration to use the SAML provider and IAM roles instead of Permission Sets.

First, define the SAML provider in your atmos.yaml:

# atmos.yaml
auth:
  providers:
    acme-okta:
      kind: aws/saml
      region: us-east-1
      url: https://acme.okta.com/app/amazon_aws/abc123/sso/saml
      idp_arn: arn:aws:iam::123456789012:saml-provider/acme-okta
      driver: Okta  # Options: Browser, GoogleApps, Okta, ADFS

Then, define identities that use the SAML provider. The aws/saml provider requires chaining to an aws/assume-role identity:

# atmos.yaml (continued)
auth:
  identities:
    plat-dev/terraform:
      kind: aws/assume-role
      via:
        provider: acme-okta  # References the SAML provider defined above
      principal:
        assume_role: arn:aws:iam::111111111111:role/acme-plat-gbl-dev-terraform
        session_name: atmos-session

See Atmos Auth Providers and Atmos Auth Identities for detailed configuration options.

6 (Optional) AWS Extend Switch Roles

For easier role-switching in the AWS Console, use the AWS Extend Switch Roles browser extension.

Copy the configuration from rootfs/etc/aws-config in your infrastructure repository into the plugin.

Comparison with IAM Identity Center

Feature	AWS SAML	IAM Identity Center
Setup complexity	Higher	Lower
User experience	Manual role selection	Integrated portal
Multiple IdPs	Supported	Single IdP
Permission management	IAM roles directly	Permission Sets
Atmos Auth support	Yes (aws/saml kind)	Yes (aws/sso kind)
Reference architecture default	No	Yes