top
(README.md)
# aws-cli-wrapper
Wraps around the AWS CLI to first retrieve AWS access key and secret key credentials from a web service, set them as the environment variables: "AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY" and "AWS_SESSION_TOKEN" before calling the AWS CLI command.
Your web service can make use of the AWS STS:AssumeRole API or SAML federation to dynamically request temporary AWS credentials that can be returned to the wrapper to use for the CLI execution.

## Prerequisites
* The AWS CLI is installed on the host and is in the path
* A web service implemented in line with the specification described below

## Usage
### Wrapper Configuration File
The wrapper takes a configuration file with the following format:
```
{
  "AuthService": {
    "UserId": "userid-to-authenticate-to-auth-web-service",
    "Password": "password-to-authenticate-to-auth-web-service",
    "EndPoint": "https://auth-web-service-endpoint/creds-url",
    "TrustCACert": "/path/to/CA.pem"
  },
  "RoleId": "auth-web-service-role-reference"
}
```
* UserId - (Optional) Username passed in basic authentication header to the authenticating web service. If not defined the current logged in user is used.
* Password - (Optional) Password passed in basic authentication header to the authenticating web service. If not defined the password is prompted for.
* EndPoint - The URL stub of the service that is called to request AWS access key and secret key credentials. Recommended to be over HTTPS so UserId and Password are not sent unencrypted.
* TrustCACert - (Optional) Certificate to trust for a HTTPS connection to the EndPoint. Path to file in PEM format.
* RoleId - (Optional) Appended to the EndPoint URL to request AWS access key and secret key credentials for a praticular role reference. Request is made to EndPoint/RoleId

### Running
```
./aws-cli-wrapper <wrapper arguments> <aws cli arguments>
```
Without any wrapper arguments the wrapper configuration is looked for at ~/wrapper-config.json
Another wrapper configuration file location can be specified with the -wrapper-config=<path to config> option.
Command line arguments can also be used to override values in the wrapper configuration file.

```
Usage of ./aws-cli-wrapper:
  -wrapper-authendpoint string
        Specify the EndPoint to authenticate to. Overrides the value in the wrapper-config file
  -wrapper-config string
        Specify the path to the configuration file that specifies the UserId, Password and EndPoint. (default "~/wrapper-config.json")
  -wrapper-password string
        Specify the password to authenticate with. It's not recommedend to use this argument as command line history may store the password
  -wrapper-roleId string
        Specify the roleId to request access to. This is a roleId that the authentication service recognises, not an AWS arn
  -wrapper-trustcacert string
        Specify the path to a CA cert to trust for the authentication service. Must be PEM format.
  -wrapper-userId string
        Specify the UserId authenticate with. Overrides the value in the wrapper-config file
```

#### Example
```
./aws-cli-wrapper -wrapper-config=/path/to/wrapper-config.json ec2 describe-instances
```

## Authentication Web Service Specification
* Return AWS access key and secret key credentials in the following format:
```
{
	"SecretAccessKey": "<Access key string>",
	"SessionToken": "<Session token string>",
	"Expiration": "<Expiration date time>",
	"AccessKeyId": "<Access KeyId>"
}
```
This format is the same as that returned from teh AWS STS API.
The Expiration value is optional and not really required by the wrapper at this time.

* Implement basic authentication to access the web service (other options may be supported in the future)

* To request credentials for different roles this should be referenced by a different URL path ending rather than a query parameter. That is:
  * https://my-auth-service/credentials/role1234 (supported)
  * https://my-auth-service/credentials?roleId=role1234 (not supported)

Imports 3 package(s) ΒΆ

  1. github.com/jcmturner/aws-cli-wrapper/config
  2. golang.org/x/crypto/ssh/terminal
  3. github.com/jcmturner/aws-cli-wrapper/authenticate