atmos auth
Atmos Auth gives you a single, consistent way to authenticate with multiple cloud providers. It supports SAML, SSO, OIDC, GitHub Actions, and static user identities. By consolidating these flows into one system, you no longer need to juggle separate tools or browser plugins, just to try to login. And because itβs built into Atmos, it works seamlessly with stacks, components, workflows, shells, and even custom commands.
Usageβ
Examplesβ
# Validate configuration
atmos auth validate
# Authenticate with the default identity
atmos auth login
# Authenticate with a specific identity
atmos auth login --identity admin
# Print environment variables in JSON
atmos auth env --format json
# Execute a command with authentication context
atmos auth exec -- terraform plan
# Show current authentication status
atmos auth whoami
Flagsβ
--identity(alias-i)- Specify the default identity for subcommands. Can be overridden per command.
Subcommandsβ
ποΈ env
Export temporary cloud credentials as environment variables for the selected identity.
ποΈ exec
Execute a command with authentication environment variables set for the selected identity.
ποΈ login
Authenticate to cloud providers using an identity defined in atmos.yaml.
ποΈ user
Manage cloud provider user credentials in the local keychain.
ποΈ user configure
Configure static AWS user credentials and store them securely in your system keychain.
ποΈ validate
Validate the authentication configuration in atmos.yaml for syntax and logical errors.
ποΈ whoami
Show current authentication status for the selected identity.
ποΈ Tutorials
2 items
ποΈ list
List all configured authentication providers and identities with their relationships and chains.
ποΈ shell
Launch an interactive shell with authentication environment variables configured for the selected identity.
ποΈ console
Open cloud provider web console in your default browser using authenticated credentials.
ποΈ logout
Remove locally cached credentials and session data
Overviewβ
Atmos Auth provides a unified authentication system for cloud providers, supporting complex identity chaining and credential management. This guide will help you get started with configuring and using Atmos Auth for your infrastructure projects.
Quick Startβ
1. Basic Configurationβ
Add authentication configuration to your atmos.yaml:
auth:
# Configure logging
## Optional, defaults to Atmos log level
logs:
level: Info
providers:
my-sso:
kind: aws/iam-identity-center
region: us-east-1
start_url: https://mycompany.awsapps.com/start
# Optional: Configure session durations
session:
duration: 1h # Credential lifetime for auth shell/env/exec
console:
session_duration: 12h # Web console session duration (max 12h for AWS)
identities:
admin:
kind: aws/permission-set
default: true
via:
provider: my-sso
principal:
name: AdminAccess
account:
name: production
Notes:
- Region is required for the GitHub OIDC provider and is validated at construction time.
2. Validate Configurationβ
atmos auth validate
3. Authenticateβ
# Use default identity
atmos auth login
# Use specific identity
atmos auth login --identity admin
4. Check Authentication Statusβ
atmos auth whoami
5. Use with Terraformβ
# Atmos automatically handles authentication
atmos terraform plan mycomponent -s dev
Authentication Conceptsβ
Providersβ
Providers are the upstream systems that Atmos Auth uses to obtain initial credentials:
- AWS SSO:
aws/iam-identity-center - AWS SAML:
aws/saml - GitHub OIDC:
github/oidc
Identitiesβ
Identities represent the user accounts or roles available from provider credentials, such as:
- AWS Permission Set:
aws/permission-set - AWS Assume Role:
aws/assume-role - AWS User:
aws/user
Identity Chainingβ
Identity chaining (often called role chaining) is when one identity is used to obtain another, forming a sequence of temporary credentials.
For example, you might:
- Start with an SSO login to obtain base credentials.
- Use those credentials to assume a cross-account role.
- Optionally, chain again into another role with more limited or specialized permissions.
This allows you to:
- Access multiple accounts or environments without long-lived keys.
- Follow least-privilege practices by escalating only as needed.
- Automate complex authentication flows while still relying on short-lived credentials.
You can chain identities to create complex authentication flows like this:
identities:
# Base permission set from SSO
base-admin:
kind: aws/permission-set
via:
provider: my-sso
principal:
name: AdminAccess
account:
name: core-identity
# Cross-account role using base permissions
prod-admin:
kind: aws/assume-role
via:
identity: base-admin # Chain through another identity
principal:
assume_role: arn:aws:iam::999999999999:role/ProductionAdmin
session_name: atmos-prod-access
Configuration Examplesβ
AWS SSO with Permission Setsβ
AWS Permission Set identities assume roles via AWS IAM Identity Center (SSO). The account field specifies which AWS account contains the permission set.
Account Specification Options:
You can specify the account using either:
account.name- Account name/alias (resolved via SSO ListAccounts API)account.id- Numeric account ID (used directly, no lookup required)
Using account names is recommended as it's more readable and maintainable. Account names match the account names/aliases configured in AWS Organizations.
auth:
providers:
company-sso:
kind: aws/iam-identity-center
region: us-east-1
start_url: https://company.awsapps.com/start
identities:
dev-admin:
kind: aws/permission-set
default: true
via:
provider: company-sso
principal:
name: AdminAccess
account:
name: development
# OR use account ID directly:
# id: "123456789012"
prod-readonly:
kind: aws/permission-set
via:
provider: company-sso
principal:
name: ReadOnlyAccess
account:
name: production
AWS SAML Authenticationβ
The aws/saml provider requires the next identity to be of kind aws/assume-role. This is because the assume_role is the chosen role to sign into after the SAML authentication.
auth:
providers:
okta-saml:
kind: aws/saml
region: us-east-1
url: https://company.okta.com/app/amazon_aws/abc123/sso/saml
idp_arn: arn:aws:iam::123456789012:saml-provider/okta-saml
# Optional: Specify SAML driver (Browser, GoogleApps, Okta, ADFS).
# Note: provider_type is deprecated; use driver instead.
# If not specified, Atmos automatically selects the best driver based on:
# 1. Browser (if Playwright drivers are installed)
# 2. Provider-specific fallback (GoogleApps for Google, Okta for Okta, ADFS for ADFS)
# 3. Browser with auto-download
driver: Browser
identities:
saml-admin:
kind: aws/assume-role
default: true
via:
provider: okta-saml
principal:
assume_role: arn:aws:iam::123456789012:role/AdminRole
SAML Driver Optionsβ
The driver field controls how Atmos authenticates with your SAML identity provider:
-
Browser(recommended): Opens your system browser for authentication. Requires Playwright drivers to be installed or enables auto-download when supported.# Install Playwright drivers
go run github.com/playwright-community/playwright-go/cmd/playwright@latest install -
GoogleApps: Uses Google Apps SAML API (no browser needed) -
Okta: Uses Okta SAML API (no browser needed) -
ADFS: Uses Active Directory Federation Services API (no browser needed)
If driver is not specified, Atmos automatically selects the best option based on your SAML URL and available drivers.
GitHub Actions OIDCβ
auth:
providers:
github-oidc:
kind: github/oidc
region: us-east-1 # Required
spec:
audience: sts.us-east-1.amazonaws.com
identities:
github-deploy:
kind: aws/assume-role
default: true
via:
provider: github-oidc
principal:
assume_role: arn:aws:iam::123456789012:role/GitHubActionsRole
AWS User (Break-glass)β
auth:
identities:
emergency-user:
kind: aws/user
credentials:
access_key_id: !env EMERGENCY_AWS_ACCESS_KEY_ID
secret_access_key: !env EMERGENCY_AWS_SECRET_ACCESS_KEY
region: us-east-1
Alternatively
auth:
identities:
emergency-user:
kind: aws/user
credentials:
region: us-east-1
Then run atmos auth user configure to configure the credentials on the keychain. See user configure for details.
CLI Commandsβ
Authentication Commandsβ
# Validate auth configuration
atmos auth validate
atmos auth validate --verbose
# Login (authenticate and cache credentials)
atmos auth login
atmos auth login --identity prod-admin
# Check current authentication status
atmos auth whoami
atmos auth whoami --identity dev-admin
# Get environment variables
atmos auth env
atmos auth env --identity prod-admin --format bash
atmos auth env --format json
atmos auth env --format dotenv
# Execute command with authentication
atmos auth exec --identity prod-admin -- aws sts get-caller-identity
atmos auth exec -- terraform plan
# Configure AWS user credentials
atmos auth user configure
Component-Level Configurationβ
Override authentication settings for specific components:
# In your component configuration
components:
terraform:
myapp:
auth:
identities:
custom-role:
kind: aws/assume-role
via:
provider: my-sso
principal:
assume_role: arn:aws:iam::123456789012:role/MyAppRole
Environment Variable Formatsβ
Bash Formatβ
atmos auth env --format bash
# Output:
export AWS_ACCESS_KEY_ID="AKIA..."
export AWS_SECRET_ACCESS_KEY="..."
export AWS_SESSION_TOKEN="..."
JSON Formatβ
atmos auth env --format json
# Output:
{
"AWS_ACCESS_KEY_ID": "AKIA...",
"AWS_SECRET_ACCESS_KEY": "...",
"AWS_SESSION_TOKEN": "..."
}
Dotenv Formatβ
atmos auth env --format dotenv
# Output:
AWS_ACCESS_KEY_ID=AKIA...
AWS_SECRET_ACCESS_KEY=...
AWS_SESSION_TOKEN=...
Default Identity Handlingβ
A default identity is the one Atmos Auth will use automatically when no specific identity is requested.
- If you configure a single identity and mark it as
default: true, Atmos will always use it without requiring you to pass--identity. - If multiple identities are defined, you can still mark one as default, but youβll need to explicitly choose another when you donβt want the default.
- If no default is set and multiple identities exist, Atmos will require you to specify which identity to use.
This makes workflows simpler because you can avoid passing extra flags for the identity you use most often.
Single Defaultβ
When you have one default identity, it's used automatically:
identities:
admin:
kind: aws/permission-set
default: true # This will be used by default
Multiple Defaultsβ
When multiple defaults exist, Atmos behavior depends on the environment:
Interactive Mode: Prompts you to choose
$ atmos auth whoami
? Multiple default identities found. Please choose one:
βΈ dev-admin
prod-admin
staging-admin
No Defaultsβ
Interactive Mode: Shows all available identities
$ atmos auth whoami
? No default identity configured. Please choose an identity:
βΈ dev-admin
prod-admin
staging-admin
Credential Storageβ
Atmos supports three keyring backends for storing authentication credentials, selectable via configuration:
System Keyring (Default)β
Uses your operating system's native secure credential storage:
- macOS: Keychain
- Linux: Secret Service (GNOME Keyring, KDE Wallet)
- Windows: Windows Credential Manager
# atmos.yaml (optional - this is the default)
auth:
keyring:
type: system
Best for: Personal workstations with OS-level security integration
File Keyringβ
AES-256 encrypted file-based storage with interactive password prompting:
# atmos.yaml
auth:
keyring:
type: file
spec:
path: ~/.atmos/keyring # Optional: custom path
password_env: ATMOS_KEYRING_PASSWORD # Optional: env var name
Best for: Shared environments, servers, or CI/CD pipelines
Default storage location:
- Follows the XDG Base Directory Specification
- Default:
$XDG_DATA_HOME/atmos/keyring(typically~/.local/share/atmos/keyringon Linux/Unix and macOS) - Can be overridden via
ATMOS_XDG_DATA_HOMEorXDG_DATA_HOMEenvironment variables - Custom path can be specified via
spec.pathconfiguration
Password resolution order:
- Environment variable (
ATMOS_KEYRING_PASSWORDor custom frompassword_env) - Interactive prompt (if TTY available)
- Error if neither available
# Interactive mode - prompts for password
atmos auth login --identity prod-admin
# Automation mode - password from environment
export ATMOS_KEYRING_PASSWORD="my-secure-password"
atmos auth login --identity prod-admin
# Custom XDG data directory
export ATMOS_XDG_DATA_HOME=/custom/data
atmos auth login --identity prod-admin
Memory Keyringβ
In-memory storage with no persistence (credentials lost on exit):
# atmos.yaml
auth:
keyring:
type: memory
Best for: Unit tests, integration tests, and temporary credential caching
Note: Can also be set via ATMOS_KEYRING_TYPE environment variable
Credential Expirationβ
- Credentials are automatically refreshed when expired
- You can check expiration with
atmos auth whoami - Manual refresh:
atmos auth login --identity <name>
AWS File Managementβ
Atmos manages AWS credential files separately from your personal AWS configuration, following the XDG Base Directory Specification.
This design avoids common problems:
-
No risk of overwriting personal config: Atmos never modifies
~/.aws/credentialsor~/.aws/config. This prevents accidental overrides of credentials you manage yourself and keeps your personal AWS setup intact. -
Provider isolation: Each provider's credentials live under the Atmos namespace (e.g.,
~/.config/atmos/aws/<provider>/on Linux), making it safe and easy to switch between SSO, SAML, OIDC, or static identities without conflicts. -
Seamless SDK integration: Under the hood, Atmos sets the standard AWS SDK environment variables (
AWS_SHARED_CREDENTIALS_FILE,AWS_CONFIG_FILE) so tools that already rely on the AWS SDK (like Terraform, AWS CLI, CDK) just work without extra setup. -
Project convenience: Since all configuration lives under Atmos, every project is self-contained. You don't have to share custom AWS config steps with teammates, and you can cleanly delete all credentials or config associated with a profile at any time.
-
XDG compliance: Atmos follows platform conventions, storing credentials in standard locations that respect
$XDG_CONFIG_HOMEand$ATMOS_XDG_CONFIG_HOMEenvironment variables.
This makes authentication more secure, more portable across projects, and less error-prone in day-to-day development.
File Locationsβ
Atmos-managed AWS credentials are stored following the XDG Base Directory Specification:
Linux:
- Credentials:
~/.config/atmos/aws/<provider>/credentials - Config:
~/.config/atmos/aws/<provider>/config
macOS:
- Credentials:
~/.config/atmos/aws/<provider>/credentials - Config:
~/.config/atmos/aws/<provider>/config
Windows:
- Credentials:
%APPDATA%\atmos\aws\<provider>\credentials - Config:
%APPDATA%\atmos\aws\<provider>\config
Custom Locations:
You can override the default location using environment variables:
# Override for Atmos only
export ATMOS_XDG_CONFIG_HOME=/custom/path
# Override for all XDG-compliant tools
export XDG_CONFIG_HOME=/custom/path
Or configure per-provider in atmos.yaml:
auth:
providers:
my-sso:
kind: aws/iam-identity-center
# ... other config ...
spec:
files:
base_path: /custom/path/aws
Environment Variablesβ
- Your files remain untouched
- Your existing
~/.aws/credentialsand~/.aws/configare never modified - Atmos uses separate files to avoid conflicts
- Standard AWS environment variables are set to point to Atmos-managed files
Troubleshootingβ
Common Issuesβ
Configuration Validation Errors
atmos auth validate --verbose
Authentication Failures
# Check current status
atmos auth whoami
# Re-authenticate
atmos auth login --identity <name>
# Check with verbose output
atmos auth login --identity <name> --verbose
Permission Errors
# Verify identity configuration
atmos auth validate
# Check assumed role/permissions
atmos auth exec --identity <name> -- aws sts get-caller-identity
Environment Variable Issues
# Check what variables are set
atmos auth env --identity <name>
# Test environment
atmos auth exec --identity <name> -- env | grep AWS
Debug Modeβ
Enable debug logging for detailed troubleshooting:
# Verbose CLI output
atmos auth validate --verbose
atmos auth login --identity <name> --verbose
# Set log level explicitly
ATMOS_LOG_LEVEL=Debug atmos auth whoami
Logs Configurationβ
Configure logging in atmos.yaml:
auth:
logs:
level: Debug # Debug, Info, Warn, Error
file: /tmp/atmos-auth.log
Workflows Integrationβ
Use Atmos Auth in workflows:
# atmos.yaml workflows section
workflows:
deploy:
description: Deploy with authentication
steps:
- name: validate-auth
command: atmos auth validate
- name: deploy-dev
command: atmos terraform apply myapp -s dev
identity: dev-admin
- name: deploy-prod
command: atmos terraform apply myapp -s prod
identity: prod-admin
CI/CD Integrationβ
GitHub Actionsβ
- name: Configure AWS credentials
run: |
# Atmos handles authentication automatically in CI
atmos auth whoami
- name: Deploy infrastructure
run: |
atmos terraform apply myapp -s prod
GitLab CIβ
deploy:
script:
- atmos auth validate
- atmos terraform apply myapp -s prod
Security Best Practicesβ
Credential Managementβ
- Never commit credentials to version control
- Use environment variables for sensitive data:
!env VAR_NAME - Regularly rotate credentials
- Use least-privilege access
Configuration Securityβ
- Validate configurations regularly:
atmos auth validate - Use specific account IDs in permission sets
- Implement proper session naming for audit trails
- Monitor authentication logs
Environment Isolationβ
- Use different identities for different environments
- Separate providers for different security domains
- Implement proper identity chaining for cross-account access