From 5451a3a394f0ac3b7656b4fe7787d573f2bd089d Mon Sep 17 00:00:00 2001 From: Lauchlin <1527417+lokulin@users.noreply.github.com> Date: Wed, 21 Dec 2022 15:04:30 +1100 Subject: [PATCH] Deprecation notice (#118) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 😢 --- OLDREADME.md | 263 +++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 261 +------------------------------------------------- 2 files changed, 265 insertions(+), 259 deletions(-) create mode 100644 OLDREADME.md diff --git a/OLDREADME.md b/OLDREADME.md new file mode 100644 index 0000000..0b6d28f --- /dev/null +++ b/OLDREADME.md @@ -0,0 +1,263 @@ +# yak + +[![Build Status](https://github.com/redbubble/yak/actions/workflows/ci.yml/badge.svg)](https://github.com/redbubble/yak/actions) + +A tool to generate access keys for AWS using Okta. If you want a backronym, try 'Your AWS Kredentials'. + +## Usage + +### Installation + +We produce builds of `yak` for macOS and Linux. + +#### macOS with Homebrew + +The easiest option for macOS users is to install `yak` via Homebrew. +This will also help keep `yak` up-to-date when you run `brew upgrade` +as usual. + +```sh +brew tap redbubble/redbubble +brew install yak +``` + +This will also put ZSH and Bash completions in the right spot; they +should be usable next time you reload your shell config. + +#### Ubuntu/Debian APT repository + +`yak` can be installed from our APT repo. This should get you up and +running: + +```sh +sudo apt install curl gnupg2 +# This is the Redbubble GPG key, to verify releases: +curl -Lq https://raw.githubusercontent.com/redbubble/yak/master/static/delivery-engineers.pub.asc | sudo gpg --no-default-keyring --import --keyring gnupg-ring:/etc/apt/trusted.gpg.d/redbubble.gpg +sudo chmod a+r /etc/apt/trusted.gpg.d/redbubble.gpg +echo "deb http://apt.redbubble.com/ stable main" | sudo tee /etc/apt/sources.list.d/redbubble.list +sudo apt update +sudo apt install yak +``` + +#### Standalone DEB/RPM packages + +We generate Deb and RPM packages as part of our release. + +Download the package appropriate for your distro from the [latest +release](https://github.com/redbubble/yak/releases/latest) page. +Unfortunately, this won't give you nice automatic updates. + +#### A note about completions + +We've seen issues using tab-completion on older versions of ZSH. It seems +that version 5.1 or newer will work correctly. + +#### Manually + +Download the [latest release](https://github.com/redbubble/yak/releases/latest) for your architecture. The `yak` executable is statically linked, +so all you should need to do is put the executable somewhere in your `$PATH`. + +This method will not give you tab-completion; if you'd like that, the completions files are available in +[/static/completions](https://github.com/redbubble/yak/tree/master/static/completions). + +### Running + +You can run `yak` like this: + +``` +yak [] +``` + +and will run `command` as `role`. + +More specifically, `yak` runs `command` in the same environment it was called from, with the credentials for `role` +injected as environment variables. + +When run without a command, `yak` prints those variables as `export` statements; this is intended to allow easy sourcing +into your shell. + +If run with the `--list-roles` flag like this: + +``` +yak --list-roles +``` + +`yak` will print a list of available roles and exit. + +Note that to pass `-/--` flags to commands you want to run, you'll need to put a `--` before the +``, to let `yak` know you're done passing flags to *it*, like this: + +``` +yak [flags] -- +``` + +For example: + +``` +yak --cache-only nonprod -- npx cdk --app 'npx ts-node --prefer-ts-exts bin/my-stack.ts' list +``` + + +#### Arguments + +``` + -d, --aws-session-duration int The session duration to request from AWS (in seconds) + --cache-only Only use cache, do not make external requests. Mutually exclusive with --no-cache + --clear-cache Delete all data from yak's cache. If no other arguments are given, exit without error + -h, --help Display this help message and exit + -l, --list-roles List available AWS roles and exit + --no-cache Ignore cache for this request. Mutually exclusive with --cache-only + --okta-aws-saml-endpoint string The app embed path for the AWS app within Okta + --okta-domain string The domain to use for requests to Okta + --okta-mfa-provider string The Okta MFA provider name for login + --okta-mfa-type string The Okta MFA type for login + -u, --okta-username string Your Okta username + -o, --output-format string Can be set to either 'json' or 'env'. The format in which to output credential data + --pinentry Use the pinentry to prompt for credentials, instead of terminal (useful for GUI applications) + --version Print the current version and exit + -- Terminator for -/-- flags. Necessary if you want to pass -/-- flags to commands +``` + +#### Environment Variables + +| Variable | Effect | +|-----------------|--------------------------------------------------------------------------------------------| +| `OKTA_PASSWORD` | The value set in this variable will be passed to Okta as the 'password' component of login | + +Please note that setting the `OKTA_PASSWORD` variable in plain text, especially on the command-line, is not a good idea +from a security perspective. A suggested mode of use for this variable would be something like: + +``` +OKTA_PASSWORD=$(get-password-from-password-manager) yak ... +``` + +### Configuring + +Yak can be configured with a configuration file at `~/.config/yak/config.toml` (`~/.yak/config.toml` is also supported). + +#### Okta Config + +```toml +[okta] +# Required. The URL for your okta domain. +domain = "https://.okta.com" + +# Required. The path for fetching the SAML assertion from okta. +aws_saml_endpoint = "/home///" + +# Optional. Your okta username. +username = "" + +# Optional. Your okta MFA device type and provider so that you don't have to choose. +# Yak supports the following values for mfa_type: token:software:totp, token:hardware or push +# For a full list of Okta-supported factors and providers see [this page](https://developer.okta.com/docs/api/resources/factors#supported-factors-for-providers) +mfa_type = "" +mfa_provider = "" +``` + +##### How to find your config values + +`domain`: This the same domain where you log in to Okta. + +`aws_saml_endpoint`: To get this value, you'll need to: + +1. Log in to Okta +2. Find the AWS application +3. Copy the URL for the AWS application, e.g. by right-clicking and selecting + "Copy Link Address" or similar +4. Remove everything up to `okta.com/` (inclusive) +5. Remove everything from the `?` onwards + +OR ask your organisation's Okta administrator. + +If you're an Okta administrator, you can also: + +1. Log in to Okta +2. Click the "Admin" button +3. Navigate to Applications +4. Open the "Amazon Web Services" application +5. On the General tab, copy the App Embed Link +6. Remove everything up to `okta.com/` (inclusive) + +`username`: The username you use when logging in to Okta. If in doubt, consult +your organisation's Okta administrator. + +#### AWS Config + +```toml +[aws] +# Optional. Duration in seconds for the AWS credentials to last. Default 1 hour, maximum 12 hours. +session_duration = 3600 +``` + +#### Other Config + +```toml +[login] +# Optional. Duration in seconds from the start of the login process until it times out. +timeout = 180 +``` + +```toml +# Optional. Prompt for password and MFA token using pinentry. Useful for when using GUI tools like Lens. +pinentry = true +``` + +#### Aliases + +You can configure *role aliases* in the `[alias]` section of your config file; these can be used instead of having to +remember the whole ARN: + +```toml +[alias] +prod = "arn:aws:some:long:role:path" +``` + +This configuration would allow you to log in with: +``` +yak prod [] +``` + +## Development + +To hack on `yak`, you'll want to get a copy of the source. Then: + +``` +go build +``` + +### Releasing changes + +If you want to do releases, you'll also want the `deb-s3` package. +You'll also want `gnupg2` to be able to sign releases, but i'll leave +installation of that up to you. + +```sh +gem install deb-s3 +``` + +### Running locally + +The `make install` target will compile the application and 'install' it into your `$GOPATH`. + +You can then run `$GOPATH/bin/yak`. + +### Running tests + +Just run: + +``` +make test +``` + +If `gotestsum` isn't available we'll try and install it. +To run tests without gotestsum, or to run the tests for any individual package, you can run: + +``` +go test +``` + +## License + +`yak` is provided under an MIT license. See the [LICENSE](https://github.com/redbubble/yak/blob/master/LICENSE) file for +details. diff --git a/README.md b/README.md index 0b6d28f..7bc02ab 100644 --- a/README.md +++ b/README.md @@ -1,263 +1,6 @@ # yak -[![Build Status](https://github.com/redbubble/yak/actions/workflows/ci.yml/badge.svg)](https://github.com/redbubble/yak/actions) -A tool to generate access keys for AWS using Okta. If you want a backronym, try 'Your AWS Kredentials'. +**:information_source: Due to changes in the way Okta works `yak` is now deprecated. We suggest looking at using the native `aws sso` commands.** -## Usage - -### Installation - -We produce builds of `yak` for macOS and Linux. - -#### macOS with Homebrew - -The easiest option for macOS users is to install `yak` via Homebrew. -This will also help keep `yak` up-to-date when you run `brew upgrade` -as usual. - -```sh -brew tap redbubble/redbubble -brew install yak -``` - -This will also put ZSH and Bash completions in the right spot; they -should be usable next time you reload your shell config. - -#### Ubuntu/Debian APT repository - -`yak` can be installed from our APT repo. This should get you up and -running: - -```sh -sudo apt install curl gnupg2 -# This is the Redbubble GPG key, to verify releases: -curl -Lq https://raw.githubusercontent.com/redbubble/yak/master/static/delivery-engineers.pub.asc | sudo gpg --no-default-keyring --import --keyring gnupg-ring:/etc/apt/trusted.gpg.d/redbubble.gpg -sudo chmod a+r /etc/apt/trusted.gpg.d/redbubble.gpg -echo "deb http://apt.redbubble.com/ stable main" | sudo tee /etc/apt/sources.list.d/redbubble.list -sudo apt update -sudo apt install yak -``` - -#### Standalone DEB/RPM packages - -We generate Deb and RPM packages as part of our release. - -Download the package appropriate for your distro from the [latest -release](https://github.com/redbubble/yak/releases/latest) page. -Unfortunately, this won't give you nice automatic updates. - -#### A note about completions - -We've seen issues using tab-completion on older versions of ZSH. It seems -that version 5.1 or newer will work correctly. - -#### Manually - -Download the [latest release](https://github.com/redbubble/yak/releases/latest) for your architecture. The `yak` executable is statically linked, -so all you should need to do is put the executable somewhere in your `$PATH`. - -This method will not give you tab-completion; if you'd like that, the completions files are available in -[/static/completions](https://github.com/redbubble/yak/tree/master/static/completions). - -### Running - -You can run `yak` like this: - -``` -yak [] -``` - -and will run `command` as `role`. - -More specifically, `yak` runs `command` in the same environment it was called from, with the credentials for `role` -injected as environment variables. - -When run without a command, `yak` prints those variables as `export` statements; this is intended to allow easy sourcing -into your shell. - -If run with the `--list-roles` flag like this: - -``` -yak --list-roles -``` - -`yak` will print a list of available roles and exit. - -Note that to pass `-/--` flags to commands you want to run, you'll need to put a `--` before the -``, to let `yak` know you're done passing flags to *it*, like this: - -``` -yak [flags] -- -``` - -For example: - -``` -yak --cache-only nonprod -- npx cdk --app 'npx ts-node --prefer-ts-exts bin/my-stack.ts' list -``` - - -#### Arguments - -``` - -d, --aws-session-duration int The session duration to request from AWS (in seconds) - --cache-only Only use cache, do not make external requests. Mutually exclusive with --no-cache - --clear-cache Delete all data from yak's cache. If no other arguments are given, exit without error - -h, --help Display this help message and exit - -l, --list-roles List available AWS roles and exit - --no-cache Ignore cache for this request. Mutually exclusive with --cache-only - --okta-aws-saml-endpoint string The app embed path for the AWS app within Okta - --okta-domain string The domain to use for requests to Okta - --okta-mfa-provider string The Okta MFA provider name for login - --okta-mfa-type string The Okta MFA type for login - -u, --okta-username string Your Okta username - -o, --output-format string Can be set to either 'json' or 'env'. The format in which to output credential data - --pinentry Use the pinentry to prompt for credentials, instead of terminal (useful for GUI applications) - --version Print the current version and exit - -- Terminator for -/-- flags. Necessary if you want to pass -/-- flags to commands -``` - -#### Environment Variables - -| Variable | Effect | -|-----------------|--------------------------------------------------------------------------------------------| -| `OKTA_PASSWORD` | The value set in this variable will be passed to Okta as the 'password' component of login | - -Please note that setting the `OKTA_PASSWORD` variable in plain text, especially on the command-line, is not a good idea -from a security perspective. A suggested mode of use for this variable would be something like: - -``` -OKTA_PASSWORD=$(get-password-from-password-manager) yak ... -``` - -### Configuring - -Yak can be configured with a configuration file at `~/.config/yak/config.toml` (`~/.yak/config.toml` is also supported). - -#### Okta Config - -```toml -[okta] -# Required. The URL for your okta domain. -domain = "https://.okta.com" - -# Required. The path for fetching the SAML assertion from okta. -aws_saml_endpoint = "/home///" - -# Optional. Your okta username. -username = "" - -# Optional. Your okta MFA device type and provider so that you don't have to choose. -# Yak supports the following values for mfa_type: token:software:totp, token:hardware or push -# For a full list of Okta-supported factors and providers see [this page](https://developer.okta.com/docs/api/resources/factors#supported-factors-for-providers) -mfa_type = "" -mfa_provider = "" -``` - -##### How to find your config values - -`domain`: This the same domain where you log in to Okta. - -`aws_saml_endpoint`: To get this value, you'll need to: - -1. Log in to Okta -2. Find the AWS application -3. Copy the URL for the AWS application, e.g. by right-clicking and selecting - "Copy Link Address" or similar -4. Remove everything up to `okta.com/` (inclusive) -5. Remove everything from the `?` onwards - -OR ask your organisation's Okta administrator. - -If you're an Okta administrator, you can also: - -1. Log in to Okta -2. Click the "Admin" button -3. Navigate to Applications -4. Open the "Amazon Web Services" application -5. On the General tab, copy the App Embed Link -6. Remove everything up to `okta.com/` (inclusive) - -`username`: The username you use when logging in to Okta. If in doubt, consult -your organisation's Okta administrator. - -#### AWS Config - -```toml -[aws] -# Optional. Duration in seconds for the AWS credentials to last. Default 1 hour, maximum 12 hours. -session_duration = 3600 -``` - -#### Other Config - -```toml -[login] -# Optional. Duration in seconds from the start of the login process until it times out. -timeout = 180 -``` - -```toml -# Optional. Prompt for password and MFA token using pinentry. Useful for when using GUI tools like Lens. -pinentry = true -``` - -#### Aliases - -You can configure *role aliases* in the `[alias]` section of your config file; these can be used instead of having to -remember the whole ARN: - -```toml -[alias] -prod = "arn:aws:some:long:role:path" -``` - -This configuration would allow you to log in with: -``` -yak prod [] -``` - -## Development - -To hack on `yak`, you'll want to get a copy of the source. Then: - -``` -go build -``` - -### Releasing changes - -If you want to do releases, you'll also want the `deb-s3` package. -You'll also want `gnupg2` to be able to sign releases, but i'll leave -installation of that up to you. - -```sh -gem install deb-s3 -``` - -### Running locally - -The `make install` target will compile the application and 'install' it into your `$GOPATH`. - -You can then run `$GOPATH/bin/yak`. - -### Running tests - -Just run: - -``` -make test -``` - -If `gotestsum` isn't available we'll try and install it. -To run tests without gotestsum, or to run the tests for any individual package, you can run: - -``` -go test -``` - -## License - -`yak` is provided under an MIT license. See the [LICENSE](https://github.com/redbubble/yak/blob/master/LICENSE) file for -details. +[Old README.md](OLDREADME.md)