open-vault/website/source/docs/auth/aws.html.md

---
layout: "docs"
page_title: "Auth Backend: AWS EC2"
sidebar_current: "docs-auth-aws"
description: |-
  The AWS EC2 backend allows automated authentication of AWS EC2 instances.
---

# Auth Backend: AWS EC2

The AWS EC2 auth backend provides a secure introduction mechanism for AWS EC2
instances, allowing automated retrieval of a Vault token. Unlike most Vault
authentication backends, this backend does not require first deploying or
provisioning security-sensitive credentials (tokens, username/password, client
certificates, etc). Instead, it treats AWS as a Trusted Third Party and uses
the cryptographically signed dynamic metadata information that uniquely
represents each EC2 instance.

## Authentication Workflow

EC2 instances have access to metadata describing the instance. (For those not
familiar with instance metadata, details can be found
[here](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html).)

One piece of "dynamic metadata" available to the EC2 instance is the instance
identity document, a JSON representation of a collection of instance metadata.
Importantly, AWS also provides a copy of this metadata in PKCS#7 format signed
with its public key, and publishes the public keys used (which are grouped by
region). (Details on the instance identity document and the signature can be
found
[here](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-identity-documents.html).)

During login, the backend verifies the signature on the PKCS#7 document,
ensuring that the information contained within is certified accurate by AWS.
Before succeeding the login attempt and returning a Vault token, the backend
verifies the current running status of the instance via the EC2 API.

There are various modifications to this workflow that provide more or less
security, as detailed later in this documentation.

## Authorization Workflow

The basic mechanism of operation is per-AMI. AMI IDs are registered in the
backend and associated with various optional restrictions, such as the set of
allowed policies and max TTLs on the generated tokens.

In many cases, an organization will use a "seed AMI" that is specialized after
bootup by configuration management or similar processes. For this reason, an
AMI entry in the backend can also be associated with a "role tag". These tags
are generated by the backend and are placed as the value of a tag with the
given key on the EC2 instance. The role tag can be used to further restrict the
parameters set on the image, but cannot be used to grant additional privileges.
If the "role tag" is enabled on the AMI and the EC2 instance performing login
does not have an expected tag on it, or if the tag on the instance is deleted,
authentication fails.

The role tags can be generated at will by an operator with appropriate API
access. They are HMAC-signed by a per-AMI key stored within the backend, allowing
the backend to verify the authenticity of a found role tag and ensure that it has
not been tampered with. There is also a mechanism to blacklist role tags if one
has been found to be distributed outside of its intended set of machines.

## Client Nonce

If an unintended party gains access to the PKCS#7 signature of the identity
document (which by default is available to every process and user that gains
access to an EC2 instance), it can impersonate that instance and fetch a Vault
token. The backend addresses this problem by using a Trust On First Use (TOFU)
mechanism that allows the first client to present the PKCS#7 signature of the
document to be authenticated and denying the rest. An important property of
this design is detection of unauthorized access: if an unintended party authenticates,
the intended client will be unable to authenticate and can raise an alert for
investigation.

During the first login, the backend stores the instance ID that authenticated
in a `whitelist`. One method of operation of the backend is to disallow any
authentication attempt for an instance ID contained in the whitelist. However,
this has consequences for token rotation, as it means that once a token has
expired, subsequent authentication attempts would fail.

The backend addresses this problem by sharing the responsibility with clients.
In the default method of operation, the client supplies a unique nonce during
the first authentication attempt, storing this nonce in the client's memory for
future use. This nonce is stored in the whitelist, tied to the instance ID.
Subsequent authentication attempts by the client require the nonce to match;
since only the original client knows the nonce, only the original client is
allowed to reauthenticate. (This is the reason that this is a whitelist rather
than a blacklist; by default, it's keeping track of clients allowed to
reauthenticate, rather than those that are not.) 

It is up to the client to behave correctly with respect to the nonce; if the
client stores the nonce on disk it can survive reboots, but could also give
access to other users or applications on the instance. It is also up to the
operator to ensure that client nonces are in fact unique; sharing nonces allows
a compromise of the nonce value to enable an attacker that gains access to any
EC2 instance to imitate the legitimate client on that instance. This is why
nonces can be disabled on the backend side in favor of only a single
authentication per instance; in some cases, such as when using ASGs, instances
are immutable and single-boot anyways, and in conjunction with a high max TTL,
reauthentication may not be needed (and if it is, the instance can simply be
shut down and allow ASG to start a new one). By default, reauthentication
is enabled in this backend, and can be turned off using 'disallow_reauthentication'
parameter on the registered AMI.

In both cases, entries can be removed from the whitelist by instance ID,
allowing reauthentication by a client if the nonce is lost (or not used) and an
operator approves the process.

One other point: if available by the OS/distribution being used with the EC2
instance, it is not a bad idea to firewall access to the signed PKCS#7 metadata
to ensure that it is accessible only to the matching user(s) that require
access.

## Advanced Options and Caveats

### Dynamic Management of Policies Via Role Tags

If the instance is required to have customized set of policies based on the
role it plays, the `role_tag` option can be used to provide a tag to set on
instances with the given AMI. When this option is set, during login, along with
verification of PKCS#7 signature and instance health, the backend will query
for the value of a specific tag with the configured key that is attached to the
instance. The tag holds information that represents a *subset* of privileges that
are set on the AMI and are used to further restrict the set of the AMI's
privileges for that particular instance.

A `role_tag` can be created using `auth/aws/image/<ami_id>/roletag` endpoint
and is immutable. The information present in the tag is SHA256 hashed and HMAC
protected. The per-AMI key to HMAC is only maintained in the backend. This prevents
an adversarial operator from modifying the tag when setting it on the EC2 instance
in order to escalate privileges.

When 'role_tag' option is set on an AMI, the instances are required to have a
role tag. If the tag is not found on the EC2 instance, authentication will fail.
This is to ensure that privileges of an instance are never escalated for not
having the tag on it or for removing the tag. If the role tag has no policy component,
the client will inherit the allowed policies set on the AMI. If the role tag has a
policy component but it contains no policies, the token will contain only the
`default` policy; by default, this policy allows only manipulation (revocation,
renewal, lookup) of the existing token, plus access to its
[cubbyhole](https://www.vaultproject.io/docs/secrets/cubbyhole/index.html).
This can be useful to allow instances access to a secure "scratch space" for
storing data (via the token's cubbyhole) but without granting any access to
other resources provided by or resident in Vault.

### Handling Lost Client Nonces

If an EC2 instance loses its client nonce (due to a reboot, a stop/start of the
client, etc.), subsequent login attempts will not succeed. If the client nonce
is lost, normally the only option is to delete the entry corresponding to the
instance ID from the identity `whitelist` in the backend. This can be done via
the `auth/aws/whitelist/identity/<instance_id>` endpoint. This allows a new
client nonce to be accepted by the backend during the next login request.

Under certain circumstances there is another useful setting. When the instance
is placed onto a host upon creation, it is given a `pendingTime` value in the
instance identity document (documentation from AWS does not cover this option,
unfortunately). If an instance is stopped and started, the `pendingTime` value
is updated (this does not apply to reboots, however).

The backend can take advantage of this via the `allow_instance_migration`
option, which is set per-AMI. When this option is enabled, if the client nonce
does not match the saved nonce, the `pendingTime` value in the instance
identity document will be checked; if it is newer than the stored `pendingTime`
value, the backend assumes that the client was stopped/started and allows the
client to log in successfully, storing the new nonce as the valid nonce for
that client. This essentially re-starts the TOFU mechanism any time the
instance is stopped and started, so should be used with caution. Just like with
initial authentication, the legitimate client should have a way to alert (or an
alert should trigger based on its logs) if it is denied authentication.

Unfortunately, the `allow_instance_migration` only helps during stop/start
actions; the current metadata does not provide for a way to allow this
automatic behavior during reboots. The backend will be updated if this needed
metadata becomes available.

The `allow_instance_migration` option is set per-AMI, and can also be
specified in a role tag. Since role tags can only restrict behavior, if the
option is set to `false` on the AMI, a value of `true` in the role tag takes
effect; however, if the option is set to `true` on the AMI, a value set in the
role tag has no effect.

### Disabling Reauthentication

If in a given organization's architecture a client fetches a long-lived Vault
token and has no need to rotate the token, all future logins for that instance
ID can be disabled. If the option `disallow_reauthentication` is set, only one
login will be allowed per instance.  If the intended client successfully
retrieves a token during login, it can be sure that its token will not be
hijacked by another entity.

When `disallow_reauthentication` option is enabled, the client can choose not
to supply a nonce during login, although it is not an error to do so (the nonce
is simply ignored). Note that reauthentication is enabled by default. If only
a single login is desired, `disable_reauthentication` should be set explicitly
on the registered AMI or on the role tag.

The `disallow_reauthentication` option is set per-AMI, and can also be
specified in a role tag. Since role tags can only restrict behavior, if the
option is set to `false` on the AMI, a value of `true` in the role tag takes
effect; however, if the option is set to `true` on the AMI, a value set in the
role tag has no effect.

### Blacklisting Role Tags

Role tags are tied to a specific AMI, but the backend has no control over which
instances using that AMI should have any particular role tag; that is purely up
to the operator. Although role tags are only restrictive, if a role tag is
found to have been used incorrectly, and the administrator wants to ensure that
the role tag has no further effect, the role tag can be placed on a `blacklist`
via the endpoint `auth/aws/blacklist/roletag/<role_tag>`. Note that this will
not invalidate the tokens that were already issued; this only blocks any
further login requests.

### Expiration Times and Tidying of `blacklist` and `whitelist` Entries

The expired entries in both identity `whitelist` and role tag `blacklist` are
deleted automatically.  The entries in both of these lists contain an expiration
time which is dynamically determined by three factors: `max_ttl` set on the AMI,
`max_ttl` set on the role tag, and `max_ttl` value of the backend mount. The
least of these three dictates the maximum TTL of the issued token, and
correspondingly will be set as the expiration times of these entries.

The endpoints `aws/auth/tidy/identities` and
`aws/auth/tidy/roletags` are provided to clean up the entries present
in these lists. These endpoints allow defining a safety buffer, such that an
entry must not only be expired, but be past expiration by the amount of time
dictated by the safety buffer in order to actually remove the entry.

Automatic deletion of expired entired is performed by the periodic function
of the backend. This function does the tidying of both blacklist role tags
and whitelist identities. Periodic tidying is activated by default and will
have a safety buffer of 72 hours, meaning only those entries are deleted which
were expired before 72 hours from when the tidy operation is being performed.
This can be configured via `config/tidy/roletags` and `config/tidy/identities`
endpoints.

### Varying Public Certificates

The AWS public certificate which contains the public key used to verify the
PKCS#7 signature varies for groups of regions. The default public certificate
provided with the backend is applicable for many regions. Users of instances whose
signatures cannot be verified by the default public certificate, can register a
different public certificate which can be found [here]
(http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-identity-documents.html),
via the `auth/aws/config/certificate/<cert_name>` endpoint.

### Dangling Tokens

An instance, after authenticating itself with the backend gets a Vault token.
After that, if the instance terminates or goes down for any reason, the backend
will not be aware of such events. The token issued will still be valid, until
it expires. The token will likely be expired sooner than its lifetime when the
instance fails to renew the token on time.

## Authentication

### Via the CLI

#### Enable AWS EC2 authentication in Vault.

```
$ vault auth-enable aws
```

#### Configure the credentials required to make AWS API calls

Note: the client uses the official AWS SDK and will use environment variable or
IAM role-provided credentials if available. In addition, the `AWS_REGION`
environment variable will be honored if available.

```
$ vault write auth/aws/config/client secret_key=vCtSM8ZUEQ3mOFVlYPBQkf2sO6F/W7a5TVzrl3Oj access_key=VKIAJBRHKH6EVTTNXDHA
```

#### Configure the policies on the AMI.

```
$ vault write auth/aws/image/ami-fce3c696 policies=prod,dev max_ttl=500h
```

#### Perform the login operation

```
$ vault write auth/aws/login pkcs7=MIAGCSqGSIb3DQEHAqCAMIACAQExCzAJBgUrDgMCGgUAMIAGCSqGSIb3DQEHAaCAJIAEggGmewogICJkZXZwYXlQcm9kdWN0Q29kZXMiIDogbnVsbCwKICAicHJpdmF0ZUlwIiA6ICIxNzIuMzEuNjMuNjAiLAogICJhdmFpbGFiaWxpdHlab25lIiA6ICJ1cy1lYXN0LTFjIiwKICAidmVyc2lvbiIgOiAiMjAxMC0wOC0zMSIsCiAgImluc3RhbmNlSWQiIDogImktZGUwZjEzNDQiLAogICJiaWxsaW5nUHJvZHVjdHMiIDogbnVsbCwKICAiaW5zdGFuY2VUeXBlIiA6ICJ0Mi5taWNybyIsCiAgImFjY291bnRJZCIgOiAiMjQxNjU2NjE1ODU5IiwKICAiaW1hZ2VJZCIgOiAiYW1pLWZjZTNjNjk2IiwKICAicGVuZGluZ1RpbWUiIDogIjIwMTYtMDQtMDVUMTY6MjY6NTVaIiwKICAiYXJjaGl0ZWN0dXJlIiA6ICJ4ODZfNjQiLAogICJrZXJuZWxJZCIgOiBudWxsLAogICJyYW1kaXNrSWQiIDogbnVsbCwKICAicmVnaW9uIiA6ICJ1cy1lYXN0LTEiCn0AAAAAAAAxggEXMIIBEwIBATBpMFwxCzAJBgNVBAYTAlVTMRkwFwYDVQQIExBXYXNoaW5ndG9uIFN0YXRlMRAwDgYDVQQHEwdTZWF0dGxlMSAwHgYDVQQKExdBbWF6b24gV2ViIFNlcnZpY2VzIExMQwIJAJa6SNnlXhpnMAkGBSsOAwIaBQCgXTAYBgkqhkiG9w0BCQMxCwYJKoZIhvcNAQcBMBwGCSqGSIb3DQEJBTEPFw0xNjA0MDUxNjI3MDBaMCMGCSqGSIb3DQEJBDEWBBRtiynzMTNfTw1TV/d8NvfgVw+XfTAJBgcqhkjOOAQDBC4wLAIUVfpVcNYoOKzN1c+h1Vsm/c5U0tQCFAK/K72idWrONIqMOVJ8Uen0wYg4AAAAAAAA nonce=vault-client-nonce
```


### Via the API

#### Enable AWS EC2 authentication in Vault.

```
curl -X POST -H "x-vault-token:123" "http://127.0.0.1:8200/v1/sys/auth/aws" -d '{"type":"aws"}'
```

#### Configure the credentials required to make AWS API calls.

```
curl -X POST -H "x-vault-token:123" "http://127.0.0.1:8200/v1/auth/aws/config/client" -d '{"access_key":"VKIAJBRHKH6EVTTNXDHA", "secret_key":"vCtSM8ZUEQ3mOFVlYPBQkf2sO6F/W7a5TVzrl3Oj"}'
```

#### Configure the policies on the AMI.

```
curl -X POST -H "x-vault-token:123" "http://127.0.0.1:8200/v1/auth/aws/image/ami-fce3c696" -d '{"policies":"prod,dev","max_ttl":"500h"}'
```

#### Perform the login operation

```
curl -X POST "http://127.0.0.1:8200/v1/auth/aws/login" -d '{"pkcs7":"MIAGCSqGSIb3DQEHAqCAMIACAQExCzAJBgUrDgMCGgUAMIAGCSqGSIb3DQEHAaCAJIAEggGmewogICJkZXZwYXlQcm9kdWN0Q29kZXMiIDogbnVsbCwKICAicHJpdmF0ZUlwIiA6ICIxNzIuMzEuNjMuNjAiLAogICJhdmFpbGFiaWxpdHlab25lIiA6ICJ1cy1lYXN0LTFjIiwKICAidmVyc2lvbiIgOiAiMjAxMC0wOC0zMSIsCiAgImluc3RhbmNlSWQiIDogImktZGUwZjEzNDQiLAogICJiaWxsaW5nUHJvZHVjdHMiIDogbnVsbCwKICAiaW5zdGFuY2VUeXBlIiA6ICJ0Mi5taWNybyIsCiAgImFjY291bnRJZCIgOiAiMjQxNjU2NjE1ODU5IiwKICAiaW1hZ2VJZCIgOiAiYW1pLWZjZTNjNjk2IiwKICAicGVuZGluZ1RpbWUiIDogIjIwMTYtMDQtMDVUMTY6MjY6NTVaIiwKICAiYXJjaGl0ZWN0dXJlIiA6ICJ4ODZfNjQiLAogICJrZXJuZWxJZCIgOiBudWxsLAogICJyYW1kaXNrSWQiIDogbnVsbCwKICAicmVnaW9uIiA6ICJ1cy1lYXN0LTEiCn0AAAAAAAAxggEXMIIBEwIBATBpMFwxCzAJBgNVBAYTAlVTMRkwFwYDVQQIExBXYXNoaW5ndG9uIFN0YXRlMRAwDgYDVQQHEwdTZWF0dGxlMSAwHgYDVQQKExdBbWF6b24gV2ViIFNlcnZpY2VzIExMQwIJAJa6SNnlXhpnMAkGBSsOAwIaBQCgXTAYBgkqhkiG9w0BCQMxCwYJKoZIhvcNAQcBMBwGCSqGSIb3DQEJBTEPFw0xNjA0MDUxNjI3MDBaMCMGCSqGSIb3DQEJBDEWBBRtiynzMTNfTw1TV/d8NvfgVw+XfTAJBgcqhkjOOAQDBC4wLAIUVfpVcNYoOKzN1c+h1Vsm/c5U0tQCFAK/K72idWrONIqMOVJ8Uen0wYg4AAAAAAAA","nonce":"vault-client-nonce"}'
```


The response will be in JSON. For example:

```javascript
{
  "auth": {
    "renewable": true,
    "lease_duration": 1800000,
    "metadata": {
      "role_tag_max_ttl": "0",
      "instance_id": "i-de0f1344"
    },
    "policies": [
      "default",
      "dev",
      "prod"
    ],
    "accessor": "20b89871-e6f2-1160-fb29-31c2f6d4645e",
    "client_token": "c9368254-3f21-aded-8a6f-7c818e81b17a"
  },
  "warnings": null,
  "data": null,
  "lease_duration": 0,
  "renewable": false,
  "lease_id": ""
}
```

## API
### /auth/aws/config/client
#### POST
<dl class="api">
  <dt>Description</dt>
  <dd>
    Configures the credentials required to perform API calls to AWS.
    The instance identity document fetched from the PKCS#7 signature
    will provide the EC2 instance ID. The credentials configured using
    this endpoint will be used to query the status of the instances via
    DescribeInstanceStatus API. Also, if the login is performed using
    the role tag, then these credentials will also be used to fetch the
    tags that are set on the EC2 instance via DescribeTags API. If the
    static credentials are not provided using this endpoint, then the
    credentials will be retrieved from the environment variables
    `AWS_ACCESS_KEY`, `AWS_SECRET_KEY` and `AWS_REGION` respectively.
    If the credentials are still not found and if the backend is configured
    on an EC2 instance with metadata querying capabilities, the credentials
    are fetched automatically.
  </dd>

  <dt>Method</dt>
  <dd>POST</dd>

  <dt>URL</dt>
  <dd>`/auth/aws/config/client`</dd>

  <dt>Parameters</dt>
  <dd>
    <ul>
      <li>
        <span class="param">access_key</span>
        <span class="param-flags">required</span>
        AWS Access key with permissions to query EC2 instance metadata.
      </li>
    </ul>
    <ul>
      <li>
        <span class="param">secret_key</span>
        <span class="param-flags">required</span>
        AWS Secret key with permissions to query EC2 instance metadata.
      </li>
    </ul>
    <ul>
      <li>
        <span class="param">endpoint</span>
        <span class="param-flags">optional</span>
        URL to override the default generated endpoint for making AWS EC2 API calls.
      </li>
    </ul>
  </dd>

  <dt>Returns</dt>
  <dd>`204` response code.
  </dd>
</dl>

#### GET
<dl class="api">
  <dt>Description</dt>
    Returns the previously configured AWS access credentials.
  <dd>
    
  </dd>

  <dt>Method</dt>
  <dd>GET</dd>

  <dt>URL</dt>
  <dd>`/auth/aws/config/client`</dd>

  <dt>Parameters</dt>
  <dd>
    None.
  </dd>

  <dt>Returns</dt>
  <dd>

```
{
  "auth": null,
  "warnings": null,
  "data": {
    "secret_key": "vCtSM8ZUEQ3mOFVlYPBQkf2sO6F/W7a5TVzrl3Oj",
    "access_key": "VKIAJBRHKH6EVTTNXDHA"
    "endpoint" "",
  },
  "lease_duration": 0,
  "renewable": false,
  "lease_id": ""
}
```

  </dd>
</dl>


#### DELETE
<dl class="api">
  <dt>Description</dt>
  <dd>
    Deletes the previously configured AWS access credentials.
  </dd>

  <dt>Method</dt>
  <dd>DELETE</dd>

  <dt>URL</dt>
  <dd>`/auth/aws/config/client`</dd>

  <dt>Parameters</dt>
  <dd>
    None.
  </dd>

  <dt>Returns</dt>
  <dd>`204` response code.
  </dd>
</dl>


### /auth/aws/config/certificate/<cert_name>
#### POST
<dl class="api">
  <dt>Description</dt>
  <dd>
    Registers an AWS public key that is used to verify the PKCS#7 signature of the
    EC2 instance metadata.
  </dd>

  <dt>Method</dt>
  <dd>POST</dd>

  <dt>URL</dt>
  <dd>`/auth/aws/config/certificate/<cert_name>`</dd>

  <dt>Parameters</dt>
  <dd>
    <ul>
      <li>
        <span class="param">cert_name</span>
        <span class="param-flags">required</span>
        Name of the certificate.
      </li>
    </ul>
    <ul>
      <li>
        <span class="param">aws_public_cert</span>
        <span class="param-flags">required</span>
        AWS Public key required to verify PKCS7 signature of the EC2 instance metadata.
      </li>
    </ul>
  </dd>

  <dt>Returns</dt>
  <dd>`204` response code.
  </dd>
</dl>


#### GET
<dl class="api">
  <dt>Description</dt>
  <dd>
    Returns the previously configured AWS public key.
  </dd>

  <dt>Method</dt>
  <dd>GET</dd>

  <dt>URL</dt>
  <dd>`/auth/aws/config/certificate/<cert_name>`</dd>

  <dt>Parameters</dt>
  <dd>
    None.
  </dd>

  <dt>Returns</dt>
  <dd>

```javascript
{
  "auth": null,
  "warnings": null,
  "data": {
    "aws_public_cert": "-----BEGIN CERTIFICATE-----\nMIIC7TCCAq0CCQCWukjZ5V4aZzAJBgcqhkjOOAQDMFwxCzAJBgNVBAYTAlVTMRkw\nFwYDVQQIExBXYXNoaW5ndG9uIFN0YXRlMRAwDgYDVQQHEwdTZWF0dGxlMSAwHgYD\nVQQKExdBbWF6b24gV2ViIFNlcnZpY2VzIExMQzAeFw0xMjAxMDUxMjU2MTJaFw0z\nODAxMDUxMjU2MTJaMFwxCzAJBgNVBAYTAlVTMRkwFwYDVQQIExBXYXNoaW5ndG9u\nIFN0YXRlMRAwDgYDVQQHEwdTZWF0dGxlMSAwHgYDVQQKExdBbWF6b24gV2ViIFNl\ncnZpY2VzIExMQzCCAbcwggEsBgcqhkjOOAQBMIIBHwKBgQCjkvcS2bb1VQ4yt/5e\nih5OO6kK/n1Lzllr7D8ZwtQP8fOEpp5E2ng+D6Ud1Z1gYipr58Kj3nssSNpI6bX3\nVyIQzK7wLclnd/YozqNNmgIyZecN7EglK9ITHJLP+x8FtUpt3QbyYXJdmVMegN6P\nhviYt5JH/nYl4hh3Pa1HJdskgQIVALVJ3ER11+Ko4tP6nwvHwh6+ERYRAoGBAI1j\nk+tkqMVHuAFcvAGKocTgsjJem6/5qomzJuKDmbJNu9Qxw3rAotXau8Qe+MBcJl/U\nhhy1KHVpCGl9fueQ2s6IL0CaO/buycU1CiYQk40KNHCcHfNiZbdlx1E9rpUp7bnF\nlRa2v1ntMX3caRVDdbtPEWmdxSCYsYFDk4mZrOLBA4GEAAKBgEbmeve5f8LIE/Gf\nMNmP9CM5eovQOGx5ho8WqD+aTebs+k2tn92BBPqeZqpWRa5P/+jrdKml1qx4llHW\nMXrs3IgIb6+hUIB+S8dz8/mmO0bpr76RoZVCXYab2CZedFut7qc3WUH9+EUAH5mw\nvSeDCOUMYQR7R9LINYwouHIziqQYMAkGByqGSM44BAMDLwAwLAIUWXBlk40xTwSw\n7HX32MxXYruse9ACFBNGmdX2ZBrVNGrN9N2f6ROk0k9K\n-----END CERTIFICATE-----\n"
  },
  "lease_duration": 0,
  "renewable": false,
  "lease_id": ""
}
```

  </dd>
</dl>

#### LIST
<dl class="api">
  <dt>Description</dt>
  <dd>
    Lists all the AWS public certificates that are registered with the backend.
  </dd>

  <dt>Method</dt>
  <dd>GET</dd>

  <dt>URL</dt>
  <dd>`/auth/aws/config/certificates?list=true`</dd>

  <dt>Parameters</dt>
  <dd>
    None.
  </dd>

  <dt>Returns</dt>
  <dd>

```javascript
{
  "auth": null,
  "warnings": null,
  "data": {
    "keys": [
      "cert1"
    ]
  },
  "lease_duration": 0,
  "renewable": false,
  "lease_id": ""
}
```

  </dd>
</dl>

### /auth/aws/config/tidy/identities
##### POST
<dl class="api">
  <dt>Description</dt>
  <dd>
    Configures the periodic tidying operation of the whitelisted identity entries.
  </dd>

  <dt>Method</dt>
  <dd>POST</dd>

  <dt>URL</dt>
  <dd>`/auth/aws/config/tidy/identities`</dd>

  <dt>Parameters</dt>
  <dd>
    <ul>
      <li>
        <span class="param">safety_buffer</span>
        <span class="param-flags">optional</span>
        The amount of extra time that must have passed beyond the `roletag` expiration,
        before it is removed from the backend storage. Defaults to 72h.
      </li>
    </ul>
    <ul>
      <li>
        <span class="param">disable_periodic_tidy</span>
        <span class="param-flags">optional</span>
        If set to 'true', disables the periodic tidying of the 'whitelist/identity/<instance_id>'
        entries and 'whitelist/identity/<instance_id>' entries.
      </li>
    </ul>
  </dd>

  <dt>Returns</dt>
  <dd>`204` response code.
  </dd>
</dl>


#### GET
<dl class="api">
  <dt>Description</dt>
  <dd>
    Returns the previously configured periodic whitelist tidying settings.
  </dd>

  <dt>Method</dt>
  <dd>GET</dd>

  <dt>URL</dt>
  <dd>`/auth/aws/config/tidy/identities`</dd>

  <dt>Parameters</dt>
  <dd>
    None.
  </dd>

  <dt>Returns</dt>
  <dd>

```javascript
{
  "auth": null,
  "warnings": null,
  "data": {
    "safety_buffer": 60,
    "disable_periodic_tidy": false
  },
  "lease_duration": 0,
  "renewable": false,
  "lease_id": ""
}
```

  </dd>
</dl>

#### DELETE
<dl class="api">
  <dt>Description</dt>
  <dd>
    Deletes the previously configured periodic whitelist tidying settings.
  </dd>

  <dt>Method</dt>
  <dd>DELETE</dd>

  <dt>URL</dt>
  <dd>`/auth/aws/config/tidy/identities`</dd>

  <dt>Parameters</dt>
  <dd>
    None.
  </dd>

  <dt>Returns</dt>
  <dd>`204` response code.
  </dd>
</dl>



### /auth/aws/config/tidy/roletags
##### POST
<dl class="api">
  <dt>Description</dt>
  <dd>
    Configures the periodic tidying operation of the blacklisted role tag entries.
  </dd>

  <dt>Method</dt>
  <dd>POST</dd>

  <dt>URL</dt>
  <dd>`/auth/aws/config/tidy/roletags`</dd>

  <dt>Parameters</dt>
  <dd>

    <ul>
      <li>
        <span class="param">safety_buffer</span>
        <span class="param-flags">optional</span>
        The amount of extra time that must have passed beyond the `roletag` expiration, before it is removed from the backend storage. Defaults to 72h.
      </li>
    </ul>
    <ul>
      <li>
        <span class="param">disable_periodic_tidy</span>
        <span class="param-flags">optional</span>
        If set to 'true', disables the periodic tidying of the 'blacklist/roletag/<role_tag>' entries and 'whitelist/identity/<instance_id>' entries.
      </li>
    </ul>
  </dd>

  <dt>Returns</dt>
  <dd>`204` response code.
  </dd>
</dl>


#### GET
<dl class="api">
  <dt>Description</dt>
  <dd>
    Returns the previously configured periodic blacklist tidying settings.
  </dd>

  <dt>Method</dt>
  <dd>GET</dd>

  <dt>URL</dt>
  <dd>`/auth/aws/config/tidy/roletags`</dd>

  <dt>Parameters</dt>
  <dd>
    None.
  </dd>

  <dt>Returns</dt>
  <dd>

```javascript
{
  "auth": null,
  "warnings": null,
  "data": {
    "safety_buffer": 60,
    "disable_periodic_tidy": false
  },
  "lease_duration": 0,
  "renewable": false,
  "lease_id": ""
}
```

  </dd>
</dl>

#### DELETE
<dl class="api">
  <dt>Description</dt>
  <dd>
    Deletes the previously configured periodic blacklist tidying settings.
  </dd>

  <dt>Method</dt>
  <dd>DELETE</dd>

  <dt>URL</dt>
  <dd>`/auth/aws/config/tidy/roletags`</dd>

  <dt>Parameters</dt>
  <dd>
    None.
  </dd>

  <dt>Returns</dt>
  <dd>`204` response code.
  </dd>
</dl>



### /auth/aws/image/<ami_id>
#### POST
<dl class="api">
  <dt>Description</dt>
  <dd>
    Registers an AMI ID in the backend. Only those instances which are using the AMIs registered using this endpoint,
    will be able to perform login operation. If each EC2 instance is using unique AMI ID, then all those AMI IDs should
    be registered beforehand. In case the same AMI is shared among many EC2 instances, then that AMI should be registered
    using this endpoint with the option `role_tag` (refer API section), then a `roletag` should be created using
    `auth/aws/image/<ami_id>/roletag` endpoint, and this tag should be attached to the EC2 instance before the login operation
    is performed.
  </dd>

  <dt>Method</dt>
  <dd>POST</dd>

  <dt>URL</dt>
  <dd>`/auth/aws/image/<ami_id>`</dd>

  <dt>Parameters</dt>
  <dd>
    <ul>
      <li>
        <span class="param">ami_id</span>
        <span class="param-flags">required</span>
        AMI ID to be mapped.
      </li>
    </ul>
    <ul>
      <li>
        <span class="param">instance_id</span>
        <span class="param-flags">optional</span>
        Instance ID for which this tag is intended for. If set, the created tag can only be used by the instance with the given ID.
      </li>
    </ul>
    <ul>
      <li>
        <span class="param">role_tag</span>
        <span class="param-flags">optional</span>
        If set, enables the `roletag` login for this AMI, meaning that this AMI is shared among many EC2 instances. The value set for this field should be the `key` of the tag on the EC2 instance and the `tag_value` returned from `auth/aws/image/<ami_id>/roletag` should be the `value` of the tag on the instance. Defaults to empty string, meaning that this AMI is not shared among instances.
      </li>
    </ul>
    <ul>
      <li>
        <span class="param">max_ttl</span>
        <span class="param-flags">optional</span>
        The maximum allowed lease duration.
      </li>
    </ul>
    <ul>
      <li>
        <span class="param">policies</span>
        <span class="param-flags">optional</span>
        Policies to be associated with the AMI.
      </li>
    </ul>
    <ul>
      <li>
        <span class="param">allow_instance_migration</span>
        <span class="param-flags">optional</span>
        If set, allows migration of the underlying instance where the client resides. This keys off of pendingTime in the metadata document, so essentially, this disables the client nonce check whenever the instance is migrated to a new host and pendingTime is newer than the previously-remembered time. Use with caution.
      </li>
    </ul>
    <ul>
      <li>
        <span class="param">disallow_reauthentication</span>
        <span class="param-flags">optional</span>
        If set, only allows a single token to be granted per instance ID. In order to perform a fresh login, the entry in whitelist for the instance ID needs to be cleared using 'auth/aws/whitelist/identity/<instance_id>' endpoint. Defaults to 'false'.
      </li>
    </ul>
  </dd>

  <dt>Returns</dt>
  <dd>`204` response code.
  </dd>
</dl>


#### GET
<dl class="api">
  <dt>Description</dt>
  <dd>
    Returns the previously registered AMI ID configuration.
  </dd>

  <dt>Method</dt>
  <dd>GET</dd>

  <dt>URL</dt>
  <dd>`/auth/aws/image/<ami_id>`</dd>

  <dt>Parameters</dt>
  <dd>
    None.
  </dd>

  <dt>Returns</dt>
  <dd>

```javascript
{
  "auth": null,
  "warnings": null,
  "data": {
    "role_tag": "",
    "policies": [
      "default",
      "dev",
      "prod"
    ],
    "max_ttl": 1800000,
    "disallow_reauthentication": false,
    "allow_instance_migration": false
  },
  "lease_duration": 0,
  "renewable": false,
  "lease_id": ""
}
```

  </dd>
</dl>


#### LIST
<dl class="api">
  <dt>Description</dt>
  <dd>
    Lists all the AMI IDs that are registered with the backend.
  </dd>

  <dt>Method</dt>
  <dd>GET</dd>

  <dt>URL</dt>
  <dd>`/auth/aws/images?list=true`</dd>

  <dt>Parameters</dt>
  <dd>
    None.
  </dd>

  <dt>Returns</dt>
  <dd>

```javascript
{
  "auth": null,
  "warnings": null,
  "data": {
    "keys": [
      "ami-fce3c696",
      "ami-hei3d687"
    ]
  },
  "lease_duration": 0,
  "renewable": false,
  "lease_id": ""
}
```

  </dd>
</dl>


#### DELETE
<dl class="api">
  <dt>Description</dt>
  <dd>
    Deletes the previously registered AMI ID.
  </dd>

  <dt>Method</dt>
  <dd>DELETE</dd>

  <dt>URL</dt>
  <dd>`/auth/aws/image/<ami_id>`</dd>

  <dt>Parameters</dt>
  <dd>
    None.
  </dd>

  <dt>Returns</dt>
  <dd>`204` response code.
  </dd>
</dl>


### /auth/aws/image/<ami_id>/roletag
#### POST
<dl class="api">
  <dt>Description</dt>
  <dd>
    Creates a `roletag` for the AMI_ID. Role tags provide an effective way to restrict the
    options that are set on the AMI ID. This is of use when AMI is shared by multiple instances
    and there is need to customize the options for specific instances.
  </dd>

  <dt>Method</dt>
  <dd>POST</dd>

  <dt>URL</dt>
  <dd>`/auth/aws/image/<ami_id>/roletag`</dd>

  <dt>Parameters</dt>
  <dd>
    <ul>
      <li>
        <span class="param">ami_id</span>
        <span class="param-flags">required</span>
        AMI ID to create a tag for.
      </li>
    </ul>
    <ul>
      <li>
        <span class="param">policies</span>
        <span class="param-flags">optional</span>
        Policies to be associated with the tag.
      </li>
    </ul>
    <ul>
      <li>
        <span class="param">max_ttl</span>
        <span class="param-flags">optional</span>
        The maximum allowed lease duration.
      </li>
    </ul>
    <ul>
      <li>
        <span class="param">disallow_reauthentication</span>
        <span class="param-flags">optional</span>
        If set, only allows a single token to be granted per instance ID. This can be cleared with the auth/aws/whitelist/identity endpoint. Defaults to 'false'.
      </li>
    </ul>
    <ul>
      <li>
        <span class="param">allow_instance_migration</span>
        <span class="param-flags">optional</span>
        If set, allows migration of the underlying instance where the client resides. This keys off of pendingTime in the metadata document, so essentially, this disables the client nonce check whenever the instance is migrated to a new host and pendingTime is newer than the previously-remembered time. Use with caution. Defaults to 'false'.
      </li>
    </ul>
  </dd>

  <dt>Returns</dt>
  <dd>

```javascript
{
  "auth": null,
  "warnings": null,
  "data": {
    "tag_value": "v1:09Vp0qGuyB8=:a=ami-fce3c696:p=default,prod:d=false:t=300h0m0s:uPLKCQxqsefRhrp1qmVa1wsQVUXXJG8UZP/pJIdVyOI=",
    "tag_key": "VaultRole"
  },
  "lease_duration": 0,
  "renewable": false,
  "lease_id": ""
}
```

  </dd>
</dl>


### /auth/aws/login
#### POST
<dl class="api">
  <dt>Description</dt>
  <dd>
   Login and fetch a token. If the instance metadata signature is valid
   along with a few other conditions, a token will be issued. 
  </dd>

  <dt>Method</dt>
  <dd>POST</dd>

  <dt>URL</dt>
  <dd>`/auth/aws/login`</dd>

  <dt>Parameters</dt>
  <dd>
    <ul>
      <li>
        <span class="param">pkcs7</span>
        <span class="param-flags">required</span>
        PKCS7 signature of the identity document.
      </li>
    </ul>
    <ul>
      <li>
        <span class="param">nonce</span>
        <span class="param-flags">required/optional, depends</span>
        The `nonce` created by a client of this backend. When `disallow_reauthentication`
        option is enabled on either the AMI or the role tag, then `nonce` parameter is
        optional. It is a required parameter otherwise.
      </li>
    </ul>
  </dd>

  <dt>Returns</dt>
  <dd>

```javascript
{
  "auth": {
    "renewable": true,
    "lease_duration": 1800000,
    "metadata": {
      "role_tag_max_ttl": "0",
      "instance_id": "i-de0f1344"
    },
    "policies": [
      "default",
      "dev",
      "prod"
    ],
    "accessor": "20b89871-e6f2-1160-fb29-31c2f6d4645e",
    "client_token": "c9368254-3f21-aded-8a6f-7c818e81b17a"
  },
  "warnings": null,
  "data": null,
  "lease_duration": 0,
  "renewable": false,
  "lease_id": ""
}
```

  </dd>
</dl>


### /auth/aws/blacklist/roletag/<role_tag>
#### POST
<dl class="api">
  <dt>Description</dt>
  <dd>
    Places a valid roletag in a blacklist. This ensures that the `roletag`
    cannot be used by any instance to perform a login operation again.
    Note that if this `roletag` was previousy used to perfom a successful
    login, placing the `roletag` in the blacklist does not invalidate the
    already issued token.
  </dd>

  <dt>Method</dt>
  <dd>POST</dd>

  <dt>URL</dt>
  <dd>`/auth/aws/blacklist/roletag/<role_tag>`</dd>

  <dt>Parameters</dt>
  <dd>
    <ul>
      <li>
        <span class="param">role_tag</span>
        <span class="param-flags">required</span>
        Role tag that needs be blacklisted. The tag can be supplied as-is, or can be base64 encoded.
      </li>
    </ul>
  </dd>

  <dt>Returns</dt>
  <dd>`204` response code.
  </dd>
</dl>


#### GET
<dl class="api">
  <dt>Description</dt>
  <dd>
    Returns the blacklist entry of a previously blacklisted `roletag`.
  </dd>

  <dt>Method</dt>
  <dd>GET</dd>

  <dt>URL</dt>
  <dd>`/auth/aws/blacklist/roletag/<role_tag>`</dd>

  <dt>Parameters</dt>
  <dd>
    None.
  </dd>

  <dt>Returns</dt>
  <dd>

```javascript
{
  "auth": null,
  "warnings": null,
  "data": {
    "expiration_time": "2016-04-25T10:35:20.127058773-04:00",
    "creation_time": "2016-04-12T22:35:01.178348124-04:00"
  },
  "lease_duration": 0,
  "renewable": false,
  "lease_id": ""
}
```

  </dd>
</dl>


#### LIST
<dl class="api">
  <dt>Description</dt>
  <dd>
    Lists all the `roletags` that are blacklisted.
  </dd>

  <dt>Method</dt>
  <dd>GET</dd>

  <dt>URL</dt>
  <dd>`/auth/aws/blacklist/roletags?list=true`</dd>

  <dt>Parameters</dt>
  <dd>
    None.
  </dd>

  <dt>Returns</dt>
  <dd>

```javascript
{
  "auth": null,
  "warnings": null,
  "data": {
    "keys": [
      "v1:09Vp0qGuyB8=:a=ami-fce3c696:p=default,prod:d=false:t=300h0m0s:uPLKCQxqsefRhrp1qmVa1wsQVUXXJG8UZP/"
    ]
  },
  "lease_duration": 0,
  "renewable": false,
  "lease_id": ""
}
```

  </dd>
</dl>


#### DELETE
<dl class="api">
  <dt>Description</dt>
  <dd>
    Deletes a blacklisted `roletag`.
  </dd>

  <dt>Method</dt>
  <dd>DELETE</dd>

  <dt>URL</dt>
  <dd>`/auth/aws/blacklist/roletag/<role_tag>`</dd>

  <dt>Parameters</dt>
  <dd>
    None.
  </dd>

  <dt>Returns</dt>
  <dd>`204` response code.
  </dd>
</dl>


### /auth/aws/tidy/roletags
#### POST
<dl class="api">
  <dt>Description</dt>
  <dd>
    Cleans up the entries in the blacklist based on expiration time on the entry and `safety_buffer`.
  </dd>

  <dt>Method</dt>
  <dd>POST</dd>

  <dt>URL</dt>
  <dd>`/auth/aws/tidy/roletags`</dd>

  <dt>Parameters</dt>
  <dd>
    <ul>
      <li>
        <span class="param">safety_buffer</span>
        <span class="param-flags">optional</span>
        The amount of extra time that must have passed beyond the `roletag` expiration, before it is removed from the backend storage. Defaults to 72h.
      </li>
    </ul>
  </dd>

  <dt>Returns</dt>
  <dd>`204` response code.
  </dd>
</dl>


### /auth/aws/whitelist/identity/<instance_id>
#### GET
<dl class="api">
  <dt>Description</dt>
  <dd>
    Returns an entry in the whitelist. An entry will be created/updated by every successful login.
  </dd>

  <dt>Method</dt>
  <dd>GET</dd>

  <dt>URL</dt>
  <dd>`/auth/aws/whitelist/identity/<instance_id>`</dd>

  <dt>Parameters</dt>
  <dd>
    <ul>
      <li>
        <span class="param">instance_id</span>
        <span class="param-flags">required</span>
        EC2 instance ID. A successful login operation from an EC2 instance gets cached in this whitelist, keyed off of instance ID.
      </li>
    </ul>
  </dd>

  <dt>Returns</dt>
  <dd>

```javascript
{
  "auth": null,
  "warnings": null,
  "data": {
    "pending_time": "2016-04-14T01:01:41Z",
    "expiration_time": "2016-05-05 10:09:16.67077232 +0000 UTC",
    "creation_time": "2016-04-14 14:09:16.67077232 +0000 UTC",
    "client_nonce": "vault-client-nonce",
    "ami_id": "ami-fce3c696"
  },
  "lease_duration": 0,
  "renewable": false,
  "lease_id": ""
}
```

  </dd>
</dl>


#### LIST
<dl class="api">
  <dt>Description</dt>
  <dd>
    Lists all the instance IDs that are in the whitelist of successful logins.
  </dd>

  <dt>Method</dt>
  <dd>GET</dd>

  <dt>URL</dt>
  <dd>`/auth/aws/whitelist/identities?list=true`</dd>

  <dt>Parameters</dt>
  <dd>
    None.
  </dd>

  <dt>Returns</dt>
  <dd>`204` response code.

```javascript
{
  "auth": null,
  "warnings": null,
  "data": {
    "keys": [
      "i-aab47d37"
    ]
  },
  "lease_duration": 0,
  "renewable": false,
  "lease_id": ""
}
```

  </dd>
</dl>


#### DELETE
<dl class="api">
  <dt>Description</dt>
  <dd>
    Deletes a cache of the successful login from an instance.
  </dd>

  <dt>Method</dt>
  <dd>DELETE</dd>

  <dt>URL</dt>
  <dd>`/auth/aws/whitelist/identity/<instance_id>`</dd>

  <dt>Parameters</dt>
  <dd>
    None.
  </dd>

  <dt>Returns</dt>
  <dd>`204` response code.
  </dd>
</dl>


### /auth/aws/tidy/identities
#### POST
<dl class="api">
  <dt>Description</dt>
  <dd>
    Cleans up the entries in the whitelist based on expiration time and `safety_buffer`.
  </dd>

  <dt>Method</dt>
  <dd>POST</dd>

  <dt>URL</dt>
  <dd>`/auth/aws/tidy/identities`</dd>

  <dt>Parameters</dt>
  <dd>
    <ul>
      <li>
        <span class="param">safety_buffer</span>
        <span class="param-flags">optional</span>
        The amount of extra time that must have passed beyond the identity expiration, before it is removed from the backend storage. Defaults to 72h.
      </li>
    </ul>
  </dd>

  <dt>Returns</dt>
  <dd>`204` response code.
  </dd>
</dl>