Metadata-Version: 2.4
Name: swaj
Version: 1.0
Summary: AWS + CLI + MFA (pronounced like swage)
Home-page: https://github.com/f0rk/swaj
Author: Ryan P. Kelly
Author-email: ryan@ryankelly.us
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: System :: Systems Administration
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: botocore
Requires-Dist: lockfile
Requires-Dist: python-dateutil
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-dist
Dynamic: summary

swaj
====

"If you watch the movie Jaws backwards, it's a movie about a shark that keeps
throwing up people until they have to open a beach."

`swaj` is a tool to simplify using multiple sets of credentials with AWS. If
you have multiple profiles, `swaj` eliminates the need to constantly re-export
values when using MFA or SSO. `swaj` is especially helpful when using MFA in
that it persists the temporary session credentials, minimizing the number of
times an OTP code must be entered.

Requires python.

If you'd like to use the built-in TOTP functionality (instead of an app, like
Google Authenticator or Authy), you'll also need to install pyotp, like so:
`pip install pyotp`.

Install
=======

```!sh
$ curl https://raw.githubusercontent.com/f0rk/swaj/master/tools/swaj-standalone > ~/bin/swaj
$ chmod +x ~/bin/swaj
```

Configuration
=============

If you wish to use swaj to more safely use profiles, no additional
configuration is needed.

If you wish to use an MFA device (currently, the AWS API only supports
software-based devices), place the serial of that device in your
`~/.aws/config` like so:

```
[profile dev]
region = us-west-1
mfa_serial = arn:aws:iam::000000000000:mfa/jimmy
```

Additionally, if you wish to assume a role, you can configure it like so:
```
[profile admin]
region = us-west-1
mfa_serial = arn:aws:iam::000000000000:mfa/jimmy
swaj_role_arn = arn:aws:iam::000000000000:role/admin
```

This usage is non-standard but is a workaround for a bug in botocore.

Using SSO is straightforward, just configure your SSO normally and `swaj` will
ensure you are authenticated.

Usage
=====

`swaj` works with profiles as defined in your `~/.aws/config`. It does not
support other modes of operation. You must either set `AWS_PROFILE` in your
environment or pass `--profile yourprofile` to it.

`swaj` will get everything squared away with MFA and then run your command with
the determiend credentials:

```
$ swaj --profile dev exec aws s3api list-buckets               
enter token for mfa_serial arn:aws:iam::000000000000:mfa/jimmy: 123456  
{                                                     
    "Buckets": [
        {
            "Name": "bananaphone",            
            "CreationDate": "2020-05-08T01:01:01.000Z"
        },
    ],
    "Owner": {
        "DisplayName": "jimmysworld",
        "ID": "0000000000000000000000000000000000000000000000000000000000000000"
    }
}
```

Subsequent runs will not prompt you for MFA credentials:
```
$ swaj --profile dev exec aws s3api list-buckets               
{                                                     
    "Buckets": [
        {
            "Name": "bananaphone",            
            "CreationDate": "2020-05-08T01:01:01.000Z"
        },
    ],
    "Owner": {
        "DisplayName": "jimmysworld",
        "ID": "0000000000000000000000000000000000000000000000000000000000000000"
    }
}
```

Perhaps, though, you just want to set the credentials in your environment. To
get the credentials you could run:

```
$ swaj --profile dev env
...
AWS_SECRET_ACCESS_KEY=...
AWS_SESSION_TOKEN=...
AWS_ACCESS_KEY_ID=...
AWS_SESSION_EXPIRATION=...
...
```

For convenience, you can use the `eval` subcommand to simplify:

```
$ eval $(swaj --profile dev eval)
$ env | grep AWS
... 
AWS_SECRET_ACCESS_KEY=...
AWS_SESSION_TOKEN=...
AWS_ACCESS_KEY_ID=...
AWS_SESSION_EXPIRATION=...
...
```
