Configuration
Granted Configuration Folder
The configuration settings for Granted are stored within the $HOME/.granted
folder on Unix systems, and %USERPROFILE%/.granted
on Windows. This designated folder serves as a repository for configuration data, encompassing:
-
Default Browser Configuration: The
DefaultBrowser
option allows you to establish the default browser. -
Custom Browser Paths: The
CustomBrowserPath
option lets you override default installation paths for browsers with custom locations. -
Custom Single Sign-On (SSO) Browser Paths: The
CustomSSOBrowserPath
option provides the ability to set custom browser for running Single Sign-On (SSO) flows. -
Profile Ordering: The
Ordering
option allows you to change the order of profiles when they are displayed. -
Export Credential Suffix: The
ExportCredentialSuffix
option enables appending a suffix when exporting credentials. -
Access Request URL: The
AccessRequestURL
option lets you set a Glide URL that can be used to request access. -
CommonFate SSO Default Start URL and Region: The
CommonFateDefaultSSOStartURL
andCommonFateDefaultSSORegion
options respectively set the default start URL and region for CommonFate Single Sign-On. -
Usage Tips and Credential Caching: The
DisableUsageTips
option, when set to true, suppresses usage tips. TheDisableCredentialProcessCache
option, when set to true, prevents credential caching via credential processes. -
Export All Environment Variables: The
DefaultExportAllEnvVar=true
configuration exports all environment variables by default when thecredential_process
is used. -
Export Credentials To AWS: The
ExportCredsToAWS=true
configuration will enable credentials to be exported to~/.aws/credentials
by default.
To configure any of these options, you can use the following command:
granted settings set
Changing the profile ordering
There are settings options in Granted which allow you to change the way that profiles are listed in use. Default being by Frecency. Alternatively it can be configured to list profiles alphabetically. To set the profile ordering type just run:
granted settings profile-order set
From here you will be able to select your preferred method of choice
? Select filter type [Use arrows to move, type to filter]
> Frecency
Alphabetical
Frecency
Granted uses a Frecency algorithm to show the most frequent and recent profiles at the top of the list when running assume
. The algorithm can be found here. The algorithm caches frecency data locally in the aws_profiles_frecency
file in the Granted configuration folder.
Autocompletion
Granted has support for shell auto complete. We currently support zsh and fish, with plans to support bash, and powershell in the future. Please let us know of your interest by opening an issue on GitHub.
Fish
Fish autocompletions can be created by running the following command, then following the prompts.
Note, This currently only provides command and flag autocompletion, it does not automatically list aws profiles with the assume command. Let us know if you are using Fish and would like to see this added.
granted completion -s fish
ZSH
ZSH autocompletion can be enabled by running the following command.
granted completion -s zsh
Type assume
and press tab to see a list of your aws profiles.
assume
profile-1 profile-2 profile-3
Type assume -
and press tab to see flag completions.
assume -
--active-role --duration --export --pt --unset --version -h -v
--ar --env --granted-active-aws-role-profile --region --update-checker-api-url -c -r
--auto-configure-shell --ex --help --service --url -d -s
--console --exec --pass-through --un --verbose -e -u
Type assume -s
and press tab to see service names.
ct gd s3 sso
appsync cw grafana sagemaker states
athena ddb iam scrh stepfn
c9 dms l scrm tra
ce dx lambda secretsmanager trustedadvisor
cf eb mwaa securityhub vpc
cfn ebs param ses waf
cloudformation ec2 r53 sfn
cloudmap ecr rds sm
cloudwatch ecs redshift sns
config eks route53 ssm
Type assume -r
and press tab to see regions.
af-south-1 ap-south-1 eu-north-1 me-south-1 us-west-2
ap-east-1 ap-southeast-1 eu-south-1 sa-east-1
ap-northeast-1 ap-southeast-2 eu-west-1 us-east-1
ap-northeast-2 ca-central-1 eu-west-2 us-east-2
ap-northeast-3 eu-central-1 eu-west-3 us-west-1
Changing the web browser
To see which browser Granted will use to open cloud consoles with, run granted browser
.
To change the web browser, run the command:
granted browser set
You will get a response like this:
? Select your default browser [Use arrows to move, type to filter]
> Chrome
Brave
Edge
Firefox
Chromium
Safari
Firefox Developer Edition
Arc
Select which browser you would like to use and press Enter.
Using specific browser profiles
Launching a specific browser profile is possible with --browser-profile
flag for supported browsers such as Chrome, Edge, and Chromium Variants. Example usage: assume profile-name -c --browser-profile "<your_browser_profile>"
Setting color and icon preferences for profiles
If you use Firefox with the Granted Firefox Addon, you can set the color and icon preference for each profile. This is useful for distinguishing between profiles at a glance.
To customize the color and icon add granted_color
and granted_icon
to the profile in your ~/.aws/config
file.
This configuration:
granted_color = green
granted_icon = dollar
Will result in this:
Valid colors are: blue
, turquoise
, green
, yellow
, orange
, red
, pink
and purple
Valid icons are: fingerprint
, briefcase
, dollar
, cart
, circle
, gift
, vacation
, food
, fruit
, pet
, tree
and chill
Custom browser for running SSO flows
You can specify a custom browser path for your SSO login flows with Granted.
granted browser set-sso
You will get a response like this:
ℹ️ Select your SSO default browser
? Select your default browser Chrome
✅ Granted will default to using /Applications/Google Chrome.app/Contents/MacOS/Google Chrome for SSO flows.
Error reporting and update checking
We currently do not collect error reports in Granted but this is something we are considering in future in order to ensure Granted works reliably on all platforms. Any error reporting telemetry, including instructions on how to opt out, will be communicated through GitHub and this documentation page.
The Granted binary will periodically check to see if new versions are available by calling https://update.api.granted.dev.
To disable update checking you can set the environment variable GRANTED_DISABLE_UPDATE_CHECK=true
.
Granted Configuration Editing
Granted gives you tools to be able to interact with the config that is set under the hood.
- Use the
-unset
flag to remove any exported environment variables that Granted has provisioned eg.
assume -unset
- Use the
uninstall
command to reset the granted configuration to a factory default
granted uninstall
SSO Configuration
- To list all SSO tokens saved in the Granted keychain use the
sso-tokens
command
granted sso-tokens
granted sso-tokens list
- To remove a token from the local store use
sso-tokens clear
granted sso-tokens clear
granted sso-tokens clear profile_name
- To remove all tokens from the store use the
--all
flag
granted sso-tokens clear --all
Enable Quiet Mode
To enable quiet mode in Granted, set the GRANTED_QUIET
environment variable to true
by running:
export GRANTED_QUIET=true
This suppresses most of the command output, providing a quieter experience.
Customize AWS Configuration and Credentials File Locations
Specify the location of your AWS configuration file and credentials file through environment variables. Set the $AWS_CONFIG_FILE
and $AWS_SHARED_CREDENTIALS_FILE
environment variables to configure these file locations according to your preferences.