Skip to main content

atmos auth login

Authenticate with a configured identity using SSO, SAML, OIDC, or static credentials. Atmos retrieves and caches short-lived credentials so they can be reused until expiration, avoiding repeated logins for each command.

atmos auth login --help

Usage​

atmos auth login [--identity <name>]

Examples​

# Use default identity (prompts if no default is configured)
atmos auth login

# Interactively select identity (even if default is configured)
atmos auth login --identity

# Use specific identity
atmos auth login --identity admin

# Use short form of identity flag
atmos auth login -i admin

# Interactive selection with short form
atmos auth login -i

Arguments​

n/a
No positional arguments.

Flags​

--identity (alias -i)

Specify the identity to authenticate. This flag has three modes:

  • With value (--identity admin): Use the specified identity
  • Without value (--identity): Force interactive selector, even if a default identity is configured
  • Omitted: Automatic behavior based on configuration:
    • Exactly one default identity: Use it automatically
    • No default identities (interactive): Show selector with all available identities
    • Multiple default identities (interactive): Show selector with only the default identities
    • No/multiple defaults (CI/non-interactive): Return an error

Environment variables: ATMOS_IDENTITY or IDENTITY (checked in that order)

Interactive Identity Selection​

Atmos provides an interactive identity selector in two scenarios:

  1. No default configured: When no --identity flag is provided and no default identity is configured
  2. Explicit request: When using --identity without a value (e.g., atmos auth login --identity)

This allows you to:

  • Quickly choose an identity without remembering exact names
  • Override the default identity temporarily without changing configuration
  • Browse all available identities and make an informed selection

The interactive selector displays all configured identities with arrow key navigation and Enter to confirm. In CI/CD pipelines or non-interactive environments, you must either:

  • Configure a default identity in your atmos.yaml
  • Explicitly specify the identity using --identity <name> or environment variable

Notes​

  • Prints provider, identity, account, region, and expiration when successful.
  • Credentials are cached to avoid repeated logins until expiration.
  • The interactive selector uses arrow keys for navigation and Enter to confirm selection.
  • Using --identity without a value is useful when:
    • You have a default identity configured but want to temporarily use a different one
    • You want to browse available identities before selecting
    • You're working in a team environment with multiple configured identities
  • For AWS SSO (IAM Identity Center), you will see a verification code displayed in the terminal. This is a device authorization user code (e.g., "WDDD-HRQV") that AWS generates for the device flow - this is NOT an MFA token. The code is displayed so you can visually verify it matches what AWS shows in the browser. Any MFA prompts will appear in the browser during authentication.
  • For Azure device code authentication, you will see a similar verification code and URL to complete browser-based authentication. Atmos writes credentials to the Azure CLI MSAL cache, ensuring full compatibility with Terraform's Azure providers (azurerm, azuread, azapi).

Authentication Methods​

Atmos supports multiple authentication methods for different cloud providers:

AWS​

  • IAM Identity Center (SSO)
  • IAM Roles Anywhere (certificate-based)
  • OIDC (GitHub Actions, GitLab CI)
  • Static credentials

See Migrating from Leapp for AWS examples.

Azure​

  • Device Code Flow (browser-based)
  • OIDC (workload identity for CI/CD)
  • Service Principals (client credentials)

See Azure Authentication for detailed Azure configuration.

AWS SSO (IAM Identity Center)​

IAM Permissions for Identity Provisioning​

When using automatic identity provisioning (auto_provision_identities: true), Atmos queries AWS Identity Center APIs during login to discover available permission sets across assigned accounts. This requires specific IAM permissions.

Required IAM Permissions

Basic Provisioning (Required)​

These permissions are required for automatic identity provisioning to work:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "sso:ListAccounts",
        "sso:ListAccountRoles"
      ],
      "Resource": "*"
    }
  ]
}

APIs Used:

  • sso:ListAccounts - Enumerates all AWS accounts the user can access
  • sso:ListAccountRoles - Lists available permission sets (roles) for each account

Tag/Label Support (Optional)​

If you enable tag discovery (include_tags: true in provider configuration), additional permissions are required:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "sso:ListAccounts",
        "sso:ListAccountRoles"
      ],
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "sso:ListInstances",
        "sso:DescribePermissionSet",
        "sso:ListPermissionSets",
        "sso:ListTagsForResource"
      ],
      "Resource": "*"
    }
  ]
}

Additional APIs Used:

  • sso:ListInstances - Finds the SSO instance ARN
  • sso:DescribePermissionSet - Gets permission set details
  • sso:ListPermissionSets - Finds permission set ARNs
  • sso:ListTagsForResource - Retrieves AWS tags from permission sets

How to Apply Permissions​

These permissions should be attached to the IAM Identity Center permission set that users authenticate with, or to the IAM user/role if using static credentials. Without these permissions, identity provisioning will fail gracefully and fall back to manually configured identities.