From b529c911ec35ab62f3239e118875468ce6f4d9e6 Mon Sep 17 00:00:00 2001 From: pcmxgti <16561338+pcmxgti@users.noreply.github.com> Date: Fri, 13 Jan 2023 15:54:20 -0500 Subject: [PATCH] Fix spelling and gramar (#108) --- README.md | 14 +++--- docs/README.md | 104 +++++++++++++++++++++++------------------- docs/tokendito.ini.md | 6 ++- tests/README.md | 20 ++++---- tests/conftest.py | 4 +- tokendito/okta.py | 2 +- tokendito/user.py | 10 ++-- 7 files changed, 86 insertions(+), 74 deletions(-) diff --git a/README.md b/README.md index 6ae4a881..8c025459 100644 --- a/README.md +++ b/README.md @@ -4,12 +4,12 @@ ## Generate temporary AWS credentials via Okta. -[![image](https://github.com/dowjones/tokendito/workflows/Lint%20and%20Test/badge.svg)](https://github.com/dowjones/tokendito/actions) -[![image](https://img.shields.io/badge/python-3.7%2C%203.8%2C%203.9%2C%203.10%2C%203.11-blueviolet)](https://pypi.org/project/tokendito/) -[![image](https://github.com/dowjones/tokendito/workflows/Woke/badge.svg)](https://github.com/dowjones/tokendito/actions) +[![image](https://img.shields.io/github/actions/workflow/status/dowjones/tokendito/test.yml)](https://github.com/dowjones/tokendito/actions) +[![image](https://img.shields.io/pypi/pyversions/tokendito?color=blueviolet)](https://pypi.org/project/tokendito/) +[![image](https://img.shields.io/github/actions/workflow/status/dowjones/tokendito/woke.yml?label=woke)](https://github.com/dowjones/tokendito/actions) [![image](https://img.shields.io/badge/license-Apache%202.0-ff69b4)](https://github.com/dowjones/tokendito/blob/main/LICENSE.txt) [![image](https://img.shields.io/badge/OS-Mac%2C%20Windows%2C%20Linux-9cf)](https://github.com/dowjones/tokendito/) -[![image](https://coveralls.io/repos/github/dowjones/tokendito/badge.svg)](https://coveralls.io/github/dowjones/tokendito) +[![image](https://img.shields.io/coverallsCoverage/github/dowjones/tokendito)](https://coveralls.io/github/dowjones/tokendito) [![image](https://img.shields.io/pypi/dm/tokendito)](https://pypistats.org/packages/tokendito) # @@ -28,11 +28,11 @@ The following changes are part of this release: - Set the config file to be platform dependent, and follow the XDG standard. - Extend configuration capabilities. - Modernize output. -- Change mfa method from strict match to partial match. +- Change the MFA method from strict match to partial match. - Mask secrets from output logs. - Automatically discover AWS URLs. - Fix authentication with DUO. -- Add support for setting loglevel via ini file and env vars. +- Add support for setting the logging level via both the INI file and ENV vars. - Add support for Python 3.9 and 3.10. - And many fixes. @@ -43,7 +43,7 @@ Consult [additional notes](docs/README.md) for how to use tokendito. - Python 3.7+ - AWS account(s) federated with Okta -Tokendito is compatible with python 3, and can be installed with either +Tokendito is compatible with Python 3 and can be installed with either pip or pip3. ## Getting started diff --git a/docs/README.md b/docs/README.md index 13c7b21c..2df30dfb 100644 --- a/docs/README.md +++ b/docs/README.md @@ -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 prod_service_user@company.com \ ---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 = jane.doe@acme.com @@ -68,7 +68,7 @@ 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] @@ -76,16 +76,16 @@ usage: tokendito [-h] [--version] [--configure] [--username OKTA_USERNAME] [--pa [--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//.config/tokendito/tokendito.ini` +* On MacOS: `/Users//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://git@github.com/dowjones/tokendito.git@` @@ -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! diff --git a/docs/tokendito.ini.md b/docs/tokendito.ini.md index e8850455..4a807318 100644 --- a/docs/tokendito.ini.md +++ b/docs/tokendito.ini.md @@ -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 = jane.doe@acme.com ``` -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. diff --git a/tests/README.md b/tests/README.md index f2be0a4e..d9fbdefd 100644 --- a/tests/README.md +++ b/tests/README.md @@ -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,7 +25,7 @@ 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 \ @@ -35,13 +33,13 @@ py.test -v -rA -k 'functional' -s tests \ --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='jane.doe@mycompany.com' diff --git a/tests/conftest.py b/tests/conftest.py index 3360262e..c3d4438d 100644 --- a/tests/conftest.py +++ b/tests/conftest.py @@ -5,8 +5,8 @@ def pytest_addoption(parser): """Add command-line options for running functional tests with credentials.""" - parser.addoption("--username", default="", help="username to login to Okta") - parser.addoption("--password", default="", help="password to login to Okta.") + parser.addoption("--username", default="", help="username to log in to Okta") + parser.addoption("--password", default="", help="password to log in to Okta.") parser.addoption("--okta-tile", default=None, help="Okta tile URL to use.") parser.addoption("--okta-mfa", default=None, help="Sets the MFA method") parser.addoption( diff --git a/tokendito/okta.py b/tokendito/okta.py index c6686e0b..3c8a82a5 100644 --- a/tokendito/okta.py +++ b/tokendito/okta.py @@ -261,7 +261,7 @@ def user_mfa_options(selected_mfa_option, headers, mfa_challenge_url, payload, p if config.okta["mfa_response"] is None: logger.debug("Getting verification code from user.") - config.okta["mfa_response"] = user.get_input("Enter your verification code:") + config.okta["mfa_response"] = user.get_input("Enter your verification code: ") user.add_sensitive_value_to_be_masked(config.okta["mfa_response"]) # time to verify the mfa diff --git a/tokendito/user.py b/tokendito/user.py index b04e5c58..ae020202 100644 --- a/tokendito/user.py +++ b/tokendito/user.py @@ -60,7 +60,7 @@ def parse_cli_args(args): :return: args parse object """ parser = argparse.ArgumentParser( - prog="tokendito", description="Gets a STS token to use with the AWS CLI and SDK." + prog="tokendito", description="Gets an STS token to use with the AWS CLI and SDK." ) parser.add_argument("--version", action="store_true", help="Displays version and exit") parser.add_argument( @@ -71,14 +71,14 @@ def parse_cli_args(args): parser.add_argument( "--username", dest="okta_username", - help="username to login to Okta. You can " + help="username to log in to Okta. You can " "also use the OKTA_USERNAME environment variable.", ) parser.add_argument( "--password", dest="okta_password", - help="password to login to Okta. You " - "can also user the OKTA_PASSWORD environment variable.", + help="password to log in to Okta. You " + "can also use the OKTA_PASSWORD environment variable.", ) parser.add_argument( "--profile", @@ -752,7 +752,7 @@ def get_interactive_config(tile=None, org=None, username=""): # We need either one of these two: while not validate_okta_org(org) and not validate_okta_tile(tile): - print("\n\nPlease enter either your Organization URL, a tileURL, or both.") + print("\n\nPlease enter either your Organization URL, a tile URL, or both.") org = get_org() tile = get_tile()