Configuring Geodesic with Atmos Auth

Note: atmos auth requires minimum Atmos version v1.195.0

This guide explains how to configure Geodesic to work with atmos auth for AWS authentication using IAM Identity Center.

Overview

Geodesic is Cloud Posse's DevOps toolbox - a containerized environment with pre-installed cloud tools. When using atmos auth, you authenticate on your host machine (laptop/workstation) before starting Geodesic, then mount the Atmos-managed credentials into the container.

How Authentication Works

1. Authentication happens on the host - You run atmos auth login on your laptop before starting Geodesic
2. Browser-based SSO flow - Opens your browser for IAM Identity Center authentication
3. Credentials stored on host - Atmos saves credentials following XDG Base Directory Specification at ~/.config/atmos/aws/ (all platforms)
4. Geodesic mounts credentials - The container accesses credentials via volume mounts from ~/.config
5. Override Geodesic's XDG paths - Set ATMOS_XDG_CONFIG_HOME=$HOME/.config to ensure credentials are stored in mounted directories
6. Keychain integration - On macOS, Atmos can optionally store refresh tokens in Keychain (host-only, not available inside containers)

Prerequisites

• Geodesic toolbox set up for your infrastructure
• atmos.yaml configured with auth providers and identities
• Understanding of Geodesic's Dockerfile and Makefile structure
• Atmos installed on your host machine (laptop/workstation) for authentication

Keychain Integration

Atmos can optionally store refresh tokens in your operating system's keyring (macOS Keychain, Linux Secret Service, Windows Credential Manager) using atmos auth user configure. However, this keyring integration is only available on the host machine. Inside the Geodesic container, Atmos will use file-based credential storage following XDG conventions (e.g., ~/.config/atmos/aws/ in the container). See Credential Storage for details.

Configuration Steps

1. Update Your Geodesic Dockerfile

Add the following environment variables to your Geodesic Dockerfile to configure the default identity:

# Atmos auth configuration
# Set the default identity to use when launching Geodesic
ENV ATMOS_IDENTITY="acme-identity"

That's it! Atmos handles AWS credential management automatically. You do not need to set:

• ❌ AWS_SHARED_CREDENTIALS_FILE - Atmos manages this
• ❌ AWS_CONFIG_FILE - Atmos manages this
• ❌ AWS_PROFILE - Atmos manages this

Key Configuration Details:

• ATMOS_IDENTITY: The default identity to use (must match an identity in your atmos.yaml)

How Atmos Auth Works in Geodesic

When you run Atmos commands inside Geodesic, Atmos automatically:

1. Loads credentials from XDG-compliant paths (mounted from your host via ~/.config)
2. Sets up AWS SDK configuration to use the correct provider and identity
3. Manages the AWS profile internally

You should NOT manually set AWS environment variables like AWS_SHARED_CREDENTIALS_FILE or AWS_CONFIG_FILE. Setting these prevents Atmos from managing credentials properly and defeats the purpose of using atmos auth.

Legacy Setup Migration

If your Dockerfile currently sets AWS_SHARED_CREDENTIALS_FILE, AWS_CONFIG_FILE, or AWS_PROFILE, remove them. These are legacy configurations that conflict with Atmos auth's credential management.

2. Update Your Makefile

Add an automatic login step to your Makefile to ensure users are authenticated before starting the Geodesic shell:

login:
	@atmos auth login --identity acme-identity

...

## Start the geodesic shell by calling wrapper script
run: login
	@$(APP_NAME)

This ensures that:

• Users authenticate with Atmos before the shell starts
• The specified identity is used for authentication
• Credentials are fresh when starting work

3. Configure XDG Paths for Geodesic

Important: Geodesic sets system-wide XDG environment variables (XDG_CONFIG_HOME=/etc/xdg_config_home) that conflict with Atmos credential storage. You need to override these to use your home directory instead.

Add these environment variables to your Geodesic Dockerfile or your shell profile:

# Override Geodesic's system XDG paths to use home directory
# This ensures Atmos credentials are stored in mounted directories
ENV ATMOS_XDG_CONFIG_HOME=$HOME/.config
ENV ATMOS_XDG_DATA_HOME=$HOME/.local/share
ENV ATMOS_XDG_CACHE_HOME=$HOME/.cache

Or add to your shell profile (~/.zshrc, ~/.bashrc, etc.):

export ATMOS_XDG_CONFIG_HOME="$HOME/.config"
export ATMOS_XDG_DATA_HOME="$HOME/.local/share"
export ATMOS_XDG_CACHE_HOME="$HOME/.cache"

Why This Is Needed

Geodesic sets XDG_CONFIG_HOME=/etc/xdg_config_home for system tools installed in the container. However, this directory is not mounted to your host machine. User credentials need to be stored in directories that Geodesic automatically mounts (like ~/.config).

The ATMOS_XDG_* environment variables tell Atmos to use your home directory instead of Geodesic's system directories, ensuring credentials persist across container restarts.

Geodesic Default Mounts

Geodesic automatically mounts these directories from your home directory:

• ~/.aws
• ~/.config ← Atmos credentials stored here (when using ATMOS_XDG_CONFIG_HOME)
• ~/.ssh
• ~/.kube
• ~/.terraform.d

By setting ATMOS_XDG_CONFIG_HOME=$HOME/.config, Atmos stores credentials at ~/.config/atmos/aws/ which gets automatically mounted into Geodesic.

Migrating from Legacy Path

If you're migrating from an older Atmos version that used ~/.aws/atmos/, re-authenticate to move credentials to the new XDG-compliant location:

# Inside Geodesic or on your host
atmos auth login

This will create credentials at ~/.config/atmos/aws/<provider>/ which Geodesic automatically mounts.

Note: We do not recommend setting ATMOS_XDG_CONFIG_HOME="$HOME/.aws" as this affects all Atmos XDG paths (config, cache, data), not just AWS credentials. If you need to customize only the AWS credentials location, use the provider's base_path configuration in atmos.yaml instead.

4. Update Source Profile Configuration

For assume-role and other Geodesic utilities to work correctly, update your source_profile in the {Repo Root}/etc/aws-config/aws-config-teams file to match the identity name from your atmos.yaml auth configuration.

Example:

If your atmos.yaml defines:

auth:
  identities:
    acme-identity:
      kind: aws/permission-set
      # ...

Then your aws-config-teams should reference:

[profile some-role]
source_profile = acme-identity
role_arn = arn:aws:iam::123456789012:role/SomeRole

Complete Example

Here's a complete example showing how all the pieces fit together:

atmos.yaml

auth:
  providers:
    acme-sso:
      kind: aws/iam-identity-center
      region: us-east-1
      start_url: https://acme.awsapps.com/start/

  identities:
    acme-identity:
      default: true
      kind: aws/permission-set
      via:
        provider: acme-sso
      principal:
        name: "IdentityDevopsTeamAccess"
        account:
          name: "core-identity"

Dockerfile (Geodesic)

FROM cloudposse/geodesic:latest

# Override Geodesic's system XDG paths to use home directory
# This ensures Atmos credentials are stored in mounted directories
ENV ATMOS_XDG_CONFIG_HOME=$HOME/.config
ENV ATMOS_XDG_DATA_HOME=$HOME/.local/share
ENV ATMOS_XDG_CACHE_HOME=$HOME/.cache

# Atmos auth configuration
ENV ATMOS_IDENTITY="acme-identity"

# Geodesic AWS configuration for assume-role
ENV AWS_CONFIG_TEAMS=/etc/aws-config/aws-config-teams
ENV ASSUME_ROLE_INTERACTIVE_QUERY=${NAMESPACE}${TENANT:+-$TENANT}-gbl-

# Your other Geodesic configuration...

Makefile

APP_NAME := your-geodesic-shell

login:
	@atmos auth login --identity acme-identity

run: login
	@$(APP_NAME)

etc/aws-config/aws-config-teams

[profile acme-identity]
# This is the base identity managed by Atmos

[profile dev-admin]
source_profile = acme-identity
role_arn = arn:aws:iam::111111111111:role/DevAdmin
region = us-east-1

[profile prod-readonly]
source_profile = acme-identity
role_arn = arn:aws:iam::222222222222:role/ProdReadOnly
region = us-east-1

Workflow

Once configured, the typical workflow is:

1. Start Geodesic (on your laptop): Run make run
2. Authenticate (on your laptop): Atmos runs atmos auth login on your host machine, opens your browser for SSO
3. Credentials mounted: Once authenticated, Geodesic starts with credentials mounted from ~/.config/atmos/ (all platforms)
4. Work in Shell (inside Geodesic): Use AWS CLI, Terraform, and other tools normally
5. Assume Roles (inside Geodesic): Use assume-role dev-admin to switch to other roles

Important Notes

• Authentication is host-based: You cannot run atmos auth login inside the Geodesic container - it requires browser access on your laptop
• Credentials are mounted: The Atmos config directory from your laptop is mounted into Geodesic following XDG conventions
• Keychain not available in container: macOS Keychain integration works only on the host, not inside Geodesic
• Session duration: Authentication persists for the duration configured in IAM Identity Center (typically 1-12 hours)

Troubleshooting

Issue: "Credentials not found" error

Cause: Atmos hasn't authenticated yet, or credentials have expired.

Solution: Exit Geodesic and run atmos auth login on your host machine to re-authenticate. Remember, authentication must happen on your laptop, not inside the container.

Issue: assume-role not finding source profile

Cause: The source_profile in aws-config-teams doesn't match the identity name in atmos.yaml.

Solution: Ensure the profile names match exactly:

# atmos.yaml
identities:
  acme-identity:  # ← This name

# aws-config-teams
[profile some-role]
source_profile = acme-identity  # ← Must match exactly

Issue: Credentials stored in /etc/xdg_config_home instead of ~/.config

Cause: Geodesic's system-wide XDG environment variables are overriding Atmos defaults.

Solution: Set ATMOS_XDG_CONFIG_HOME to override Geodesic's system paths:

# Add to Dockerfile or shell profile
export ATMOS_XDG_CONFIG_HOME="$HOME/.config"
export ATMOS_XDG_DATA_HOME="$HOME/.local/share"
export ATMOS_XDG_CACHE_HOME="$HOME/.cache"

Verify the credentials are now in the correct location:

ls -la ~/.config/atmos/aws/
# Should show your provider directories (e.g., acme-sso/)

Next Steps

• Learn about authentication workflows
• Explore component-level authentication
• Review the Leapp migration guide if migrating

Getting Help

If you encounter issues:

1. Run atmos auth validate --verbose to check configuration
2. Check the User Guide for common scenarios
3. Verify your IAM Identity Center configuration is correct
4. Review Geodesic logs for authentication errors

---

Ready to configure? Start by updating your Dockerfile with the environment variables above, then rebuild your Geodesic container.