<AwsAuth>

The <AwsAuth> block authenticates the user to AWS with static credentials, AWS SSO (IAM Identity Center), or a local AWS profile. Once authenticated, the credentials are available to later Command and Check blocks.

By default, AwsAuth detects credentials in environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and so on), validates them, and asks the user to confirm the account before using them.

Basic usage

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

Authentication methods

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

Static Credentials is the tab users land on. Set defaultTab to open on a different one:

<AwsAuth
  id="aws-auth"
  defaultTab="sso"
  ssoStartUrl="https://my-company.awsapps.com/start"
/>

The user can still switch tabs. defaultTab only chooses the starting one.

Props

Prop	Type	Default	Description
id	string	required	Unique identifier for this component
inputsId	string or string[]	-	ID of one or more Inputs blocks. title and description resolve {{ .inputs.VarName }} expressions against them
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. GovCloud regions (us-gov-east-1, us-gov-west-1) are supported. When the credentials don’t name a region themselves, this region also decides which partition (commercial or GovCloud) they are validated in
defaultTab	'credentials', 'sso', or 'profile'	'credentials'	Which authentication tab the block opens on. An unrecognized value falls back to 'credentials'
detectCredentials	false or CredentialSource[]	['env']	Whether and how to detect existing credentials. See Credential detection
ssoStartUrl	string	-	AWS SSO start URL (for example https://my-company.awsapps.com/start). Required for SSO
ssoRegion	string	“us-east-1”	AWS region where IAM Identity Center is configured. Every SSO call goes to this region. For a GovCloud Identity Center this is us-gov-east-1 or us-gov-west-1
ssoAccountId	string	-	Pre-select a specific AWS account after SSO authentication. Takes effect only together with ssoRoleName
ssoRoleName	string	-	Pre-select a specific IAM role to assume. Takes effect only together with ssoAccountId

AWS partitions

Credentials are validated in the partition their region belongs to: the commercial partition, GovCloud (US), China, the European Sovereign Cloud, or an isolated (ISO) partition. The region picker lists commercial and GovCloud regions. A region in any other partition works when it comes from the environment’s credentials, a profile’s region, or a block’s AWS_REGION output, and is validated against that partition’s own STS endpoint.

Environment variables

When authentication succeeds, these environment variables are set for later 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

They are set in the session environment, so later blocks get them without setting awsAuthId.

Using with Commands and Checks

A Command or Check block that doesn’t set awsAuthId uses the session environment, which has the credentials of the most recently authenticated AwsAuth block. Each new sign-in replaces them.

Clicking Re-authenticate on the success card withdraws the block’s credentials, so blocks that reference it with awsAuthId (below) report it as not authenticated until the user signs in again. The session environment variables keep their previous values until the next sign-in replaces them.

To make a Command or Check block use one specific AwsAuth block, regardless of which signed in last, set awsAuthId:

<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!"
/>

Pre-selecting the SSO account and role

After the user approves the sign-in in their browser, AwsAuth lists the AWS accounts they can access and asks them to pick an account and then a role. If they can access exactly one account with exactly one role, that role is used without asking.

To skip the account and role selection, set both ssoAccountId and ssoRoleName. Setting only one has no effect.

<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

A runbook can have several AwsAuth blocks, one per AWS account:

<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

With several AwsAuth blocks, the session environment variables hold the most recently authenticated credentials. Set awsAuthId on each command so it runs against the account you intend.

Local profile support

The Local Profile tab shows profiles from your ~/.aws/credentials and ~/.aws/config files, or from the files that AWS_SHARED_CREDENTIALS_FILE and AWS_CONFIG_FILE point to. The files are read the way the AWS CLI reads them: [profile staging] in config and [staging] in credentials are one profile, so keys in one file and a region in the other work together. Two profile types are supported:

Profile type	Description
Static Credentials	Profiles with aws_access_key_id and aws_secret_access_key
Assume Role	Profiles with a role_arn and either a source_profile or a credential_source

Other profile types, such as credential_process profiles, are not listed.

Refresh profiles re-reads both files. The selected profile stays selected as long as it is still listed.

A profile’s own region is the one its credentials are validated in and the one set as AWS_REGION. A profile that sets no region uses the region selected in the block instead, so pick a us-gov-* region for a GovCloud profile without one.

Note

SSO profiles (those with sso_session or sso_start_url) are not shown in the Local Profile tab. Use the AWS SSO tab instead to authenticate with SSO.

Credential detection

By default, AwsAuth detects existing credentials in environment variables. It shows the user the AWS account ID, the account name if available, and the identity (for example an IAM role). The user must confirm before the credentials are used.

Note

GitHubAuth uses detected credentials without asking. AwsAuth waits for the user to confirm an account, and until then no credentials are available to later blocks. See Credential protection.

Default behavior

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

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

If credentials are found and valid, the confirmation prompt shows:

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

The region comes from AWS_REGION, then AWS_DEFAULT_REGION, then the block’s defaultRegion. It is the value set as AWS_REGION once the user confirms, and it decides the partition the credentials are validated in, so GovCloud keys need a us-gov-* region. If none of the three is set, detection reports an error instead of assuming a region.

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

When the user clicks “Use These Credentials”, AwsAuth reads and validates the environment’s credentials again before setting them in the session. If they now belong to a different AWS account than the prompt showed, the prompt switches to that account and the user has to confirm again.

Credential sources

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

Disabling detection

To show only the manual authentication tabs:

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

Custom detection with prefix

A prefixed source checks for the standard AWS environment variables under a custom prefix. This configuration checks for:

• PROD_AWS_ACCESS_KEY_ID
• PROD_AWS_SECRET_ACCESS_KEY
• PROD_AWS_SESSION_TOKEN
• PROD_AWS_REGION (or PROD_AWS_DEFAULT_REGION)

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

A prefixed source reads only the prefixed variables. It never falls back to the unprefixed AWS_* credentials, so a PROD_ block can’t pick up your development keys by accident. When you confirm, the credentials are set in the session under the standard names (AWS_ACCESS_KEY_ID, AWS_REGION, and so on).

Prefixes must follow these rules:

• Uppercase letters, numbers, and underscores only
• Must start with a letter
• Must end with an underscore, as in PROD_ or MY_APP_

Test prefix

To use a different prefix in automated tests, for example to avoid conflicts with local credentials, set env_prefix on the step in runbook_test.yml:

runbook_test.yml

steps:
  - block: aws-auth
    env_prefix: CI_  # Checks CI_AWS_ACCESS_KEY_ID, CI_AWS_SECRET_ACCESS_KEY, and so on
    expect: success

See Testing AwsAuth blocks.

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:

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

The sensitive: prefix masks the secret key and session token in the Command’s View Outputs. AwsAuth still reads them as AWS_SECRET_ACCESS_KEY and AWS_SESSION_TOKEN. See Sensitive outputs.

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

When the user clicks “Use These Credentials”, AwsAuth validates the Command’s current outputs again and registers the result. If the Command was re-run in the meantime and its credentials now belong to a different AWS account, the prompt switches to that account and the user has to confirm again. If the credentials no longer validate, for example because temporary credentials have expired, the block shows the error and registers nothing.

When users reject detected credentials

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, so scripts can’t use detected credentials until the user confirms them.

When a user clicks “Use Different 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

Credentials for the wrong account, such as production when the user expected development, were not registered, so no script runs with them.

Security

Credential protection

When a runbook contains an <AwsAuth> block, Runbooks strips AWS credentials from the session at startup:

1. Before confirmation, scripts in the runbook cannot read AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY or AWS_SESSION_TOKEN, even if they are set in your terminal.
2. When AwsAuth checks for credentials, it reads them from your environment without registering them to the session.
3. Clicking “Use These Credentials” adds the credentials to the session, where later scripts can use them.

For example, with production credentials set in your terminal, opening a runbook meant for development does not let its scripts run against production.

Tip

A runbook with no AwsAuth block leaves environment credentials in place, and all scripts can use them.

Why confirmation is required

AWS operations often take effect immediately and can’t be undone. They create resources that cost money, change production data, or delete infrastructure. Confirmation matters most when users have access to several AWS accounts, or when a tool such as aws-vault or granted has set credentials in the environment.

Credential handling

• Authentication happens between your machine and AWS. Credentials are not sent to Gruntwork or any other server unless a script in your runbook sends them.
• Credentials are stored only in your local Runbooks session and are not written to disk.
• Credentials are validated with STS GetCallerIdentity before they are registered to the session.

Detailed example

The aws-auth feature demo is a runbook that walks through the AwsAuth block.