Skip to content

Latest commit

 

History

History
550 lines (418 loc) · 18.6 KB

config.md

File metadata and controls

550 lines (418 loc) · 18.6 KB
Raw

Configuration

By default, aws-sso stores it's configuration file in ~/.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>
Threads: <integer>
MaxRetry: <integer>
MaxBackoff: <integer>

Browser: <path to web browser>
UrlAction: [clip|exec|print|printurl|open|granted-containers|open-url-in-container]
ConfigProfilesUrlAction: [clip|exec|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):

  1. At the inidividual role level: SSOConfig -> <AWS SSO Instance> -> Accounts -> <AccountId> -> Roles -> <RoleName>
  2. At the AWS Account level:SSOConfig -> <Name of the AWS SSO> -> Accounts -> <AccountId>
  3. At the AWS SSO Instance level: SSOConfig -> <AWS SSO Instance>
  4. At the config file level (default is us-east-1)

AuthUrlAction

Override the global UrlAction when authenticating with your SSO provider to retrieve an AWS SSO token. Generally only useful when you wish to use your default browser with one SSOConfig block to re-use your existing SSO browser authentication cookie.

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

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

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 clipboard
  • exec -- Execute the command provided in UrlExecCommand
  • granted-containers -- Generates a URL for the Firefox Granted Containers plugin and runs your UrlExecCommand
  • open -- Opens the URL in your default browser or the browser you specified via --browser or Browser
  • open-url-in-container -- Generates a URL for the Firefox Open Url in Container plugin and runs your UrlExecCommand
  • print -- Prints the URL with a message in your terminal to stderr
  • printurl -- 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 %.

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
UrlAction: open-url-in-container
UrlExecCommand:
    - /Applications/Firefox.app/Contents/MacOS/firefox
    - "%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

ConfigProfilesUrlAction

Setting ConfigProfilesUrlAction enables automatically updating your ~/.aws/config file any time the list of IAM Roles you are given access to changes.

This works just like UrlAction above, but is used for setting the default --url-action in your ~/.aws/config when generating named AWS profiles for use with $AWS_PROFILE and the default value for the config-profiles command.

Due to limitations with the AWS SDK, only the following options are valid:

  • clip
  • exec
  • open
  • granted-containers
  • open-url-in-container

Note: This config option was previously known as ConfigUrlAction which has been deprecated.

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 role
  • AccountId -- AWS Account ID (int64! not zero padded)
  • AccountIdPad -- AWS Account ID (zero padded)
  • AccountAlias -- AWS Account Name defined in AWS by the account owner
  • AccountName -- AWS Account Name defined in ~/.aws-sso/config.yaml
  • EmailAddress -- Root account email address associated with the account in AWS
  • ExpiresEpoch -- When your API credentials expire (UNIX epoch)
  • Expires -- When your API credentials expire (string)
  • Arn -- AWS ARN for this role
  • RoleName -- The role name
  • DefaultRegion -- The manually configured default region for this role
  • SSO -- Name of the AWS SSO instance
  • SSORegion -- The AWS Region where AWS SSO is enabled in your account
  • StartUrl -- The AWS SSO start URL for your account
  • Tags -- Map of additional custom key/value pairs
  • Via -- 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:

  • EmptyString(x) -- Returns true/false if the value x is an empty string
  • FirstItem([]x) -- Returns the first item in a list that is not an empty string
  • StringsJoin(x, []y) -- Joins the items in y with the string x

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 identifier
  • AccountAlias -- Account Name in AWS as defined by the account owner
  • AccountId -- AWS Account Id
  • AccountIdPad -- AWS Account Id with leading zeros if necessary
  • AccountName -- Account Name from config.yaml
  • Arn -- Role ARN
  • DefaultRegion -- Configured default region
  • EmailAddress -- Email address of root account associated with AWS Account
  • ExpiresEpoch -- Unix epoch time when cached STS creds expire
  • Expires -- Hours and minutes until cached STS creds expire
  • Profile -- Value used for $AWS_SSO_PROFILE and the profile name in ~/.aws/config
  • RoleName -- Role name
  • SSO -- AWS SSO instance name
  • Via -- Role Chain Via

LogLevel / LogLines

By default, the LogLevel is 'warn'. 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 Wallet
  • pass - pass (uses GPG on backend)
  • secret-service - Freedesktop.org Secret Service
  • wincred - Windows Credential Manager (default on Windows)
  • json - Cleartext JSON file (very insecure and not recommended). Location can be overridden with JsonStore

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.