Skip to main content

Getting Started

This guide will get you started using Granted to assume roles in AWS. It will take around 5 minutes to complete.

A screenshot of Granted showing a selection menu for AWS profiles

Install the AWS CLI

Although Granted doesn't depend on the AWS CLI, we recommend installing it in order to run a test command to verify Granted is working properly.

Set up your AWS profile file

You will also need to set up at least one role in your AWS config file. On MacOS and Linux, this is stored in ~/.aws/config. On Windows, this is stored in the %UserProfile% directory. Some example configurations are included below.

If you use AWS SSO but you haven't yet configured any profiles, you can run aws configure sso which will walk you through the process of setting up your profile file.

If you've already set up roles for the AWS CLI to access AWS you probably don't need to configure anything: Granted uses the same configuration files as the AWS CLI.

Example configuration for AWS SSO (recommended)
# ~/.aws/config
# Change the values below to match your AWS SSO configuration
# Granted uses the profile name: in this case 'my-profile' to choose the role.

[profile my-profile]
sso_start_url=https://mycompany.awsapps.com/start
sso_region=us-east-1
sso_account_id=123456789012
sso_role_name=DeveloperRole
region=us-east-1
Example configuration for AWS IAM user and roles

More information on using IAM users and roles can be found here.

# ~/.aws/credentials
[base]
aws_access_key_id=<ACCESS_KEY>
aws_secret_access_key=<SECRET_KEY>
# ~/.aws/config
# Change the values below to match your AWS role configuration
# Granted uses the profile name: in this case 'my-profile' to choose the role.

[profile base]
region=us-east-1

[profile my-profile]
region=us-east-1
source_profile=base
role_arn=arn:aws:iam::123456789012:role/my-role

Installing the CLI

In order to use Granted you'll need to install it on your system. Common Fate provides binaries for Granted.

Homebrew is an open source package manager for MacOS. We publish a Homebrew formula for Granted. To install Granted with Homebrew, run the commands below in your terminal.

brew tap common-fate/granted
brew install granted

Verify the installation

You can verify the integrity and authenticity of the Granted binary you have downloaded by running through the verification process here.

To verify that the installation has succeeded, print the version of Granted by running granted -v. You should see an output similar to below.

➜ granted -v


Granted v0.13.2

If you have any issues installing don't hesitate to ask for help on our Slack.

Next steps

Now that you've installed Granted, it's time to assume your first role.