Granted: Fast AWS Profile Switching

DevOps 2026-02-14 · 9 min read granted aws cloud iam profiles devops credentials

Granted: Fast AWS Profile Switching

If you work with more than one AWS account, you know the pain. You have a development account, a staging account, a production account, maybe separate accounts for logging, networking, and security. Each has its own credentials or role assumptions. Switching between them means editing environment variables, running aws sts assume-role commands, or maintaining a growing collection of terminal tabs each set to a different profile. Opening the AWS Console in a browser is worse -- you can only be logged into one account at a time unless you use private windows or separate browser profiles.

Granted solves this entire problem. It is an open-source CLI tool built by Common Fate that makes switching between AWS profiles instant, supports assuming IAM roles with a single command, and -- most impressively -- opens multiple AWS Console sessions in your browser simultaneously, each in a separate tab or Firefox container. No more juggling browser profiles or private windows.

The Multi-Account Problem

Modern AWS setups follow the multi-account pattern recommended by AWS itself. A typical organization might have:

Management account: Billing and organization root
Security account: GuardDuty, Security Hub, audit logs
Log archive account: Centralized CloudTrail and VPC Flow Logs
Network account: Transit Gateway, shared VPCs
Dev account: Development environments
Staging account: Pre-production testing
Production account: Live workloads
Sandbox accounts: Individual developer experimentation

Developers regularly need to access 3-5 of these accounts throughout their day. The standard AWS CLI approach is to define profiles in ~/.aws/config and switch using --profile flags or AWS_PROFILE environment variables. This works but is clunky, especially when you need to assume roles across accounts.

Granted makes this workflow seamless.

Installation

macOS

brew tap common-fate/granted
brew install granted

Linux

curl -OL releases.commonfate.io/granted/v0.35.0/granted_0.35.0_linux_x86_64.tar.gz
tar -xzf granted_0.35.0_linux_x86_64.tar.gz
sudo mv granted assume /usr/local/bin/

Windows

choco install granted

Verify Installation

granted --version

Shell Alias Setup

Granted works through a shell function called assume. After installation, add the following to your shell configuration:

Bash (~/.bashrc):

alias assume="source assume"

Zsh (~/.zshrc):

alias assume="source assume"

Fish (~/.config/fish/config.fish):

alias assume="source assume"

The source is critical. Granted needs to set environment variables in your current shell session, which requires sourcing rather than running as a subprocess.

AWS Profile Configuration

Before using Granted, you need AWS profiles defined in ~/.aws/config. Here is a typical multi-account setup:

[profile dev]
sso_start_url = https://myorg.awsapps.com/start
sso_region = us-east-1
sso_account_id = 111111111111
sso_role_name = DeveloperAccess
region = us-west-2
output = json

[profile staging]
sso_start_url = https://myorg.awsapps.com/start
sso_region = us-east-1
sso_account_id = 222222222222
sso_role_name = DeveloperAccess
region = us-west-2

[profile production]
sso_start_url = https://myorg.awsapps.com/start
sso_region = us-east-1
sso_account_id = 333333333333
sso_role_name = ReadOnlyAccess
region = us-west-2

[profile sandbox]
source_profile = dev
role_arn = arn:aws:iam::444444444444:role/SandboxAdmin
region = us-west-2

[profile security-audit]
source_profile = dev
role_arn = arn:aws:iam::555555555555:role/SecurityAudit
region = us-east-1

Granted works with all standard AWS credential types: SSO, IAM users with access keys, assumed roles, and credential processes.

Basic Usage

Switching Profiles

The core command is assume:

assume dev

This sets AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN, AWS_REGION, and AWS_PROFILE in your current shell. Any subsequent AWS CLI or SDK command uses these credentials.

assume dev
aws s3 ls                    # Lists S3 buckets in dev account
assume production
aws s3 ls                    # Lists S3 buckets in production account

Interactive Profile Selection

Run assume without arguments for an interactive fuzzy search:

assume

This opens a search interface listing all your configured profiles. Type to filter, use arrow keys to navigate, and press Enter to select. If you have dozens of profiles, this is much faster than remembering exact names.

Unsetting Credentials

To clear the current assumed profile:

assume -un

This removes all AWS environment variables from your shell, returning you to a clean state.

Profile with Reason (for Audit)

Some organizations require a reason when assuming privileged roles:

assume production --reason "Investigating elevated error rates in us-west-2"

The reason is logged and can be integrated with audit systems.

Browser Console Access

This is Granted's standout feature. Instead of switching between browser profiles or private windows to access different AWS accounts, Granted opens the console directly.

Opening the Console

assume dev -c

The -c (or --console) flag opens the AWS Console for the dev account in your default browser. But here is the key innovation: each account opens in its own session.

Multiple Simultaneous Console Sessions

assume dev -c          # Opens dev console in Tab 1
assume staging -c      # Opens staging console in Tab 2
assume production -c   # Opens production console in Tab 3

All three tabs are authenticated to different AWS accounts simultaneously. No logging out and back in, no private windows, no browser profile switching.

How It Works

Granted uses AWS's federation endpoint to generate a sign-in URL with temporary credentials. For Firefox users, it leverages Firefox Containers (Multi-Account Containers) to isolate each session. For Chrome users, it can use separate browser profiles or Granted's built-in browser.

Configuring the Browser

# Set your preferred browser
granted browser set

# Options:
# - firefox (uses Multi-Account Containers)
# - chrome
# - brave
# - edge
# - granted-browser (Chromium-based, built-in isolation)

Firefox with Multi-Account Containers provides the best experience. Each AWS account gets its own container with a colored tab indicator, so you can visually distinguish which account you are looking at.

Opening a Specific Console Page

# Open directly to S3
assume dev -c -s s3

# Open to CloudWatch Logs
assume production -c -s cloudwatch

# Open to a specific URL
assume dev -c -u https://us-west-2.console.aws.amazon.com/ecs/home

This is incredibly useful when you need to quickly check a specific service in a specific account.

Role Chaining

In complex AWS setups, you often need to chain role assumptions: assume a role in one account, then use those credentials to assume a role in another account. Granted handles this automatically based on your ~/.aws/config:

[profile hub]
sso_start_url = https://myorg.awsapps.com/start
sso_region = us-east-1
sso_account_id = 111111111111
sso_role_name = HubRole

[profile spoke-dev]
source_profile = hub
role_arn = arn:aws:iam::222222222222:role/SpokeDevRole

[profile spoke-prod]
source_profile = hub
role_arn = arn:aws:iam::333333333333:role/SpokeProdRole

assume spoke-dev

Granted automatically assumes the hub role first, then uses those credentials to assume the spoke-dev role. This works for arbitrarily deep chains.

Credential Process Integration

Granted can act as a credential process for the AWS CLI and SDKs. This is useful when you want tools to automatically refresh credentials without manual intervention:

[profile dev]
credential_process = granted credential-process --profile dev

With this configuration, any AWS SDK or CLI call using the dev profile automatically invokes Granted to obtain fresh credentials. This works well for:

Long-running development servers that need persistent AWS access
IDE integrations that read AWS credentials
Docker containers that need host AWS credentials

Exporting Credentials

Sometimes you need credentials in a format other than environment variables:

# Export as environment variables (for eval)
assume dev --export

# Export for use in a subprocess
assume dev --exec "terraform plan"

# Export to a specific format
assume dev --export --format json

The --exec flag is particularly useful for running a single command with a specific profile without changing your shell's environment:

assume production --exec "aws s3 ls"
assume dev --exec "terraform apply"

Your shell's current profile is unchanged after the command completes.

Profiles Configuration with Granted

Beyond the standard AWS config, Granted supports its own configuration for enhanced functionality:

# ~/.granted/config
DefaultBrowser: FIREFOX
CustomBrowserPath: /usr/bin/firefox
Ordering: Frecency
ExportCredentialSuffix: ""

Ordering Options

Frecency (default): Profiles you use most frequently and most recently appear first in the interactive selector. This is usually the best choice.

Alphabetical: Profiles sorted alphabetically.

MostRecent: Profiles sorted by last use time.

Profile Registry

For teams, Granted supports a shared profile registry. Instead of each developer maintaining their own ~/.aws/config, you define profiles in a central location:

# .granted/registry.yml
profiles:
  dev:
    sso_start_url: https://myorg.awsapps.com/start
    sso_region: us-east-1
    sso_account_id: "111111111111"
    sso_role_name: DeveloperAccess
    region: us-west-2
  production:
    sso_start_url: https://myorg.awsapps.com/start
    sso_region: us-east-1
    sso_account_id: "333333333333"
    sso_role_name: ReadOnlyAccess
    region: us-west-2

Commit this to your team's repository, and new developers get correct AWS profiles immediately.

Using Granted with AWS SSO

AWS IAM Identity Center (formerly AWS SSO) is the recommended way to manage access across multiple AWS accounts. Granted integrates seamlessly with it.

Initial SSO Setup

# Configure SSO in AWS CLI
aws configure sso

# Or manually add to ~/.aws/config:
# [profile dev]
# sso_start_url = https://myorg.awsapps.com/start
# sso_region = us-east-1
# sso_account_id = 111111111111
# sso_role_name = DeveloperAccess

SSO Login with Granted

# Login to SSO (opens browser for authentication)
assume dev

# If SSO session is expired, Granted automatically triggers login
# No need to manually run 'aws sso login' first

Granted detects when your SSO session has expired and automatically initiates the login flow. This eliminates the common workflow of running aws sso login --profile dev before every session.

Populating SSO Profiles

If you have many accounts in your SSO organization, Granted can discover and generate profiles for all of them:

granted sso populate --sso-region us-east-1 https://myorg.awsapps.com/start

This queries your SSO instance and adds profiles to ~/.aws/config for every account and role you have access to.

Security Considerations

Credential Lifetime

Granted uses temporary credentials by default. SSO credentials and assumed role credentials both have configurable but limited lifetimes (typically 1-12 hours). This is inherently more secure than long-lived access keys.

Clearing Credentials

Always unset credentials when you are done working with a sensitive account:

assume -un

This removes all AWS-related environment variables from your shell, preventing accidental operations against the wrong account.

MFA Support

For profiles that require MFA:

[profile production]
source_profile = dev
role_arn = arn:aws:iam::333333333333:role/ProdAdmin
mfa_serial = arn:aws:iam::111111111111:mfa/your-username

Granted prompts for your MFA code when assuming this role. It caches the session to avoid repeated MFA prompts within the session lifetime.

Audit Trail

With the --reason flag, you can attach context to role assumptions. Combined with CloudTrail, this provides a complete audit trail of who accessed what account and why.

Granted vs. Alternatives

Granted vs. aws-vault

aws-vault is a popular tool for securely storing and accessing AWS credentials. It focuses on credential storage (in the system keychain) and temporary credential generation. Granted overlaps in credential management but adds the browser console feature, interactive profile selection, and frecency-based ordering. If you primarily need secure credential storage, aws-vault is solid. If you need the full multi-account workflow including console access, Granted is more complete.

Granted vs. leapp

Leapp is a GUI application for managing cloud credentials. It provides a desktop app with a visual interface for switching between accounts. If you prefer GUI tools, Leapp is worth considering. If you prefer staying in the terminal and want browser console integration, Granted fits better.

Granted vs. aws sso login + --profile

The native AWS CLI approach works but requires separate login commands, has no fuzzy search, no console integration, and no frecency ordering. Granted wraps this with a better developer experience while using the same underlying mechanisms.

Granted vs. saml2aws

saml2aws is for organizations using SAML-based federation (Okta, OneLogin, ADFS). It handles the SAML authentication flow to obtain AWS credentials. Granted works with SSO natively but does not handle SAML federation directly. If your organization uses SAML rather than AWS SSO, saml2aws is the right tool.

Tips and Best Practices

Use frecency ordering: The default frecency ordering means the profiles you use most appear first. Over time, your most-used profiles become one keystroke away.

Set up Firefox containers: If you use the AWS Console frequently, invest the 5 minutes to set up Firefox with Multi-Account Containers. The visual separation of accounts by color is invaluable for avoiding "wrong account" mistakes.

Use --exec for one-off commands: Instead of assuming a profile, running one command, and switching back, use assume production --exec "aws s3 ls" to keep your shell clean.

Name profiles clearly: Use names like dev, staging, prod-readonly, prod-admin rather than account IDs or cryptic abbreviations. You will see these names in the fuzzy finder dozens of times a day.

Populate SSO profiles automatically: If your organization uses AWS SSO, run granted sso populate periodically to pick up new accounts and roles.

Set console bookmarks per account: Use assume dev -c -s ec2 style commands as terminal aliases for your most common account+service combinations:

alias dev-ec2="assume dev -c -s ec2"
alias prod-logs="assume production -c -s cloudwatch"
alias staging-s3="assume staging -c -s s3"

Always unset after production work: Make it a habit to run assume -un after any work in production accounts to prevent accidental operations.

Conclusion

Granted transforms the daily friction of working with multiple AWS accounts into something that feels effortless. The interactive profile switcher with frecency ordering means you spend seconds, not minutes, switching context. The browser console feature eliminates the single most frustrating aspect of multi-account AWS work. And the role chaining, SSO integration, and credential process support mean it works with whatever AWS authentication setup your organization uses. For anyone who works with more than two AWS accounts, Granted is not just a nice-to-have -- it is a genuine productivity multiplier.