## OverviewThis script provides a seamless mechanism for federating the AWS CLI. Whenproperly configured this script allows a user to get a short lived (1 hour) set ofcredentials for each authorized role.

The script leverages Kerberos and ADFS to avoid any need for the user to entera AD domain password or provide AWS credentials. However, users can alsoauthenticate using NTLM with their username and password or with a Kerberos keytab.

## ConfigurationKerb-STS looks for configuration in the ~/.kerb-sts/config.json file. This file containsthe URL of the ADFS AWS login page and the default region. Users can generate this file with Kerb-STS:```kerb-sts --configure```This will prompt the user for those values and then serialize the configuration. Userscan also manually create the configuration file which should look like the following:```{ "region": "us-east-1", "adfs_url": "https://sample.domain.com/adfs/ls/IdpInitiatedSignOn.aspx?loginToRp=urn:amazon:webservices"}```Users can override either of the configured values on the command line.

## Installation* *Note: Python 2.7.10 is the minimal version supported** *Note: All platforms have been tested with both Python 2.7 and 3.5*

### OSX* *Note: If you are using El Capitan or Sierra, refer to the subsequent OSX section*

0. sudo easy_install pip1. sudo pip install kerb-sts

### OSX - El Capitan* *Note: El Capitan forces the version of some modules which directly interfere with kerb-sts. In order toget it to work users need to either use a version of Python that was not included with the OS or needto follow these instructions which leverage virtual environments.*

### MacOS Sierra0. You will need to update your version of Python to 2.7.12+; Homebrew is the easiest method.1. You will also need to install/update the XCODE Development Extensions 1a. sudo xcode-select install2. You can then just run sudo pip install kerb-sts

### Windows0. Install [Python] (https://www.python.org/downloads/)1. Ensure python and python/scripts are on the PATH2. Install pywin32 from [SourceForge] (https://sourceforge.net/projects/pywin32/files/pywin32/Build%20220/). Follow the instructions to ensure you get the correct version.3. pip install kerb-sts

## UsageIf the install went smoothly `kerb-sts` should be on your path. There are a lot of configuration options.The best way to discover them is to check out the help statement.```kerb-sts --help```

#### Default RoleThe script allows users to specify an AWS IAM role that will be set as the default IAM role inthe credentials file.```kerb-sts -r [iam-role-to-assume]```All subsequent AWS CLI commands will use this role by default.

Additionally, all available roles will be added as named profiles to the credentials file.Users can then leverage the default role or use the AWS_DEFAULT_PROFILE environment variable toselect a specific role/profile. You can find more information about the credentials filein the [AWS Documentation](http://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html#cli-config-files).

#### DaemonBy passing in a `--daemon` flag, the script will continue running and update the credentials file everyhalf hour. The refresh time can be set with the `--refresh` argument, but rememberthe tokens only last for one hour.```kerb-sts -r iam-role-to-assume --daemon```

#### KeytabThis script allows users to generate Kerberos tokens with Kerberos keytabs. Keytabsare private key files that are signed with the user's name, domain, and password.You can generate a keytab by running:```ktutil -k username.keytab add -p username@DOMAIN.COM -e arcfour-hmac-md5 -V 1```Users can use the keytab to authenticate with Kerberos by running:```kinit -kt username.keytab username@DOMAIN.COM```Keytabs allow users to authenticate without their password. The keytab is signed with the password however, sowhen a password is updated the keytab must likewise be updated.They can then be used with kerb-sts to generate temporary tokens:```kerb-sts --key username.keytab -u username -d DOMAIN.COM```

#### Credential FileThe default location for the AWS credentials file is ~/.aws/credentials. Users are also able to specifya different location for the credentials generated.```kerb-sts -c ./aws-credentials```

## Troubleshooting#### KerberosIf you are having issues authenticating with Kerberos, make sure you can run `kinit`. This should prompt you foryour password and then login successfully. You can view your current Kerberos tickets with `klist`. If you want toensure Kerberos is working properly you can delete all of your tickets with `kdestroy -A` and then try to get anotherticket issued by running `kinit`.

## Building a DistributionThe easiest way to install and distribute kerb-sts is using a wheel.A distribution can be built by running:```python setup.py bdist_wheel```That should output a .whl file in the dist directory which can be installed with pip.

## DevelopmentThe recommended way to install locally from source is to use a virtual environment. From the rootof the kerb-sts source code directory run: