Skip to content

2025-10-18-keyring-backends.mdx

Latest commit

 

History

History
274 lines (204 loc) · 8.06 KB

2025-10-18-keyring-backends.mdx

File metadata and controls

274 lines (204 loc) · 8.06 KB
slug flexible-keyring-backends
title Flexible Keyring Backends: System, File, and Memory Storage for Credentials
authors
aknysh
tags
feature
security
release v1.196.0

Atmos Auth supports flexible keyring backends, giving you control over how authentication credentials are stored. Use your system keyring for native OS integration, file-based keyrings to share credentials across OS boundaries (like between your Mac and a Docker container), or memory keyrings for testing.

Why Different Keyring Types Matter

Different environments have different credential storage needs:

System keyrings are great for personal workstations, where OS-native security (macOS Keychain, Windows Credential Manager, Linux Secret Service) provides tight integration with your operating system.

File-based keyrings solve cross-boundary problems. When you're working across OS boundaries—like developing on macOS but running commands in a Docker container, or using a Dev Container in VS Code—your system keyring isn't accessible inside the container. A file-based keyring can be mounted into the container, giving you seamless credential access across both environments.

Memory keyrings are perfect for testing and CI/CD, where you need fast, isolated credential storage without external dependencies or security concerns.

Flexible Keyring Backends

Atmos now supports three keyring backends, selectable via configuration or environment variable:

1. System Keyring (Default)

OS-native secure credential storage using your operating system's built-in keyring. This is the default and requires no configuration.

# atmos.yaml (optional - this is the default)
auth:
  keyring:
    type: system

Best for: Personal workstations where OS-level security is preferred.

Features:

  • ✅ OS-native secure storage
  • ✅ Integration with system password managers
  • ❌ Cannot list all stored credentials (API limitation)
  • ❌ May not be available in CI/headless environments

2. File Keyring

Encrypted file-based storage using 99designs/keyring with interactive password prompting via Charm Bracelet's huh library.

# atmos.yaml
auth:
  keyring:
    type: file
    spec:
      path: ~/.atmos/keyring  # Optional: custom path
      password_env: ATMOS_KEYRING_PASSWORD  # Optional: env var for password

Best for: Shared environments, servers, or when you need portability across different machines.

Features:

  • ✅ AES-256 encryption
  • ✅ Cross-platform (works anywhere)
  • ✅ Supports listing all stored credentials
  • ✅ Interactive password prompting (with huh)
  • ✅ Automation-friendly (password via environment variable)
  • ⚠️ Requires password management

Password Resolution:

  1. Check ATMOS_KEYRING_PASSWORD environment variable (or custom env var from password_env)
  2. Prompt interactively if TTY is available (using Charm Bracelet's secure input)
  3. Error if neither is available

Example Usage:

# Interactive mode - you'll be prompted 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

3. Memory Keyring (Testing Only)

In-memory credential storage with no persistence. Credentials are lost when the process exits.

# atmos.yaml (or set ATMOS_KEYRING_TYPE=memory)
auth:
  keyring:
    type: memory

Best for: Unit tests, integration tests, and CI/CD pipelines where you need fast, isolated credential storage without external dependencies.

Features:

  • ✅ No external dependencies
  • ✅ Thread-safe concurrent access
  • ✅ Supports listing all stored credentials
  • ✅ Perfect for testing
  • ⚠️ Not persistent (ephemeral)
  • ⚠️ Not encrypted (testing only!)

CI/CD Example:

# .github/workflows/test.yml
env:
  ATMOS_KEYRING_TYPE: memory

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run Auth Tests
        run: go test ./pkg/auth/...

Configuration Priority

Keyring backend selection follows this priority order:

  1. ATMOS_KEYRING_TYPE environment variable (highest priority - great for testing)
  2. auth.keyring.type in atmos.yaml (explicit configuration)
  3. Default to system (backward compatibility)

This means you can override the configured backend for testing:

# Override to memory keyring for this session
export ATMOS_KEYRING_TYPE=memory
atmos auth login --identity test-identity

Real-World Use Cases

Personal Development

Use the default system keyring for secure, OS-integrated credential storage:

# atmos.yaml (no keyring config needed)
auth:
  providers:
    my-sso:
      kind: aws/iam-identity-center
      region: us-east-1
      start_url: https://mycompany.awsapps.com/start

Your credentials are stored in macOS Keychain, Windows Credential Manager, or Linux Secret Service.

Docker / Dev Container Development

Use file keyring to share credentials between your host machine and containers:

# atmos.yaml
auth:
  keyring:
    type: file
    spec:
      path: ~/.atmos/keyring
      password_env: ATMOS_KEYRING_PASSWORD

Mount the keyring into your container:

# docker-compose.yml or devcontainer.json
volumes:
  - ~/.atmos/keyring:/root/.atmos/keyring:ro

Now credentials authenticated on your Mac are available inside your Docker container. Your system keyring isn't accessible across the OS boundary, but the file-based keyring is.

CI/CD Pipeline

Use memory keyring for fast, isolated testing without external dependencies:

# .github/workflows/integration.yml
env:
  ATMOS_KEYRING_TYPE: memory

jobs:
  integration-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run Integration Tests
        run: |
          # Tests use memory keyring - fast, isolated, no dependencies
          go test ./pkg/auth/...

Local Testing

Override the configured backend for local testing:

# Test with memory keyring (no persistence)
ATMOS_KEYRING_TYPE=memory atmos auth login --identity test

# Test with file keyring
ATMOS_KEYRING_TYPE=file ATMOS_KEYRING_PASSWORD=test atmos auth login --identity test

Security Considerations

System Keyring

  • Credentials protected by OS-level security
  • Access controlled by OS permissions
  • Password prompts managed by OS

File Keyring

  • AES-256 encryption
  • File permissions: 0600 (user read/write only)
  • Password never logged or stored
  • Password required for each process (or from environment variable)

Memory Keyring

  • ⚠️ NOT for production use
  • No encryption (plain text in memory)
  • No persistence (ephemeral)
  • Perfect for testing where security is not a concern

What This Gives You

  • Cross-boundary credential access: Use file-based keyrings to share credentials between your host and Docker/Dev containers
  • Flexible storage: Choose the backend that fits your environment—system keyring for personal use, file keyring for portability, memory keyring for testing
  • CI/CD friendly: Run auth tests reliably without system keyring dependencies

Try It Out

The keyring backend system is available now. To use memory keyring for testing:

export ATMOS_KEYRING_TYPE=memory
atmos auth login --identity your-identity

To use file keyring:

# atmos.yaml
auth:
  keyring:
    type: file
    spec:
      password_env: ATMOS_KEYRING_PASSWORD

Then set the password and authenticate:

export ATMOS_KEYRING_PASSWORD="your-secure-password"
atmos auth login --identity your-identity

Get Involved

We'd love to hear your feedback! If you have questions or suggestions:

This feature improves testing reliability, enables new deployment patterns, and gives teams more control over credential storage without sacrificing security.