# Configuring Geodesic with Atmos Auth

> **Note**: `atmos auth` requires minimum Atmos version `v1.195.0`

This guide explains how to configure [Geodesic](https://github.com/cloudposse/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

:::note 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](/cli/configuration/auth/keyring) for details.
:::

## Configuration Steps

### 1. Update Your Geodesic Dockerfile

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

```dockerfile
# 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`)

:::note 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`.
:::

:::tip 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:

```makefile
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:

```dockerfile
# 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.):

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

:::note 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.
:::

:::note 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.
:::

:::warning 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:

```bash
# 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:

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

Then your `aws-config-teams` should reference:

```ini
[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

```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)

```dockerfile
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

```makefile
APP_NAME := your-geodesic-shell

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

run: login
	@$(APP_NAME)
```

### etc/aws-config/aws-config-teams

```ini
[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:

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

```ini
# 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:

```bash
# 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:

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

## Next Steps

- Learn about [authentication workflows](/cli/commands/auth/usage)
- Explore [component-level authentication](/cli/configuration/auth/identities#component-level-overrides)
- Review the [Leapp migration guide](/tutorials/migrating-from-leapp) if migrating

## Getting Help

If you encounter issues:

1. Run `atmos auth validate --verbose` to check configuration
2. Check the [User Guide](/cli/commands/auth/usage) 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.