Getting Started
This guide will get you started using Granted to assume roles in AWS. It will take around 5 minutes to complete.
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 on MacOS
- Linux
- Windows
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
Select the steps which match your system architecture. You can find your architecture by running uname -m from a terminal window.
- x86_64
- arm64
- i386
curl -OL releases.commonfate.io/granted/v0.17.1/granted_0.17.1_linux_x86_64.tar.gz
sudo tar -zxvf ./granted_0.17.1_linux_x86_64.tar.gz -C /usr/local/bin/
curl -OL releases.commonfate.io/granted/v0.17.1/granted_0.17.1_linux_arm64.tar.gz
sudo tar -zxvf ./granted_0.17.1_linux_arm64.tar.gz -C /usr/local/bin/
curl -OL releases.commonfate.io/granted/v0.17.1/granted_0.17.1_linux_i386.tar.gz
sudo tar -zxvf ./granted_0.17.1_linux_i386.tar.gz -C /usr/local/bin/
First, download the zip archive of Granted which matches your system's architecture. You can find your architecture by viewing your system properties in the Control Panel.
After downloading Granted, unzip the package. Granted runs as two binaries, assume and granted. Any other files in the package can be removed and Granted will still function.
You'll need to move Granted to a folder that is accessible on your PATH. This StackOverflow link has instructions on how to do this.
If you are using Granted with the Git Bash shell on Windows, we recommend enabling experimental support for pseudo consoles. You may need to reinstall Git For Windows to enable this. You can read more about this here.
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.17.1
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.