How to assume AWS Roles with Granted (CLI and Console)

Granted

We use a CLI tool called Granted to assume AWS roles from profiles defined in your ~/.aws/config. It streamlines AWS IAM Identity Center (SSO) login and role switching, and can also handle classic IAM role chaining.

Pre-requisites

• AWS CLI installed

  • How to install AWS CLI

• Granted installed

  • How to install Granted

Steps

Step 1 — Create/update your AWS profiles

• You need at least one AWS profile in ~/.aws/config.

• Create or update a profile using your organization’s SSO start URL and SSO region. Replace the placeholders with your real values.

[profile prod-account-admin]
granted_sso_start_url   = https://<your-company>.awsapps.com/start
granted_sso_region      = <region>
granted_sso_account_id  = 123456789012
granted_sso_role_name   = <sso_role_name>
credential_process      = granted credential-process --profile prod-account-admin

[profile prod-account-ro]
granted_sso_start_url   = https://<your-company>.awsapps.com/start
granted_sso_region      = <region>
granted_sso_account_id  = 123456789012
granted_sso_role_name   = <sso_role_name>
credential_process      = granted credential-process --profile prod-account-ro

Step 2 — Verify prerequisites

• Check that the AWS CLI and Granted are on your PATH:

  • aws --version

  • granted -v

• On macOS, Granted stores tokens in the Keychain. If prompted, allow access.

Step 3 — Sign in

• Complete the initial login:

  • granted sso login --sso-start-url https://<your-company>.awsapps.com/start --sso-region <region>

Step 4 — Assume a role with Granted

• To run AWS CLI commands:

  • Select a role from your AWS config (shows a list of all roles):

    • assume

  • Assume a specific role directly (skips the list):

    • assume prod-account-admin

• Open the AWS Management Console directly for a profile:

  • Select a role from your AWS config (shows a list of all roles):

    • assume -c

  • Open the console for a specific role directly (skips the list):

    • assume -c prod-account-admin

Optional configurations

Auto-login with credential process

• If you set the --auto-login flag, Granted will automatically open your browser to start an AWS SSO authentication flow when your token has expired.

  • Example:

    • credential_process = granted credential-process --auto-login --profile my-profile

Global auto-login

• If you prefer global auto-login instead of setting the --auto-login flag on each profile, you can configure Granted to always log in to AWS SSO.

  • Set CredentialProcessAutoLogin to true either in your Granted config file (~/.granted/config) or run:

    • granted settings set --setting=CredentialProcessAutoLogin --value true