-
Notifications
You must be signed in to change notification settings - Fork 27
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
7 changed files
with
86 additions
and
74 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -2,20 +2,21 @@ | |
|
|
||
| * [Command line Usage](#command-line-usage) | ||
| * [Default usage](#default-usage) | ||
| * [Multi-tile-Guide](#multi-tile-guide) | ||
| * [Multi-tile-Guide](#multi-tile-guide) | ||
| * [Single-command usage](#single-command-usage) | ||
| * [Additional command line reference](#additional-command-line-reference) | ||
| * [Environment variables and user configuration](#environment-variables-and-user-configuration) | ||
| * [Precedence](#precedence) | ||
| * [Environment variables and user configuration table](#environment-variables-and-user-configuration-table) | ||
| * [Configuration file location](#configuration-file-location) | ||
| * [AWS Roles Discovery](#aws-roles-discovery) | ||
| * [Supported MFAs](#supported-mfas) | ||
| * [To upgrade](#to-upgrade) | ||
| * [Installing from github](#installing-from-github) | ||
| * [Upgrading](#to-upgrade) | ||
| * [Installing from GitHub](#installing-from-github) | ||
| * [Troubleshooting](#troubleshooting) | ||
| * [Design and Limitations](#design-and-limitations) | ||
|
|
||
| # Command line Usage | ||
| # Command line Usage | ||
|
|
||
| ## Default usage | ||
|
|
||
|
|
@@ -28,8 +29,7 @@ Then execute: `tokendito` in your command line. | |
|
|
||
| If you have multiple AWS-type Okta tiles assigned to you, please update | ||
| your local [tokendito.ini](tokendito.ini.md) file with the links to | ||
| your AWS tiles in Okta. You can get the link to your tile by right | ||
| clicking on the tile in Okta and selecting \"Copy Link URL.\" This file | ||
| your AWS tiles in Okta. You can get the link to your tile by right-clicking on the tile in Okta and selecting \"Copy Link URL.\" This file | ||
| supports multiple profiles, in case there is a need to connect with | ||
| different Okta Orgs and tiles. tokendito can access the profiles by | ||
| name, by passing in the `--profile` parameter. | ||
|
|
@@ -47,14 +47,14 @@ You can just pass in your information at runtime: | |
|
|
||
| ``` sh | ||
| tokendito --username [email protected] \ | ||
| --role-arn arn:aws:iam::123456789000:role/dowjones-hammer-engineer \ | ||
| --role-arn arn:aws:iam::123456789000:role/dowjones-engineer \ | ||
| --okta-mfa push \ | ||
| --okta-aws-tile https://acme.oktapreview.com/home/amazon_aws/b07384d113edec49eaa6/123 \ | ||
| ``` | ||
|
|
||
| Or you can put your parameters into a single [profile](tokendito.ini.md) and reference that profile. | ||
|
|
||
| ``` txt | ||
| ``` | ||
| [engineer] | ||
| okta_aws_tile = https://acme.oktapreview.com/home/amazon_aws/b07384d113edec49eaa6/123 | ||
| okta_username = [email protected] | ||
|
|
@@ -68,24 +68,24 @@ And execute: | |
| tokendito --profile engineer | ||
| ``` | ||
|
|
||
| ## Additional command line reference | ||
| ## Additional command line reference | ||
|
|
||
| ``` txt | ||
| usage: tokendito [-h] [--version] [--configure] [--username OKTA_USERNAME] [--password OKTA_PASSWORD] [--profile USER_CONFIG_PROFILE] [--config-file USER_CONFIG_FILE] | ||
| [--loglevel {DEBUG,INFO,WARN,ERROR}] [--log-output-file USER_LOG_OUTPUT_FILE] [--aws-config-file AWS_CONFIG_FILE] [--aws-output AWS_OUTPUT] | ||
| [--aws-profile AWS_PROFILE] [--aws-region AWS_REGION] [--aws-role-arn AWS_ROLE_ARN] [--aws-shared-credentials-file AWS_SHARED_CREDENTIALS_FILE] | ||
| [--okta-org OKTA_ORG | --okta-tile OKTA_TILE] [--okta-mfa OKTA_MFA] [--okta-mfa-response OKTA_MFA_RESPONSE] [--quiet] | ||
| Gets a STS token to use with the AWS CLI and SDK. | ||
| Gets an STS token to use with the AWS CLI and SDK. | ||
| options: | ||
| -h, --help show this help message and exit | ||
| --version Displays version and exit | ||
| --configure Prompt user for configuration parameters | ||
| --username OKTA_USERNAME | ||
| username to login to Okta. You can also use the OKTA_USERNAME environment variable. | ||
| username to log in to Okta. You can also use the OKTA_USERNAME environment variable. | ||
| --password OKTA_PASSWORD | ||
| password to login to Okta. You can also user the OKTA_PASSWORD environment variable. | ||
| password to log in to Okta. You can also use the OKTA_PASSWORD environment variable. | ||
| --profile USER_CONFIG_PROFILE | ||
| Tokendito configuration profile to use. | ||
| --config-file USER_CONFIG_FILE | ||
|
|
@@ -112,60 +112,72 @@ options: | |
| --okta-mfa OKTA_MFA Sets the MFA method | ||
| --okta-mfa-response OKTA_MFA_RESPONSE | ||
| Sets the MFA response to a challenge | ||
| --quiet Suppress output``` | ||
| --quiet Suppress output | ||
| ``` | ||
| Regarding the Okta password, we are fans of automation but do not | ||
| recommend passing in the password to tokendito via plaintext or storing | ||
|
|
||
| Regarding the storage of the Okta password, we are fans of automation but do not recommend passing in the password to tokendito via plaintext or storing | ||
| it in your environment locally. | ||
|
|
||
|
|
||
| # Environment variables and user configuration | ||
| tokendito supports the use of environment variables and user configuration equivalent to specify the default values for most options. | ||
|
|
||
| tokendito supports the use of environment variables and user configuration equivalents to specify the default values for most options. | ||
|
|
||
| ## Precedence | ||
| Credentials and configuration settings take precedence in the following order: | ||
| 1) Command line options -- Overrides settings in any other location. You can specify \--username, \--role-arn, \--okta-aws-tile, and \--okta-mfa as parameters on the command line. | ||
| 2) Environment variables -- You can store values in your system\'s environment variables. It overrides the configuration file. | ||
| 3) User configuration file -- The user configuration file is updated when you run the command tokendito \--configure. tokendito uses [platformdirs](https://github.com/platformdirs/platformdirs) to store user configuration in the [tokendito.ini](tokendito.ini.md) file. This file can contain the credential details for the default profile and any named profiles. | ||
|
|
||
| Credentials and configuration settings take precedence in the following order: | ||
|
|
||
| 1. Command line options -- Overrides settings in any other location. You can specify `--username`, `--role-arn`, `--okta-aws-tile`, and `--okta-mfa` as parameters on the command line. | ||
| 1. Environment variables -- You can store values in your system\'s environment variables. It overrides the configuration file. | ||
| 1. User configuration file -- The user configuration file is updated when you run the command tokendito \--configure. Tokendito uses [platformdirs](https://github.com/platformdirs/platformdirs) to store user configuration in the [tokendito.ini](tokendito.ini.md) file. This file can contain the credential details for the default profile and any named profiles. | ||
|
|
||
| ## Environment variables and user configuration table | ||
|
|
||
| The following table lists the environment variable and user configuration entry equivalent for the given command line option. | ||
|
|
||
| | Command line option | Environment variable | User configuration | | ||
| | ------------------- | -------------------- | ------------------ | | ||
| | --username | TOKENDITO_OKTA_USERNAME | okta_username | | ||
| | --password | TOKENDITO_OKTA_PASSWORD | | | ||
| | --profile | TOKENDITO_USER_CONFIG_PROFILE | profile | | ||
| | --config-file | TOKENDITO_USER_CONFIG_FILE | | | ||
| | --loglevel | TOKENDITO_USER_LOGLEVEL | loglevel | | ||
| | --log-output-file | TOKENDITO_USER_LOG_OUTPUT_FILE | log_output_file | | ||
| | --aws-config-file | TOKENDITO_AWS_CONFIG_FILE | aws_config_file | | ||
| | --aws-output | TOKENDITO_AWS_OUTPUT | aws_output | | ||
| | --aws-profile | TOKENDITO_AWS_PROFILE | aws_profile | | ||
| | --aws-region | TOKENDITO_AWS_REGION | aws_region | | ||
| | --aws-role-arn | TOKENDITO_AWS_ROLE_ARN | aws_role_arn | | ||
| | --aws-shared-credentials-file | TOKENDITO_AWS_SHARED_CREDENTIALS_FILE | aws_shared_credentials_file | | ||
| | --okta-org | TOKENDITO_OKTA_ORG | okta_org | | ||
| | --okta-tile | TOKENDITO_OKTA_TILE | okta_tile | | ||
| | --okta-mfa | TOKENDITO_OKTA_MFA | okta_mfa | | ||
| | --okta-mfa-response | TOKENDITO_OKTA_MFA_RESPONSE | okta_mfa_response | | ||
| | --quiet | TOKENDITO_USER_QUIET | quiet | | ||
| | `--username` | `TOKENDITO_OKTA_USERNAME` | `okta_username` | | ||
| | `--password` | `TOKENDITO_OKTA_PASSWORD` | | | ||
| | `--profile` | `TOKENDITO_USER_CONFIG_PROFILE` | `profile` | | ||
| | `--config-file` | `TOKENDITO_USER_CONFIG_FILE` | | | ||
| | `--loglevel` | `TOKENDITO_USER_LOGLEVEL` | `loglevel` | | ||
| | `--log-output-file` | `TOKENDITO_USER_LOG_OUTPUT_FILE` | `log_output_file` | | ||
| | `--aws-config-file` | `TOKENDITO_AWS_CONFIG_FILE` | `aws_config_file` | | ||
| | `--aws-output` | `TOKENDITO_AWS_OUTPUT` | `aws_output` | | ||
| | `--aws-profile` | `TOKENDITO_AWS_PROFILE` | `aws_profile` | | ||
| | `--aws-region` | `TOKENDITO_AWS_REGION` | `aws_region` | | ||
| | `--aws-role-arn` | `TOKENDITO_AWS_ROLE_ARN` | `aws_role_arn` | | ||
| | `--aws-shared-credentials-file` | `TOKENDITO_AWS_SHARED_CREDENTIALS_FILE` | `aws_shared_credentials_file` | | ||
| | `--okta-org` | `TOKENDITO_OKTA_ORG` | `okta_org` | | ||
| | `--okta-tile` | `TOKENDITO_OKTA_TILE` | `okta_tile` | | ||
| | `--okta-mfa` | `TOKENDITO_OKTA_MFA` | `okta_mfa` | | ||
| | `--okta-mfa-response` | `TOKENDITO_OKTA_MFA_RESPONSE` | `okta_mfa_response` | | ||
| | `--quiet` | `TOKENDITO_USER_QUIET` | `quiet` | | ||
|
|
||
| # Configuration file location | ||
|
|
||
| With Tokendito version 2.0 we changed the location of the configuration file from `$HOME/.aws/okta_auth` to be platform-independent, and following the standard location for configuration files in each supported platform. `tokendito --help` will show the exact location on your system. | ||
|
|
||
| * On Linux: `/home/<username>/.config/tokendito/tokendito.ini` | ||
| * On MacOS: `/Users/<username>/Library/Preferences/tokendito/tokendito.ini` | ||
| * On Windows: `%USERPROFILE%\AppData\Local\tokendito\tokendito.ini` | ||
|
|
||
| # AWS Roles Discovery | ||
| tokendito will discover all your available AWS Roles configured in Okta, returning a list for you to select from, simply by calling: | ||
| ```tokendito --okta-org ${YOUR ORG OKTA URL}``` | ||
| `tokendito --okta-org ${YOUR ORG OKTA URL}`. For instance, `tokendito --okta-org https://acme.oktapreview.com` | ||
|
|
||
| # Supported MFAs | ||
| # Supported MFA methods | ||
|
|
||
| - Native Okta factors (push, call, sms, TOTP) except Biometrics (FIDO webauthn) | ||
| - Google Authenticator TOTP | ||
| - Duo (push, call, sms, TOTP) | ||
| - Native Okta factors (Push, phone call, SMS, TOTP) except Biometrics (FIDO WebAuthn) and Number Challenge | ||
| - Google Authenticator TOTP | ||
| - Duo Push, phone call, SMS, and TOTP | ||
|
|
||
| # To upgrade | ||
| # Upgrading | ||
|
|
||
| `pip install --upgrade tokendito` | ||
|
|
||
| # Installing from github | ||
| # Installing from GitHub | ||
|
|
||
| `pip install git+ssh://[email protected]/dowjones/tokendito.git@<version>` | ||
|
|
||
|
|
@@ -185,6 +197,6 @@ validating your environment\'s AWS configuration profile(s) located at: | |
|
|
||
| # Design and Limitations | ||
|
|
||
| - This tool does not cache and reuse Okta session IDs | ||
| - This tool does not cache and reuse Okta session IDs. | ||
|
|
||
| [Pull requests welcome](CONTRIBUTING.md)! | ||
| [Pull requests](CONTRIBUTING.md) welcome! | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,4 +1,5 @@ | ||
| tokendito uses [platformdirs](https://github.com/platformdirs/platformdirs) to manage the location of the user configuration file tokendito.ini. That file may contain different configuration for different profiles, as: | ||
| Tokendito uses [platformdirs](https://github.com/platformdirs/platformdirs) to manage the location of the user configuration file `tokendito.ini`. That file may contain different profiles, as: | ||
|
|
||
| ``` | ||
| [default] | ||
| okta_org = https://acme.okta.com/ | ||
|
|
@@ -12,4 +13,5 @@ okta_tile = https://acme.okta.com/home/amazon_aws/b07384d113edec49f00d/272?fromH | |
| okta_tile = https://acme.oktapreview.com/home/amazon_aws/b07384d113edec49eaa6/123 | ||
| okta_username = [email protected] | ||
| ``` | ||
| to select a given profile, use the `--profile $name` option, otherwise the default profile will be selected. In the above tokendito.ini file, using `--profile my_dev_okta_tile` would select the configuration values for the [my_dev_okta_tile] profile. | ||
|
|
||
| to select a given profile, use the `--profile $name` option, otherwise the default profile will be selected. In the above tokendito.ini file, using `--profile my_dev_okta_tile` would select the configuration values for the `[my_dev_okta_tile]` profile. | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,19 +1,17 @@ | ||
| --- | ||
| title: Testing | ||
| --- | ||
| # Testing | ||
|
|
||
| To run basic tests, execute: | ||
|
|
||
| `py.test -v -rA -k 'unit' -s tests`. This will run unit tests, and skip | ||
| functional (end to end) testing. | ||
| functional (end-to-end) testing. | ||
|
|
||
| To run end to end tests, use `py.test -v -rA -k 'functional' -s tests` | ||
| To run end-to-end tests, use `py.test -v -rA -k 'functional' -s tests` | ||
| instead. Several other arguments can be provided so that the tool can | ||
| run in non-interactive mode. Currently, config file, arguments, and | ||
| run in non-interactive mode. Currently, the config file, arguments, and | ||
| environment variables (mix and match) are supported. The syntax is the | ||
| same as for `tokendito`. | ||
|
|
||
| If all of username, password, mfa, tile url, and role ARN are passed to | ||
| If all of the username, password, MFA, tile URL, and role ARN are passed to | ||
| `py.test`, then two other tests are kicked off. The first will execute | ||
| `tokendito` and try to obtain STS tokens the same way that a normal user | ||
| would. The second will run `sts get-caller-identity` and validate the | ||
|
|
@@ -27,21 +25,21 @@ py.test -v -rA -s tests --config-file=/tmp/my-tokendito-config.ini | |
|
|
||
| Where the config file has valid configuration items for the tool. | ||
|
|
||
| # Example 2 | ||
| ## Example 2 | ||
|
|
||
| ``` sh | ||
| py.test -v -rA -k 'functional' -s tests \ | ||
| [email protected] \ | ||
| --password=mysecretpass \ | ||
| --okta-mfa=push \ | ||
| --okta-tile='https://acme.oktapreview.com/home/amazon_aws/b07384d113edec49eaa6/123' \ | ||
| --aws-role-arn=arn:aws:iam::123456789000:role/dowjones-hammer-engineer | ||
| --aws-role-arn=arn:aws:iam::123456789000:role/dowjones-engineer | ||
| ``` | ||
|
|
||
| This triggers the tests `test_generate_credentials` and | ||
| `test_aws_credentials` that are normally skipped. | ||
|
|
||
| # Example 3 | ||
| ## Example 3 | ||
|
|
||
| ``` sh | ||
| TOKENDITO_OKTA_MFA_METHOD=push py.test -v -rA -k 'functional' -s tests --username=... | ||
|
|
@@ -50,7 +48,7 @@ TOKENDITO_OKTA_MFA_METHOD=push py.test -v -rA -k 'functional' -s tests --usernam | |
| This shows how to mix environment variables with `py.test` and | ||
| arguments. | ||
|
|
||
| # Example 4 | ||
| ## Example 4 | ||
|
|
||
| ``` sh | ||
| TOKENDITO_OKTA_PASSWORD='mysecretpass' tox -e auth -- --username='[email protected]' | ||
|
|
||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters