<AwsAuth>

The <AwsAuth> block provides a streamlined interface for authenticating to AWS. It supports three authentication methods: static credentials, AWS SSO (IAM Identity Center), and local AWS profiles. Once authenticated, credentials are automatically available to subsequent Command and Check blocks.

By default, AwsAuth automatically detects credentials from environment variables. When credentials are detected, the user is prompted to confirm before proceeding, preventing accidental operations against the wrong AWS account.

Basic Usage

<AwsAuth
  id="aws-auth"
  title="Authenticate to AWS"
  description="Choose your preferred authentication method"
  defaultRegion="us-west-2"
/>

By default, AwsAuth checks for existing credentials in environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, etc.). If found, it validates them and prompts the user to confirm before using them.

Authentication Methods

The AwsAuth block provides three ways to authenticate:

Method	Description
Static Credentials	Enter Access Key ID and Secret Access Key directly
AWS SSO	Use AWS IAM Identity Center (formerly AWS SSO)
Local Profile	Use a profile from ~/.aws/credentials

Props

Prop	Type	Default	Description
id	string	required	Unique identifier for this component
title	string	”AWS Authentication”	Display title shown in the UI
description	string	-	Description of the authentication purpose
defaultRegion	string	”us-east-1”	Default AWS region for CLI commands. Sets AWS_REGION environment variable
detectCredentials	false or CredentialSource[]	['env']	Whether and how to detect existing credentials. See Credential Detection
ssoStartUrl	string	-	AWS SSO start URL (e.g., https://my-company.awsapps.com/start). Required for SSO
ssoRegion	string	”us-east-1”	AWS region where IAM Identity Center is configured
ssoAccountId	string	-	Pre-select a specific AWS account after SSO authentication
ssoRoleName	string	-	Pre-select a specific IAM role to assume

Environment Variables

When authentication succeeds, the following environment variables are automatically set for subsequent Command and Check blocks:

Variable	Description
AWS_ACCESS_KEY_ID	The AWS access key
AWS_SECRET_ACCESS_KEY	The AWS secret key
AWS_SESSION_TOKEN	Session token (for temporary credentials from SSO or assume role)
AWS_REGION	The selected default region

These variables are set in the session environment, so all subsequent blocks have access without needing to explicitly reference awsAuthId.

Using with Commands and Checks

When you authenticate to AWS using the AwsAuth block, the environment variables above are automatically made available to all subsequent Command and Check blocks. This means that Command and Check blocks will use the most recently authenticated AwsAuth block (if any) to get AWS authentication credentials.

Any subsequent AWS authentication will update the environment variables and then become the default AWS authentication credentials.

However, in some cases, you may want to use a specific AWS authentication with a block, not just the most recent AWS authentication. To do that, you can reference a specific AwsAuth block from Command or Check blocks using the awsAuthId prop. For example:

<AwsAuth
  id="aws-auth"
  title="Authenticate to AWS"
  defaultRegion="us-west-2"
  ssoStartUrl="https://my-company.awsapps.com/start"
/>

<Check
  id="verify-identity"
  title="Verify AWS Identity"
  command="aws sts get-caller-identity"
  awsAuthId="aws-auth"
  successMessage="Successfully authenticated!"
/>

<Command
  id="list-buckets"
  title="List S3 Buckets"
  command="aws s3 ls"
  awsAuthId="aws-auth"
  successMessage="Buckets listed!"
/>

Tip

While you can use awsAuthId to explicitly reference the AwsAuth block, the credentials are also set as session environment variables. This means subsequent blocks will have AWS access even without awsAuthId, though using it makes the dependency explicit.

Configuration Examples

Pre-selected SSO Account and Role

Skip the account/role selection step by pre-configuring them:

<AwsAuth
  id="aws-auth"
  title="Authenticate to Production"
  ssoStartUrl="https://my-company.awsapps.com/start"
  ssoRegion="us-east-1"
  ssoAccountId="123456789012"
  ssoRoleName="AdministratorAccess"
  defaultRegion="us-west-2"
/>

Multiple AWS Accounts

You can include multiple AwsAuth blocks in a single runbook to authenticate to different AWS accounts:

<AwsAuth
  id="source-account"
  title="Source Account (Development)"
  defaultRegion="us-west-2"
/>

<Command
  id="export-data"
  title="Export Data from Source"
  command="aws s3 cp s3://source-bucket/data.json /tmp/data.json"
  awsAuthId="source-account"
/>

<AwsAuth
  id="target-account"
  title="Target Account (Production)"
  defaultRegion="us-east-1"
/>

<Command
  id="import-data"
  title="Import Data to Target"
  command="aws s3 cp /tmp/data.json s3://target-bucket/data.json"
  awsAuthId="target-account"
/>

Caution

When using multiple AwsAuth blocks, be aware that the session environment variables (AWS_ACCESS_KEY_ID, etc.) will reflect the most recently authenticated credentials. Use awsAuthId to ensure each command uses the correct credentials.

Local Profile Support

The Local Profile tab shows profiles from your ~/.aws/credentials and ~/.aws/config files. Two profile types are supported:

Profile Type	Description
Static Credentials	Profiles with aws_access_key_id and aws_secret_access_key
Assume Role	Profiles that use role_arn to assume a role

Note

SSO profiles configured in ~/.aws/config are not shown in the Local Profile tab. Use the AWS SSO tab instead to authenticate with SSO.

Auto-Detection of Credentials

By default, AwsAuth automatically detects existing credentials from environment variables. When credentials are detected, the user is shown the AWS account ID, account name (if available), and identity (e.g. IAM role), and must confirm before the credentials are used.

Note

Unlike GitHubAuth which auto-authenticates silently, AwsAuth requires explicit user confirmation. Until a user explicitly confirms which AWS account to use, no credentials are available to subsequent blocks. This prevents accidental operations against the wrong AWS account, which could have serious consequences in production environments. See Credential Protection for details.

Default Behavior

With no configuration, AwsAuth checks for credentials in standard AWS environment variables:

{/* Default - same as detectCredentials={['env']} */}
<AwsAuth id="aws-auth" />

If credentials are found and valid, the user sees a confirmation prompt showing:

• AWS Account ID
• AWS Account Name (if available)
• IAM ARN (identity)
• Default Region
• Whether credentials are temporary or static

The user can then choose to “Use These Credentials” or “Use Different Credentials”.

Credential Sources

Source	Description
'env'	Check standard AWS env vars (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, etc.)
{ env: { prefix: 'PREFIX_' } }	Check prefixed env vars (PREFIX_AWS_ACCESS_KEY_ID, etc.)
{ block: 'block-id' }	Use credentials from a Command block’s output

Disable Auto-Detection

Force manual authentication only (no credential detection):

<AwsAuth
  id="aws-auth"
  detectCredentials={false}
/>

Custom Detection with Prefix

Check for the standard AWS environment variables, but with a custom prefix. For example, the following configuration will check for these environment variables:

• PROD_AWS_ACCESS_KEY_ID
• PROD_AWS_SECRET_ACCESS_KEY
• PROD_AWS_SESSION_TOKEN
• PROD_AWS_REGION

<AwsAuth
  id="prod-auth"
  detectCredentials={[{ env: { prefix: 'PROD_' } }]}
/>

Prefixes must follow these rules:

• Uppercase letters, numbers, and underscores only
• Must start with a letter
• Must end with a trailing underscore (e.g., PROD_, MY_APP_)

Test Prefix

To use a different prefix for automated tests (e.g., to avoid conflicts with local credentials), configure env_prefix in your test config file (runbook_test.yml) rather than in the MDX:

runbook_test.yml

steps:
  - block: aws-auth
    env_prefix: CI_  # Checks CI_AWS_ACCESS_KEY_ID, CI_AWS_SECRET_ACCESS_KEY, etc.
    expect: success

This keeps test configuration separate from runtime behavior. See Testing AwsAuth Blocks for details.

From Command Output

Use credentials generated by a previous Command block:

<Command
  id="assume-cross-account"
  path="scripts/assume-role.sh"
  title="Assume Cross-Account Role"
/>

<AwsAuth
  id="cross-account-auth"
  title="Cross-Account Access"
  detectCredentials={[{ block: 'assume-cross-account' }]}
/>

<Command
  id="list-buckets"
  command="aws s3 ls"
  awsAuthId="cross-account-auth"
/>

The Command script should output credentials in standard format:

#!/bin/bash
CREDS=$(aws sts assume-role --role-arn "$ROLE_ARN" --role-session-name runbook)
echo "AWS_ACCESS_KEY_ID=$(echo $CREDS | jq -r '.Credentials.AccessKeyId')" >> "$RUNBOOK_OUTPUT"
echo "AWS_SECRET_ACCESS_KEY=$(echo $CREDS | jq -r '.Credentials.SecretAccessKey')" >> "$RUNBOOK_OUTPUT"
echo "AWS_SESSION_TOKEN=$(echo $CREDS | jq -r '.Credentials.SessionToken')" >> "$RUNBOOK_OUTPUT"
echo "AWS_REGION=us-west-2" >> "$RUNBOOK_OUTPUT"  # Optional: override region

The AWS_REGION output is optional. If not provided, the AwsAuth block’s defaultRegion prop is used.

When Users Reject Auto-Detected Credentials

Auto-detected credentials are never available to scripts until the user confirms them. Auto-detection is read-only. It validates the credentials and shows the user which account they belong to, but does not register them to the session.

When a user clicks “Use Different Credentials” to reject auto-detected credentials:

1. The manual authentication UI is shown (Static Credentials, SSO, or Local Profile tabs)
2. The user must authenticate manually before any commands can access AWS

This ensures that if a user sees credentials for the wrong account (e.g., production when they expected development), those credentials are never used—they were never registered in the first place.

Note that this behavior only applies to the AwsAuth block. If standard AWS environment variables are available and the runbook does not contain any AwsAuth blocks, environment credentials work normally and these AWS credentials will automatically be available to all scripts.

This is one key benefit of the AwsAuth block. It ensures that users are always aware of which AWS account they’re about to operate in before any credentials are registered to the session.

Security

Credential Protection

When a runbook contains any <AwsAuth> blocks, Runbooks automatically strips AWS credentials from the session at startup. This means:

1. Before confirmation: Even if you have AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_SESSION_TOKEN set in your terminal, scripts in the runbook cannot access them until you explicitly confirm which account to use
2. Detection is read-only: When AwsAuth checks for credentials, it reads from your environment but does NOT register them to the session
3. Confirmation registers credentials: Only after you click “Use These Credentials” are the credentials added to the session and available to subsequent scripts

This design prevents a common and dangerous scenario: you have production credentials set in your terminal, open a runbook intending to work in development, and accidentally run scripts against production.

Tip

If your runbook does NOT contain any AwsAuth blocks, environment credentials work normally - they’re available to all scripts. The protection only activates when AwsAuth is present, since that signals the runbook author wants explicit credential management.

Why Confirmation is Required

AWS operations can have significant consequences - creating resources that cost money, modifying production data, or deleting critical infrastructure. Unlike GitHub where most operations are reversible (you can revert commits), AWS operations are often immediate and irreversible.

The confirmation flow ensures users are aware of which AWS account they’re about to operate in before any credentials are registered to the session. This is especially important in environments where:

• Users have access to multiple AWS accounts (dev, staging, production)
• Environment variables might be set by tools like aws-vault or granted
• CI/CD pipelines set credentials that persist across sessions

Credential Handling

• Credentials stay local: All authentication happens between your machine and AWS. Credentials are never transmitted to external servers or to Gruntwork (unless your runbook includes scripts that explicitly do this).
• Session storage: Credentials are stored only in your local Runbooks session and are never persisted to disk.
• Validation before use: Credentials are validated via STS GetCallerIdentity before being registered to the session.
• Protected until confirmed: AWS credentials are stripped from the session at startup when AwsAuth blocks are present, and only added back after explicit user confirmation.

Detailed Example

See the aws-auth feature demo for a good walkthrough of the AwsAuth block.