Use Atmos identities from the AWS CLI, and credential helpers from Atmos

Tools like aws-sso-util and Granted let you run aws --profile=app-sandbox-1 s3 ls from any directory, because the profile in ~/.aws/config knows how to fetch its own credentials. Move to atmos auth and that convenience goes away: the AWS CLI only gets credentials when you run it through atmos auth exec from inside the Atmos project, and people have filled the gap with shell scripts that eval $(atmos auth env) and re-encode the result as JSON without a correct expiration. The reverse problem exists too. Many organizations already vend temporary AWS credentials through a helper such as okta-aws-cli, aws-sso-cli, or aws-vault, and those credentials never reached Atmos, so those teams could not use atmos auth shell, identity chaining, or the automatic authentication of atmos terraform.

The Problem

Both gaps come from the same missing piece. The AWS CLI and every AWS SDK share one extension point, credential_process: a profile names a command, the SDK runs it, and the command prints a small JSON document with credentials. Atmos Auth did not speak that protocol in either direction.

• Atmos could not be the helper. A profile could not delegate to an Atmos identity, so the AWS CLI, boto3, and other SDK-based tools could not use the sessions you had already established with atmos auth login. The workaround scripts had no reliable way to report when credentials expire.
• Atmos could not consume a helper. An identity could only come from a provider, IAM user keys, or the ambient environment. A command that prints credentials had no place to plug in.

The Fix

Atmos now supports credential_process in both directions.

Use an Atmos identity from the AWS CLI. The new atmos aws credential-process command prints credentials for any Atmos identity in the AWS process-credential format, including a correct Expiration. It reuses cached credentials as long as at least 15 minutes of lifetime remain (raise that with --min-validity), so every aws command stays fast, and it authenticates the identity only when it must. It skips integrations such as ECR login and EKS kubeconfig updates, which remain part of atmos auth login. The same output is available as atmos auth env --format=credential-process.

Use an existing credential helper from Atmos. The new aws/credential-process identity kind runs your helper, uses the credentials it prints exactly as returned, and caches them in Atmos's managed AWS files until they are within 15 minutes of expiring. Because it is a regular identity, it works with atmos auth shell, atmos auth exec, atmos terraform, and identity chaining.

How to Use It

Run aws from any directory

Add a profile to ~/.aws/config that calls Atmos. The --chdir flag makes Atmos behave as if you ran it from the project, so the profile works from anywhere:

~/.aws/config

[profile app-sandbox-1]
credential_process = atmos --chdir=/path/to/infrastructure aws credential-process --identity=app-sandbox-1
region = us-east-1

aws sts get-caller-identity --profile=app-sandbox-1

If the identity uses AWS SSO and your session has expired, the AWS CLI captures the command's output, so Atmos cannot show a prompt or open a browser for you. Instead of hanging, the command fails right away with a hint to log in first. Run atmos auth login --identity=app-sandbox-1 in a terminal, and the profile works again. The command never opens the identity selector either, so name the identity with --identity in the profile (or mark exactly one identity as the default). If the identity lives in an Atmos profile, add Atmos's own --profile flag to the credential_process line. Other ways to point Atmos at your configuration, such as --config-path, ATMOS_CLI_CONFIG_PATH, or a global ~/.atmos/atmos.yaml, are covered in the command reference.

Bring your credential helper into Atmos

Define an identity that runs the helper:

auth:
  identities:
    corp-base:
      kind: aws/credential-process
      credentials:
        credential_process: corp-credential-helper --account=prod
        region: us-east-1

Credentials from a helper are often a base session. Chain an aws/assume-role identity from it to reach the accounts you are allowed to use:

auth:
  identities:
    prod-admin:
      kind: aws/assume-role
      via:
        identity: corp-base
      principal:
        assume_role: arn:aws:iam::111111111111:role/Admin

Atmos runs the helper through the platform shell, as the AWS SDK for Go does, so a command copied from an existing ~/.aws/config profile runs as written and pipes or environment variable expansion work. The helper keeps your terminal for MFA prompts and browser-login instructions when you run Atmos interactively, but it must finish within one minute, so log in with the helper's own tooling first if it needs a browser. Its output is never stored in the keyring, and atmos auth logout clears the cached copy. When the helper returns no expiration, Atmos runs it on every invocation because it cannot know how long the credentials last. For the web console, atmos auth console needs the helper to return temporary credentials with a session token.

Choosing the right identity kind

• Use aws/user for an IAM user with long-lived access keys.
• Use aws/ambient when the environment already provides credentials, such as IRSA, an instance profile, or an ECS task role.
• Use aws/credential-process when a command already prints the credentials you need.

The two directions compose. Atmos can run your helper and then hand the resulting credentials to the AWS CLI through atmos aws credential-process, with a chained role in between.

Get Involved

This work came out of #3248 and #1734. If your helper or profile layout needs something this does not cover, open an issue so we can cover it.