Skip to content

Commit

Permalink
Fix spelling and gramar
Browse files Browse the repository at this point in the history
  • Loading branch information
@pcmxgti
pcmxgti committed Jan 13, 2023
1 parent 5ce225d commit 9d8de9d
Show file tree
Hide file tree
Showing 5 changed files with 82 additions and 70 deletions.
14 changes: 7 additions & 7 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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)

#

Expand All @@ -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.

Expand All @@ -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
Expand Down
104 changes: 58 additions & 46 deletions docs/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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.
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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://git@github.com/dowjones/tokendito.git@<version>`

Expand All @@ -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!
6 changes: 4 additions & 2 deletions docs/tokendito.ini.md
View file
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/
Expand All @@ -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.
20 changes: 9 additions & 11 deletions tests/README.md
View file
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
Expand All @@ -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 \
--username=jane.doe@mycompany.com \
--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=...
Expand All @@ -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'
Expand Down
8 changes: 4 additions & 4 deletions tokendito/user.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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(
Expand All @@ -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",
Expand Down

0 comments on commit 9d8de9d

Please sign in to comment.