Skip to content

Commit

Permalink
Merge pull request #182 from synfinatic/improve-docs
Browse files Browse the repository at this point in the history 
improve docs
  • Loading branch information
@synfinatic
synfinatic authored Dec 16, 2021
2 parents 2d1f4f7 + 7aa9f65 commit 8b208bf
Show file tree
Hide file tree
Showing 4 changed files with 297 additions and 290 deletions.
306 changes: 19 additions & 287 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,9 +7,10 @@
* [What does AWS SSO CLI do?](#what-does-aws-sso-cli-do)
* [Demo](#demo)
* [Installation](#installation)
* [Quick Setup](#quick-setup)
* [Security](#security)
* [Commands](#commands)
* [Configuration](#configuration)
* [Configuration](docs/config.md)
* [Environment Varables](#environment-varables)
* [Release History](#release-history)
* [License](#license)
Expand Down Expand Up @@ -58,14 +59,27 @@ and then run commands in that context (by default it starts a new shell).
* Option 3: Install via [Homebrew](https://brew.sh)
1. Run `brew install synfinatic/aws-sso-cli/aws-sso-cli`
* Option 4: Build from source:
1. Install [GoLang](https://golang.org) and GNU Make
1. Install [GoLang](https://golang.org) v1.17+ and GNU Make
1. Clone this repo
1. Run `make` (or `gmake` for GNU Make)
1. Your binary will be created in the `dist` directory
1. Run `make install` to install in /usr/local/bin

Note that the release binaries are not officially signed at this time so MacOS
and Windows systems may generate warnings.
Note that the release binaries and packages are not officially signed at this time so
systems may generate warnings.

## Quick Setup

After installation, running `aws-sso` with no arguments will cause it to automatically
run through the setup wizard and ask you a few questions to get started:

* SSO Instance Name ([DefaultSSO](docs/config.md#DefaultSSO))
* SSO Start URL ([StartUrl](docs/config.md#StartUrl))
* AWS SSO Region ([SSORegion](docs/config.md#SSORegion))
* Default region for connecting to AWS ([DefaultRegion](docs/config.md#DefaultRegion))
* Default action to take with URls ([UrlAction](docs/config.md#UrlAction))
* Maximum number of History items to keep ([HistoryLimit](docs/config.md#HistoryLimit))
* Number of minutes to keep items in History ([HistoryMinutes](docs/config.md#HistoryMinutes))

## Security

Expand Down Expand Up @@ -289,288 +303,6 @@ Configures your appropriate shell configuration file to add auto-complete
functionality for commands, flags and options. Must restart your shell
for this to take effect.

## Configuration

Anytime you you run `aws-sso` and it does not find it's configuration file, it
will prompt you via a series of questions to do a basic configuration to get
started.

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.


```yaml
SSOConfig:
<Name of AWS SSO>:
SSORegion: <AWS Region where AWS SSO is deployed>
StartUrl: <URL for AWS SSO Portal>
DefaultRegion: <AWS_DEFAULT_REGION>
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>:
DefaultRegion: <AWS_DEFAULT_REGION>
Tags: # tags specific for this role (will override account level tags)
<Key1>: <Value1>
<Key2>: <Value2>

# See description below for these options
DefaultRegion: <AWS_DEFAULT_REGION>
Browser: <path to web browser>
DefaultSSO: <name of AWS SSO>
LogLevel: [error|warn|info|debug|trace]
LogLines: [true|false]
UrlAction: [print|open|clip]
ConsoleDuration: <minutes>
SecureStore: [file|keychain|kwallet|pass|secret-service|wincred|json]
JsonStore: <path to json file>
ProfileFormat: "<template>"
AccountPrimaryTag:
- <tag 1>
- <tag 2>
- <tag N>
PromptColors:
<Option 1>: <Color>
<Option 2>: <Color>
<Option N>: <Color>
HistoryLimit: <integer>
HistoryMinutes: <integer>
ListFields:
- <field 1>
- <field 2>
- <field N>
```
### 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 has a unique start URL hosted by AWS for interacting with your
SSO provider (Okta/OneLogin/etc).

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:

1. `SSOConfig -> <Name of the AWS SSO> -> Accounts -> <AccountId> -> Roles -> <RoleName>`
1. `SSOConfig -> <Name of the AWS SSO> -> Accounts -> <AccountId>`
1. `SSOConfig -> <Name of AWS SSO>`
1. Top level of the file

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

### Options

#### Browser / UrlAction

`UrlAction` gives you control over how AWS SSO and AWS Console URLs are opened in a browser:

* `print` -- Prints the URL in your terminal
* `open` -- Opens the URL in your default browser or the browser you specified via `--browser` or `Browser`
* `clip` -- Copies the URL to your clipboard

If `Browser` is not set, then your default browser will be used. Note that
your browser needs to support Javascript for the AWS SSO user interface.

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

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

#### ConsoleDuration

By default, the `console` command opens AWS Console sessions which are valid for 60 minutes.
If you wish to override the default session duration, you can specify the number of minutes here
or with the `--duration` flag.

#### SecureStore / JsonStore

`SecureStore` supports the following backends:

* `file` - Encrypted local files (OS agnostic and default)
* `keychain` - macOS [Keychain](https://support.apple.com/guide/mac-help/use-keychains-to-store-passwords-mchlf375f392/mac)
* `kwallet` - [KDE Wallet](https://utils.kde.org/projects/kwalletmanager/)
* `pass` - [pass](https://www.passwordstore.org)
* `secret-service` - Freedesktop.org [Secret Service](https://specifications.freedesktop.org/secret-service/latest/re01.html)
* `wincred` - Windows [Credential Manager](https://support.microsoft.com/en-us/windows/accessing-credential-manager-1b5c916a-6a16-889f-8581-fc16e8165ac0)
* `json` - Cleartext JSON file (very insecure and not recommended). Location can be overridden with `JsonStore`

#### ProfileFormat

AWS SSO CLI can set an environment variable named `AWS_SSO_PROFILE` with
any value you can express using a [Go Template](https://pkg.go.dev/text/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)
* `AccountAlias` -- AWS Account Alias defined in AWS
* `AccountName` -- AWS Account Name defined in AWS or overridden in AWS SSO's config
* `EmailAddress` -- Root account email address associated with the account in AWS
* `Expires` -- When your API credentials expire (string)
* `Arn` -- AWS ARN for this role
* `RoleName` -- The role name
* `Profile` -- Manually configured AWS_SSO_PROFILE value for this role
* `DefaultRegion` -- The manually configured default region for this role
* `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
<!--
issue: #38
* `Via` -- Role AWS SSO CLI will assume before assuming this role
-->

The following functions are available in your template:

* `AccountIdStr(x)` -- Converts an AWS Account ID to a string
* `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 `x` with the string `y`

**Note:** Unlike most values stored in the `config.yaml`, because `ProfileFormat`
values often start with a `{` you will need to quote the value for it to be valid
YAML.

#### 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](
https://pkg.go.dev/github.com/c-bata/go-prompt#Option).

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.

#### ListFields

Specify which fields to display via the `list` command. Valid options are:

* `Id` -- Unique row identifier
* `AccountId` -- AWS Account Id
* `AccountName` -- Account Name from config.yaml
* `AccountAlias` -- Account Name from AWS SSO
* `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
* `ExpiresStr` -- Hours and minutes until cached STS creds expire
* `RoleName` -- Role name
* `SSORegion` -- Region of AWS SSO instance
* `StartUrl` -- AWS SSO Start Url
<!--
* `Profile` -- ???
* `Via` -- Previous ARN of role to assume
-->

## Environment Varables

### Honored Variables
Expand All @@ -588,7 +320,7 @@ The following environment variables are honored by `aws-sso`:
The `file` SecureStore will use the `AWS_SSO_FILE_PASSPHRASE` environment
variable for the passphrase if it is set. (Not recommended.)

### Set Variables
### Managed Variables

The following [AWS environment variables](
https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-envvars.html)
Expand Down
4 changes: 2 additions & 2 deletions cmd/setup_cmd.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -165,7 +165,7 @@ func setupWizard(ctx *RunContext) error {
// HistoryLimit
if ctx.Cli.Setup.HistoryLimit < 0 {
prompt = promptui.Prompt{
Label: "Maximum number of History items to keep",
Label: "Maximum number of History items to keep (HistoryLimit)",
Validate: validateInteger,
Default: "10",
Pointer: promptui.PipeCursor,
Expand All @@ -180,7 +180,7 @@ func setupWizard(ctx *RunContext) error {

if ctx.Cli.Setup.HistoryMinutes < 0 {
prompt = promptui.Prompt{
Label: "Number of minutes to keep items in History",
Label: "Number of minutes to keep items in History (HistoryMinutes)",
Validate: validateInteger,
Default: "1440",
Pointer: promptui.PipeCursor,
Expand Down
2 changes: 1 addition & 1 deletion docs/FAQ.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@
2. Choose the `login` keychain
3. Find the entry named `aws-sso-cli` and right click -> `Delete "aws-sso-cli"`

### How does AWS SSO manage the $AWS_DEFAULT_REGION?
### How does AWS SSO manage the $AWS\_DEFAULT\_REGION?

AWS SSO will leave the `$AWS_DEFAULT_REGION` environment variable alone
unless the following are all true:
Expand Down
Loading

0 comments on commit 8b208bf

Please sign in to comment.