Skip to content
Common Fate
Docs Granted
Get audited access to RDS databases without a VPN using the Granted RDS Plugin. Learn more here.

Getting Started

CLI screenshot

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.

Video Walkthrough

If you’d prefer to watch a video tutorial, Rowan from Common Fate has recorded an introduction to Granted on our Youtube channel.

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.

~/.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

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.

Using Homebrew

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.

Terminal window
brew tap common-fate/granted
brew install granted

Manual install

Select the steps which match your system architecture. You can find your architecture by running uname -m from a terminal window.

For Intel (x86_64 architecture):

Terminal window
curl -OL https://releases.commonfate.io/granted/v0.36.2/granted_0.36.2_darwin_x86_64.tar.gz
sudo tar -zxvf ./granted_0.36.2_darwin_x86_64.tar.gz -C /usr/local/bin/
ln -s /usr/local/bin/granted /usr/local/bin/assumego

For ARM (arm64 architecture):

Terminal window
curl -OL https://releases.commonfate.io/granted/v0.36.2/granted_0.36.2_darwin_arm64.tar.gz
sudo tar -zxvf ./granted_0.36.2_darwin_arm64.tar.gz -C /usr/local/bin/
ln -s /usr/local/bin/granted /usr/local/bin/assumego

Reverting to an older version of Granted

If you need to revert to an older version of Granted, you can manually downgrade using the following steps. First, make sure to uninstall your current version of granted. Replace “0.36.2” with the specific version you want to install.

Using Homebrew

brew uninstall granted
brew tap-new $USER/local-tap
brew extract --version=0.36.2 common-fate/granted/granted $USER/local-tap
brew install granted@0.36.2

For Intel (x86_64 architecture):

Terminal window
curl -OL https://releases.commonfate.io/granted/v0.36.2/granted_0.36.2_darwin_x86_64.tar.gz
sudo tar -zxvf ./granted_0.36.2_darwin_x86_64.tar.gz -C /usr/local/bin/
ln -s /usr/local/bin/granted /usr/local/bin/assumego

For ARM (arm64 architecture):

Terminal window
curl -OL https://releases.commonfate.io/granted/v0.36.2/granted_0.36.2_darwin_arm64.tar.gz
sudo tar -zxvf ./granted_0.36.2_darwin_arm64.tar.gz -C /usr/local/bin/
ln -s /usr/local/bin/granted /usr/local/bin/assumego

The assumego path is symlinked to granted so that they can both share keychain items without additional prompts. The homebrew install does this automatically but for a manual install on MacOS you’ll need to do it yourself.

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.36.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.