Configuration
By default, aws-sso
will by default store all it's configuration and state files in
~/.config/aws-sso
for versions >= 1.17.0
per the XDG spec.
Previous versions of aws-sso
used ~/.aws-sso
. Users at their own descresion may move the
files to the new location. To keep files co-located in the same place, if the directory
~/.aws-sso
exists, then it will be used.
Note: The aws-sso
documentation will generally use the older file path (~/.aws-sso/...
)
when describing file locations.
The main configuration file is named ~/.aws-sso/config.yaml
, but this can be overridden by
setting $AWS_SSO_CONFIG
in your shell or via the --config
flag.
The first time you run aws-sso
and it detects there is no configuration file,
it will prompt you for a number of questions to give you a basic configuration.
Afterwords, you can edit the file and adjust the settings as desired or run
aws-sso config.
SSOConfig:
<Name of AWS SSO>:
SSORegion: <AWS Region where AWS SSO is deployed>
StartUrl: <URL for AWS SSO Portal>
DefaultRegion: <AWS_DEFAULT_REGION>
AuthUrlAction: [clip|exec|print|printurl|open|granted-containers|open-url-in-container]
Accounts: # optional block for specifying tags & overrides
<AccountId>:
Name: <Friendly Name of Account>
DefaultRegion: <AWS_DEFAULT_REGION>
Tags: # tags for all roles in the account
<Key1>: <Value1>
<Key2>: <Value2>
Roles:
<Role Name>:
Profile: <ProfileName>
DefaultRegion: <AWS_DEFAULT_REGION>
Tags: # tags specific for this role (will override account level tags)
<Key1>: <Value1>
<Key2>: <Value2>
Via: <Previous Role> # optional, for role chaining
SourceIdentity: <Source Identity>
# See description below for these options
DefaultRegion: <AWS_DEFAULT_REGION>
DefaultSSO: <name of AWS SSO>
CacheRefresh: <hours>
AutoConfigCheck: [false|true]
AutoLogin: [false|true]
Threads: <integer>
MaxRetry: <integer>
MaxBackoff: <integer>
Browser: <path to web browser>
UrlAction: [clip|exec|print|printurl|open|granted-containers|open-url-in-container]
ConfigProfilesBinaryPath: <path to aws-sso binary>
UrlExecCommand:
- <command>
- <arg 1>
- <arg N>
- "%s"
ConsoleDuration: <minutes>
LogLevel: [error|warn|info|debug|trace]
LogLines: [true|false]
HistoryLimit: <integer>
HistoryMinutes: <integer>
SecureStore: [file|keychain|kwallet|pass|secret-service|wincred|json]
JsonStore: <path to json file>
ProfileFormat: "<template>"
ConfigVariables:
<Var1>: <Value1>
<Var2>: <Value2>
<VarN>: <ValueN>
FirstTag: <Tag Name>
FullTextSearch: [true|false]
AccountPrimaryTag:
- <tag 1>
- <tag 2>
- <tag N>
PromptColors:
<Option 1>: <Color>
<Option 2>: <Color>
<Option N>: <Color>
ListFields:
- <field 1>
- <field 2>
- <field N>
EnvVarTags:
- <Tag1>
- <Tag2>
- <TagN>
SSOConfig
This is the top level block for your AWS SSO instances. Typically an
organization will have a single AWS SSO instance for all of their accounts
under a single AWS master payer account. If you have more than one AWS SSO
instance, then Default
will be the default unless overridden with
DefaultSSO
.
The SSOConfig
config block is required.
StartUrl
Each AWS SSO instance start URL hosted by AWS for interacting with your
SSO provider (Okta/OneLogin/etc). Should be in the format of
https://xxxxxxx.awsapps.com/start
.
Note: If you need to authenticate as different users to the same
AWS SSO Instance, you can specify multiple SSOConfig blocks
with the same StartUrl
.
The StartUrl
is required.
SSORegion
Each AWS SSO instance is configured in a specific AWS region which needs to be set here.
The SSORegion
is required.
DefaultRegion
The DefaultRegion
allows you to define a value for the $AWS_DEFAULT_REGION
when switching to a role. Note that, aws-sso will NEVER change an existing
$AWS_DEFAULT_REGION
set by the user.
DefaultRegion
can be specified at the following levels and the first match is
selected (most specific to most generic):
- At the inidividual role level:
SSOConfig -> <AWS SSO Instance> -> Accounts -> <AccountId> -> Roles -> <RoleName>
- At the AWS Account level:
SSOConfig -> <Name of the AWS SSO> -> Accounts -> <AccountId>
- At the AWS SSO Instance level:
SSOConfig -> <AWS SSO Instance>
- At the config file level (default is
us-east-1
)
Accounts
The Accounts
block is completely optional! The only purpose of this block
is to allow you to add additional tags (key/value pairs) to your accounts/roles
to make them easier to select.
Name
Alternate name of the account. Shown as AccountName
for the list command.
Not to be confused with the AccountAlias
which is defined by the account owner
in AWS. For more information, read the FAQ
Tags
List of key / value pairs, used by aws-sso
in prompt mode. Any tag placed at
the account level will be applied to all roles in that account.
Some special tags:
- Color -- Used to specify the color of the Firefox container label. Valid values are:
- blue
- turquoise
- green
- yellow
- orange
- red
- pink
- purple
- Icon -- Used to specify the icon of the Firefox container label. Valid values are:
- fingerprint
- briefcase
- dollar
- cart
- gift
- vacation
- food
- fruit
- pet
- tree
- chill
- circle
Roles
The Roles
block is optional, except for roles you which to assume via role chaining.
Profile
Define a custom $AWS_PROFILE
/ $AWS_SSO_PROFILE
value for this role which overrides
the ProfileFormat config option.
Roles, just like Accounts also accept Tags which are specific to that role and override any account level tags.
Via
Implements the concept of role chaining.
Via
defines which role to assume before calling sts:AssumeRole in
order to switch to the specified role. This allows you to define and assume
roles in AWS accounts that are not included in your organization's AWS SSO
scope or roles that were not defined via an AWS SSO Permission Set.
SourceIdentity
An optional string
which must not start with aws:
that your administrator may require you to set
in order to assume a role with Via
.
Common Config Options
DefaultSSO
If you only have a single AWS SSO instance, then it doesn't really matter what
you call it, but if you have two or more, than Default
is automatically
selected unless you manually specify it here, on the CLI (--sso
), or via
the AWS_SSO
environment variable.
SSO Cache Options
CacheRefresh
This is the number of hours between automatically refreshing your AWS SSO cache to detect any changes in the roles you have been granted access to. The default is 168 (7 days). Disable this feature by setting to any value <= 0.
Note: If this feature is disabled, then AutoConfigCheck is also disabled.
Threads
Certain actions when communicating with AWS can be accellerated by running multiple parallel threads. Must be >= 1. Default is 5 threads. Note that too many threads can actually hurt performance for large number of accounts!
MaxRetry
Maximum number of attempts before aborting. Default is 10 which seems optimal for <= 50 accounts. Value must be > 0.
MaxBackoff
Maximum number of seconds to wait before retrying. Too low of a value will cause retries to fail more often. Too high of a value will hurt performance. Default is 5 seconds which seems optional for <= 50 accounts. Value must be > 0.
Browser Integration
AuthUrlAction / Browser / UrlAction / UrlExecCommand
UrlAction
gives you control over how AWS SSO and AWS Console URLs are opened
in a browser:
clip
-- Copies the URL to your clipboardexec
-- Execute the command provided inUrlExecCommand
granted-containers
-- Generates a URL for the Firefox Granted Containers plugin and runs yourUrlExecCommand
open
-- Opens the URL in your default browser or the browser you specified via--browser
orBrowser
open-url-in-container
-- Generates a URL for the Firefox Open Url in Container plugin and runs yourUrlExecCommand
.print
-- Prints the URL with a message in your terminal to stderrprinturl
-- Prints only the URL in your terminal to stderr
If Browser
is not set, then your default browser will be used and that
browser needs to support JavaScript for the AWS SSO user interface.
UrlExecCommand
is used with UrlAction: exec
and the two Firefox containers
plugin options (granted-containers
/ open-url-in-container
) and allows you
to execute arbitrary commands to handle the URL. The command and arguments should be
specified as a list, with the URL to open specified as the format string %s
.
Only one instance of %s
is allowed. Note that YAML requires quotes around
strings which start with a reserved indicator like %
.
AuthUrlAction
allows you to override the global UrlAction
when authenticating
with your SSO provider to retrieve an AWS SSO token.
Examples:
Open URL In Default Browser
UrlAction: open
Open URL In Non-Default Browser
UrlAction: exec
UrlExecCommand:
- open
- -a
- /Applications/Brave Browser.app
- --args
- "%s"
Open URL in Firefox Container
Opens each IAM Role (and SSO Login page) in a unique Firefox Container using the Open Url in Container Firefox plugin.
UrlAction: open-url-in-container
UrlExecCommand:
- /Applications/Firefox.app/Contents/MacOS/firefox
- "%s"
Note: If you do not want your SSO Login page to be opened in a container, use the AuthUrlAction option to specify a different action:
SSOConfig:
Default:
SSORegion: us-east-1
StartUrl: https://example.awsapps.com/start
AuthUrlAction: open
UrlAction: open-url-in-container
UrlExecCommand:
- /Applications/Firefox.app/Contents/MacOS/firefox
- "%s"
Use custom shell script
UrlAction: exec
UrlExecCommand:
- ~/bin/open_url.sh
- "%s"
Note: If your ProfileFormat
generates a ProfileName with an &
, then
{{ .AccountId }}:{{ .RoleName }}
will be used as the Firefox container name instead.
Note: You can control the color and icon of the Firefox container label using Tags.
Note for MacOS users: This feature does not work with the bundle directory,
so you should specify /Applications/Firefox.app/Contents/MacOS/firefox
(or as
appropriate) as the command to execute.
ConsoleDuration
Number of minutes an AWS Console session is valid for (default 60). If you wish
to override the default session duration, you can specify the number of minutes
here or with the --duration
flag.
Note that even though AWS documents the API call to get a Console URL to be between 15 minutes and 36 hours, the real limit is 12 hours (720 minutes) because AWS SSO sessions are limited to 12 hours maximum.
AWS_PROFILE Integration
ConfigProfilesBinaryPath
Override execution path for aws-sso
when generating named AWS profiles via the
config-profiles.
ProfileFormat
AWS SSO CLI can set an environment variable named AWS_SSO_PROFILE
with
any value you can express using a Go Template
which can be useful for modifying your shell prompt and integrate with your own
tooling.
The following variables are accessible from the AWSRoleFlat
struct:
Id
-- Unique integer defined by AWS SSO CLI for this roleAccountId
-- AWS Account ID (int64! not zero padded)AccountIdPad
-- AWS Account ID (zero padded)AccountAlias
-- AWS Account Name defined in AWS by the account ownerAccountName
-- AWS Account Name defined in~/.aws-sso/config.yaml
EmailAddress
-- Root account email address associated with the account in AWSExpiresEpoch
-- When your API credentials expire (UNIX epoch)Expires
-- When your API credentials expire (string)Arn
-- AWS ARN for this roleRoleName
-- The role nameDefaultRegion
-- The manually configured default region for this roleSSO
-- Name of the AWS SSO instanceSSORegion
-- The AWS Region where AWS SSO is enabled in your accountStartUrl
-- The AWS SSO start URL for your accountTags
-- Map of additional custom key/value pairsVia
-- Role AWS SSO CLI will assume before assuming this role
By default, ProfileFormat
is set to {{ .AccountIdPad }}:{{ .RoleName }}
.
AWS SSO CLI uses sprig for most of its functions, but a few custom functions are available:
AccountIdStr(x)
-- Converts the.AccountId
variable to a string. Deprecated. Use.AccountIdPad
variable instead.EmptyString(x)
-- Returns true/false if the valuex
is an empty stringFirstItem([]x)
-- Returns the first item in a list that is not an empty stringStringsJoin(x, []y)
-- Joins the items iny
with the stringx
Note: Unlike most values stored in the config.yaml
, you will need to
single-quote ('
) the value because because ProfileFormat
values often start
with a {
.
For more information, see the FAQ.
ConfigVariables
Define a set of config settings for each
profile in your ~/.aws/config
file generated via the config-profiles command.
Some examples to consider:
sts_regional_endpoints: regional
output: json
Interactive Role Selection
FirstTag
When selecting a role, the tag key name at the top of the list will be this value regardless
of sort order. Useful if you want History
or some other tag easily accessible via arrow keys.
FullTextSearch
When set to true
, searching via interactive exec mode (aws-sso exec
without role selector args)
will cause searching to be done via substrings rather than the default prefix based search.
AccountPrimaryTag
When selecting a role, if you first select by role name (via the Role
tag) you
will be presented with a list of matching ARNs to select. The
AccountPrimaryTag
automatically includes another tag name and value as the
description to aid in role selection. By default the following tags are
searched (first match is used):
AccountName
AccountAlias
Email
Set AccountPrimaryTag
to an empty list to disable this feature.
PromptColors
PromptColors
takes a map of prompt options and color options allowing you to
have complete control of how AWS SSO CLI looks. You only need to specify the
options you wish to override, but do not include the PromptColors
if you have
no options. More information about the meaning and use of the options below,
refer to the go-prompt docs.
Valid options:
DescriptionBGColor
DescriptionTextColor
InputBGColor
InputTextColor
PrefixBackgroundColor
PrefixTextColor
PreviewSuggestionBGColor
PreviewSuggestionTextColor
ScrollbarBGColor
ScrollbarThumbColor
SelectedDescriptionBGColor
SelectedDescriptionTextColor
SelectedSuggestionBGColor
SelectedSuggestionTextColor
SuggestionBGColor
SuggestionTextColor
Valid low intensity colors:
Black
DarkRed
DarkGreen
Brown
DarkBlue
Purple
Cyan
LightGrey
Valid high intensity colors:
DarkGrey
Red
Green
Yellow
Blue
Fuchsia
Turquoise
White
HistoryLimit
Limits the number of recently used roles tracked via the History tag. Default is last 10 unique roles. Set to 0 to disable.
HistoryMinutes
Limits the list of recently used roles tracked via the History tag to roles that were last used within the last X minutes. Set to 0 to not limit based on the time. Default is 1440 minutes (24 hours).
This option has no effect if HistoryLimit
is set to 0.
Advanced Configuration Options
ListFields
Specify which fields to display via the list
command. Valid options are:
Id
-- Unique row identifierAccountAlias
-- Account Name in AWS as defined by the account ownerAccountId
-- AWS Account IdAccountIdPad
-- AWS Account Id with leading zeros if necessaryAccountName
-- Account Name from config.yamlArn
-- Role ARNDefaultRegion
-- Configured default regionEmailAddress
-- Email address of root account associated with AWS AccountExpiresEpoch
-- Unix epoch time when cached STS creds expireExpires
-- Hours and minutes until cached STS creds expireProfile
-- Value used for$AWS_SSO_PROFILE
and the profile name in~/.aws/config
RoleName
-- Role nameSSO
-- AWS SSO instance nameVia
-- Role Chain Via
AutoConfigCheck
When set to true
, when your AWS SSO roles are automatically refreshed (see
CacheRefresh) aws-sso
will also check to see if any changes
are warranted in your ~/.aws/config
.
Note: This option can be disabled temporarily on the command line by passing
the --no-config-check
flag.
Note: If you are using a non-default path for your ~/.aws/config
file, then
you must be sure to set the AWS_CONFIG_FILE
environment variable to the correct
path or disable this configuration option.
AutoLogin
When set to true
, aws-sso
will behave like v1.x and automatically attempt to
login with your SSO provider to AWS Identity Center when your session has expired.
When set to false
(the default) you must first run aws-sso login.
LogLevel / LogLines
By default, the LogLevel
is 'info'. You can override it here or via
--log-level
with one of the following values:
error
warn
info
debug
trace
LogLines
includes the file name/line and module name with each log for
advanced debugging.
SecureStore / JsonStore
SecureStore
supports the following backends:
file
- Encrypted local files (OS agnostic and default on Linux)keychain
- macOS Keychain (default on macOS)kwallet
- KDE Walletpass
- pass (uses GPG on backend)secret-service
- Freedesktop.org Secret Servicewincred
- Windows Credential Manager (default on Windows)json
- Cleartext JSON file (very insecure and not recommended). Location can be overridden withJsonStore
EnvVarTags
List of tag keys that should be set as a shell environment variable when
using the eval
or exec
commands.
Note: These environment variables are considered completely owned and
controlled by aws-sso
so any existing value will be overwritten.
Note: This feature is not compatible when using roles using the
$AWS_PROFILE
via the config
command.