AWS CLI Integration for IAM Account access manager.

AWS IAM Account Access Manager (AAM) is a workforce account access portal that lets your organization assign IAM roles to users across multiple AWS accounts. It uses IAM Identity Center for authentication, but manages its own separate set of access assignments, independent of the Identity Center Access Portal.

The AWS CLI does not natively support Account Access Manager yet. These scripts bridge that gap. They configure your CLI to authenticate through AAM, discover your assigned roles, and set up named profiles so you can use aws commands normally; with automatic credential refresh; until your Identity Center session expires.

You do not need to manage credentials manually. Once set up, the CLI handles everything in the background; as long as these scripts remain in the same location where you ran the setup.

There are four scripts. You only need to run three of them:

refresh-credentials.py

You never call this script directly. When create-profiles.py or setup.py creates a profile in ~/.aws/config , it wires up a credential_process entry that points the AWS CLI at refresh-credentials.py . Every time you run an aws command with one of these profiles, the CLI silently calls this script in the background to get fresh credentials.

Important: these scripts must stay in the same directory after setup. The path written into ~/.aws/config is the absolute path to refresh-credentials.py at the time you ran setup. If you move the folder afterward, credential refresh will fail. To fix it, re-run setup.py (or create-profiles.py ) from the new location; existing profiles with the old path will be skipped, but you can remove them from ~/.aws/config manually and re-run to recreate them.

The role-listing logic in list-roles.py and setup.py is designed to handle large numbers of roles reliably:

Pagination — roles are fetched one page at a time using a nextToken cursor. The scripts loop until the API returns nextToken: null , so there is no limit on the total number of roles supported.

Connection drop handling and retries — both scripts use a requests.Session with a HTTPAdapter configured for automatic retries. If the connection drops or the server returns a 5xx error, the session transparently reconnects and retries with exponential backoff — no manual connection management needed.

Socket timeout — each request has a 30-second timeout. If the server stops responding, the script fails fast and retries rather than hanging indefinitely.

Retry limit — after 5 consecutive failures, the script exits with an error rather than retrying forever.

Requires Python 3.9+ (tested on 3.12) botocore — pip install botocore python-dateutil — pip install python-dateutil requests — pip install requests

botocore — pip install botocore

python-dateutil — pip install python-dateutil

requests — pip install requests

Or install all dependencies at once:

The examples below assume your shell is in the same directory as these scripts. If you placed them elsewhere, substitute that path.

Quick start — setup.py

Note: setup.py is a reference implementation intended to show how the full setup flow fits together. Use it as a guide to build your own onboarding script tailored to your environment; do not deploy it to production as-is.

Note: setup.py is a reference implementation intended to show how the full setup flow fits together. Use it as a guide to build your own onboarding script tailored to your environment; do not deploy it to production as-is.

For most users exploring AAM, setup.py is the fastest way to get started.

Run without flags to be prompted interactively:

After setup, use your profiles normally:

See python setup.py --help for all options.

Use the individual scripts if you want more control; for example to filter which roles get profiles, or to use a different format for each step.

Step 1 — Configure your session

This writes an [sso-session] block to ~/.aws/config and immediately opens the browser for your first login. You only need to run this once per Identity Center user. If a session with that name already exists, the script exits without modifying your config.

Use --sso-session to give the session a custom name (default: account-access-session ). Pass that same name to every subsequent command.

Step 2 — List your roles

Prints every IAM role you have access to through AAM as a JSON array (default) or CSV. You can pipe this directly into create-profiles.py , save it to a file, or filter it first.

Step 3 — Create profiles

Creates an AWS CLI profile in ~/.aws/config for each role. Profiles that already exist are skipped. The script prints a summary of what was created and what was skipped.

You can optionally add profileName and sessionName fields to the input data to override the defaults for individual roles.

Step 4 — Use the AWS CLI

Credentials are fetched and refreshed automatically. When your Identity Center session expires, log back in with:

Configure, list, filter to ReadOnly roles only, create profiles, and verify: