How to Log into AWS

Locally authenticating with Atmos Auth and AWS Identity Center (AWS SSO).

NOTE:

Leapp is no longer used for authentication. If you see references to Leapp in older documentation, they are deprecated. We now use Atmos Auth for AWS authentication.

Requirements

Atmos Auth is built into the Atmos CLI, so no additional tools are required beyond what's already in the project.

Setting Your Profile

Before authenticating, you need to set your profile to match your team role. Profiles are located in the profiles/ directory:

1. developers — For developers team members
2. devops — For DevOps team members
3. managers — For managers team members

Setting the Profile

Set the ATMOS_PROFILE environment variable to your team's profile:

export ATMOS_PROFILE=developers  # or devops, managers

To make this persistent, add the export command to your shell configuration file:

1. zsh — Add to ~/.zshrc
2. bash — Add to ~/.bashrc or ~/.bash_profile
3. fish — Add to ~/.config/fish/config.fish (use set -gx ATMOS_PROFILE developers)

After adding to your shell config, reload it:

source ~/.zshrc  # or source ~/.bashrc

NOTE:

If you only run the export command without adding it to your config file, it will only apply to your current session.

The profile determines which permissions and identities are available to you. Identities follow the format <account>/<permission-set> and include:

1. Terraform identities — plat-dev/terraform, core-identity/terraform - Used automatically by Atmos for Terraform operations
2. Permission set identities — plat-dev/ReadOnlyAccess, plat-prod/AdministratorAccess - Used for AWS CLI and console access

Authentication

Authentication with Atmos Auth is simple and streamlined. The authentication configuration is already set up in atmos.yaml and your selected profile.

Quick Login

To authenticate with AWS, run:

atmos auth login --provider sso

This will:

1. Use your configured profile — Determine the appropriate identity
2. Open your browser — Navigate to the AWS SSO login page
3. Authenticate with your IdP — Sign in with your organization credentials
4. Store credentials securely — Save to your system keychain
5. Set up AWS credentials — Configure access to the infrastructure

No need to specify an identity - your profile handles that automatically!

Check Authentication Status

To verify you're authenticated and see your current session details:

atmos auth whoami

This will show you:

1. Identity — Which identity you're using
2. Account and role — The AWS account and role
3. Expiration — Credential expiration time

Daily Workflow

Your typical workflow with Atmos is simple and straightforward.

Using Atmos CLI (Recommended)

With Atmos Auth, you can run Atmos commands directly on your local machine. Once you've authenticated with atmos auth login and selected an identity, Atmos will automatically use your credentials and select the appropriate identity for each stack.

Run Terraform commands:

# Plan a terraform component
atmos terraform plan vpc -s plat-ue1-dev

# Apply a terraform component
atmos terraform apply vpc -s plat-ue1-dev

Launch AWS Console in browser:

atmos auth console --identity plat-dev/ReadOnlyAccess

Run a specific AWS CLI command:

# Execute a single AWS CLI command with read-only access
atmos auth exec --identity plat-dev/ReadOnlyAccess -- aws sts get-caller-identity

# List S3 buckets in production with admin access
atmos auth exec --identity plat-prod/AdministratorAccess -- aws s3 ls

Start an interactive shell with a specific identity:

# Open a shell session for running multiple commands
atmos auth shell --identity core-security/PowerUserAccess

# Exit the shell with Ctrl+D or type 'exit'

List all available identities:

atmos auth list

tip

Atmos will automatically select the correct identity for the stack you're working with. You can override this with the --identity flag if needed.

Using Geodesic (Optional)

If you prefer a containerized development environment with all tools pre-configured, you can use Geodesic:

First time setup:

make all

Subsequent launches:

make run

When to use Geodesic:

1. Containerized environment — You prefer a containerized development environment
2. Pre-configured tools — You want all tools pre-configured without managing versions locally
3. Persistent shell — You're working on multiple components and want a persistent shell session
4. Multiple projects — You're working across multiple projects with different tool requirements
5. Kubernetes access — You need to set up Kubernetes access with the set-cluster script

When to use direct Atmos:

1. Quick commands — You're running quick one-off commands
2. Local integration — You want to integrate Atmos into your local scripts or workflows
3. Local machine — You prefer working directly on your local machine

Both approaches work seamlessly with Atmos Auth!

Additional Information

For more details about Atmos Auth, including advanced features like identity chaining, multiple identities, and troubleshooting, see the Atmos Auth documentation.