<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.

Basic Usage

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

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

Required Props

• id (string) - Unique identifier for this component. See Using With Commands And Checks for how this prop is used.

Optional Props

• title (string) - Display title shown in the UI (default: “AWS Authentication”). Supports inline markdown (bold, italic, links, code).
• description (string) - Longer description of the authentication purpose. Supports inline markdown.
• defaultRegion (string) - Default AWS region for CLI commands (default: “us-east-1”). Sets AWS_REGION environment variable.

SSO-Specific Props

These props configure AWS SSO (IAM Identity Center) authentication:

Required

• ssoStartUrl (string) - Your organization’s AWS SSO start URL (e.g., https://my-company.awsapps.com/start)

Optional

• ssoRegion (string) - The AWS region where your IAM Identity Center is configured (default: “us-east-1”)
• 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.

Detailed Example

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