1731 lines
50 KiB
Markdown
1731 lines
50 KiB
Markdown
---
|
|
layout: "docs"
|
|
page_title: "Auth Backend: AWS-EC2"
|
|
sidebar_current: "docs-auth-aws-ec2"
|
|
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-role. Roles 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. Each role can
|
|
be specified with the constraints that are to be met during the login. For
|
|
example, one such constraint that is supported is to bind against AMI ID. A
|
|
role which is bound to a specific AMI, can only be used for login by those
|
|
instances that are deployed on the same AMI.
|
|
|
|
In many cases, an organization will use a "seed AMI" that is specialized after
|
|
bootup by configuration management or similar processes. For this reason, a
|
|
role 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 role, but cannot be used to grant additional privileges.
|
|
If a role with an AMI bind constraint has "role tag" enabled on the role, and
|
|
the EC2 instance performing login does not have an expected tag on it, or if the
|
|
tag on the instance is deleted for some reason, authentication fails.
|
|
|
|
The role tags can be generated at will by an operator with appropriate API
|
|
access. They are HMAC-signed by a per-role 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, using the
|
|
'disallow_reauthentication' option on the role, meaning that an instance is
|
|
allowed to login only once. However, this has consequences for token rotation,
|
|
as it means that once a token has expired, subsequent authentication attempts
|
|
would fail. By default, reauthentication is enabled in this backend, and can be
|
|
turned off using 'disallow_reauthentication' parameter on the registered role.
|
|
|
|
In the default method of operation, the backend will return a unique nonce
|
|
during the first authentication attempt, as part of auth `metadata`. Clients
|
|
should present this `nonce` for subsequent login attempts and it should match
|
|
the `nonce` cached at the identity-whitelist entry at the backend. 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.). Clients can choose to provide a `nonce` even
|
|
for the first login attempt, in which case the provided `nonce` will be tied to
|
|
the cached identity-whitelist entry. It is recommended to use a strong `nonce`
|
|
value in this case.
|
|
|
|
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).
|
|
|
|
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, for a given role. 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 role and are used to further restrict the set of the role's
|
|
privileges for that particular instance.
|
|
|
|
A `role_tag` can be created using `auth/aws-ec2/role/<role>/tag` endpoint
|
|
and is immutable. The information present in the tag is SHA256 hashed and HMAC
|
|
protected. The per-role 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 enabled on a role, 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 getting the tag removed. If the role tag creation does
|
|
not specify the policy component, the client will inherit the allowed policies set
|
|
on the role. If the role tag creation specifies the 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-ec2/identity-whitelist/<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-role. 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-role, 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 role, a value of `true` in the role tag takes
|
|
effect; however, if the option is set to `true` on the role, 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, `disallow_reauthentication` should be set explicitly
|
|
on the role or on the role tag.
|
|
|
|
The `disallow_reauthentication` option is set per-role, 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 role, a value of `true` in the role tag takes
|
|
effect; however, if the option is set to `true` on the role, a value set in the
|
|
role tag has no effect.
|
|
|
|
### Blacklisting Role Tags
|
|
|
|
Role tags are tied to a specific role, but the backend has no control over, which
|
|
instances using that role, should have any particular role tag; that is purely up
|
|
to the operator. Although role tags are only restrictive (a tag cannot escalate
|
|
privileges above what is set on its role), 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-ec2/roletag-blacklist/<role_tag>`. Note that this will not invalidate the
|
|
tokens that were already issued; this only blocks any further login requests from
|
|
those instances that have the blacklisted tag attached to them.
|
|
|
|
### 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 role,
|
|
`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/identity-whitelist` and `aws/auth/tidy/roletag-blacklist` 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 entries 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/roletag-blacklist` and `config/tidy/identity-whitelist`
|
|
endpoints.
|
|
|
|
### Varying Public Certificates
|
|
|
|
The AWS public certificate, which contains the public key used to verify the
|
|
PKCS#7 signature, varies for different AWS regions. The primary AWS public
|
|
certificate, which covers most AWS regions, is already included in Vault and
|
|
does not need to be added. Instances whose PKCS#7 signatures cannot be
|
|
verified by the default public certificate included in Vault 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-ec2/config/certificate/<cert_name>` endpoint.
|
|
|
|
### Dangling Tokens
|
|
|
|
An EC2 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.
|
|
|
|
### Cross Account Access
|
|
|
|
To allow Vault to authenticate EC2 instances running in other accounts, AWS STS (Security
|
|
Token Service) can be used to retrieve temporary credentials by assuming an IAM Role
|
|
in those accounts.
|
|
|
|
The account in which Vault is running (i.e. the master account) must be listed as
|
|
a trusted entity in the IAM Role being assumed on the remote account. The Role itself
|
|
must allow the `ec2:DescribeInstances` action, and `iam:GetInstanceProfile` if IAM Role
|
|
binding is used (see below).
|
|
|
|
Furthermore, in the master account, Vault must be granted the action `sts:AssumeRole`
|
|
for the IAM Role to be assumed.
|
|
|
|
## Authentication
|
|
|
|
### Via the CLI
|
|
|
|
#### Enable AWS EC2 authentication in Vault.
|
|
|
|
```
|
|
$ vault auth-enable aws-ec2
|
|
```
|
|
|
|
#### Configure the credentials required to make AWS API calls
|
|
|
|
If not specified, Vault will attempt to use standard environment variables
|
|
(`AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`) or IAM EC2 instance role
|
|
credentials if available.
|
|
|
|
The IAM account or role to which the credentials map must allow the
|
|
`ec2:DescribeInstances` action. In addition, if IAM Role binding is used (see
|
|
`bound_iam_role_arn` below), `iam:GetInstanceProfile` must also be allowed.
|
|
|
|
```
|
|
$ vault write auth/aws-ec2/config/client secret_key=vCtSM8ZUEQ3mOFVlYPBQkf2sO6F/W7a5TVzrl3Oj access_key=VKIAJBRHKH6EVTTNXDHA
|
|
```
|
|
|
|
#### Configure the policies on the role.
|
|
|
|
```
|
|
$ vault write auth/aws-ec2/role/dev-role bound_ami_id=ami-fce3c696 policies=prod,dev max_ttl=500h
|
|
```
|
|
|
|
#### Perform the login operation
|
|
|
|
```
|
|
$ vault write auth/aws-ec2/login role=dev-role \
|
|
pkcs7=MIAGCSqGSIb3DQEHAqCAMIACAQExCzAJBgUrDgMCGgUAMIAGCSqGSIb3DQEHAaCAJIAEggGmewogICJkZXZwYXlQcm9kdWN0Q29kZXMiIDogbnVsbCwKICAicHJpdmF0ZUlwIiA6ICIxNzIuMzEuNjMuNjAiLAogICJhdmFpbGFiaWxpdHlab25lIiA6ICJ1cy1lYXN0LTFjIiwKICAidmVyc2lvbiIgOiAiMjAxMC0wOC0zMSIsCiAgImluc3RhbmNlSWQiIDogImktZGUwZjEzNDQiLAogICJiaWxsaW5nUHJvZHVjdHMiIDogbnVsbCwKICAiaW5zdGFuY2VUeXBlIiA6ICJ0Mi5taWNybyIsCiAgImFjY291bnRJZCIgOiAiMjQxNjU2NjE1ODU5IiwKICAiaW1hZ2VJZCIgOiAiYW1pLWZjZTNjNjk2IiwKICAicGVuZGluZ1RpbWUiIDogIjIwMTYtMDQtMDVUMTY6MjY6NTVaIiwKICAiYXJjaGl0ZWN0dXJlIiA6ICJ4ODZfNjQiLAogICJrZXJuZWxJZCIgOiBudWxsLAogICJyYW1kaXNrSWQiIDogbnVsbCwKICAicmVnaW9uIiA6ICJ1cy1lYXN0LTEiCn0AAAAAAAAxggEXMIIBEwIBATBpMFwxCzAJBgNVBAYTAlVTMRkwFwYDVQQIExBXYXNoaW5ndG9uIFN0YXRlMRAwDgYDVQQHEwdTZWF0dGxlMSAwHgYDVQQKExdBbWF6b24gV2ViIFNlcnZpY2VzIExMQwIJAJa6SNnlXhpnMAkGBSsOAwIaBQCgXTAYBgkqhkiG9w0BCQMxCwYJKoZIhvcNAQcBMBwGCSqGSIb3DQEJBTEPFw0xNjA0MDUxNjI3MDBaMCMGCSqGSIb3DQEJBDEWBBRtiynzMTNfTw1TV/d8NvfgVw+XfTAJBgcqhkjOOAQDBC4wLAIUVfpVcNYoOKzN1c+h1Vsm/c5U0tQCFAK/K72idWrONIqMOVJ8Uen0wYg4AAAAAAAA nonce=5defbf9e-a8f9-3063-bdfc-54b7a42a1f95
|
|
```
|
|
|
|
|
|
### 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-ec2"}'
|
|
```
|
|
|
|
#### 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-ec2/config/client" -d '{"access_key":"VKIAJBRHKH6EVTTNXDHA", "secret_key":"vCtSM8ZUEQ3mOFVlYPBQkf2sO6F/W7a5TVzrl3Oj"}'
|
|
```
|
|
|
|
#### Configure the policies on the role.
|
|
|
|
```
|
|
curl -X POST -H "x-vault-token:123" "http://127.0.0.1:8200/v1/auth/aws-ec2/role/dev-role -d '{"bound_ami_id":"ami-fce3c696","policies":"prod,dev","max_ttl":"500h"}'
|
|
```
|
|
|
|
#### Perform the login operation
|
|
|
|
```
|
|
curl -X POST "http://127.0.0.1:8200/v1/auth/aws-ec2/login" -d
|
|
'{"role":"dev-role","pkcs7":"'$(curl -s http://169.254.169.254/latest/dynamic/instance-identity/pkcs7 | tr -d '\n')'","nonce":"5defbf9e-a8f9-3063-bdfc-54b7a42a1f95"}'
|
|
```
|
|
|
|
|
|
The response will be in JSON. For example:
|
|
|
|
```javascript
|
|
{
|
|
"auth": {
|
|
"renewable": true,
|
|
"lease_duration": 72000,
|
|
"metadata": {
|
|
"role_tag_max_ttl": "0s",
|
|
"role": "ami-f083709d",
|
|
"region": "us-east-1",
|
|
"nonce": "5defbf9e-a8f9-3063-bdfc-54b7a42a1f95",
|
|
"instance_id": "i-a832f734",
|
|
"ami_id": "ami-f083709d"
|
|
},
|
|
"policies": [
|
|
"default",
|
|
"dev",
|
|
"prod"
|
|
],
|
|
"accessor": "5cd96cd1-58b7-2904-5519-75ddf957ec06",
|
|
"client_token": "150fc858-2402-49c9-56a5-f4b57f2c8ff1"
|
|
},
|
|
"warnings": null,
|
|
"wrap_info": null,
|
|
"data": null,
|
|
"lease_duration": 0,
|
|
"renewable": false,
|
|
"lease_id": "",
|
|
"request_id": "d7d50c06-56b8-37f4-606c-ccdc87a1ee4c"
|
|
}
|
|
```
|
|
|
|
## API
|
|
### /auth/aws-ec2/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
|
|
DescribeInstances API. If 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-ec2/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 DescribeInstances API.
|
|
</li>
|
|
</ul>
|
|
<ul>
|
|
<li>
|
|
<span class="param">secret_key</span>
|
|
<span class="param-flags">required</span>
|
|
AWS Secret key with permissions to query EC2 DescribeInstances API.
|
|
</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-ec2/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-ec2/config/client`</dd>
|
|
|
|
<dt>Parameters</dt>
|
|
<dd>
|
|
None.
|
|
</dd>
|
|
|
|
<dt>Returns</dt>
|
|
<dd>`204` response code.
|
|
</dd>
|
|
</dl>
|
|
|
|
|
|
### /auth/aws-ec2/config/certificate/<cert_name>
|
|
#### POST
|
|
<dl class="api">
|
|
<dt>Description</dt>
|
|
<dd>
|
|
Registers an AWS public key to be used to verify the instance identity
|
|
documents. While the PKCS#7 signature of the identity documents have DSA
|
|
digest, the identity signature will have RSA digest, and hence the public keys
|
|
for each type varies respectively. Indicate the type of the public key using
|
|
the "type" parameter.
|
|
</dd>
|
|
|
|
<dt>Method</dt>
|
|
<dd>POST</dd>
|
|
|
|
<dt>URL</dt>
|
|
<dd>`/auth/aws-ec2/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>
|
|
<ul>
|
|
<li>
|
|
<span class="param">type</span>
|
|
<span class="param-flags">optional</span>
|
|
Takes the value of either "pkcs7" or "identity", indicating the type of
|
|
document which can be verified using the given certificate. The PKCS#7 document
|
|
will have a DSA digest and the identity signature will have an RSA signature,
|
|
and accordingly the public certificates to verify those also vary. Defaults to
|
|
"pkcs7".
|
|
</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-ec2/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>LIST/GET</dd>
|
|
|
|
<dt>URL</dt>
|
|
<dd>`/auth/aws-ec2/config/certificates` (LIST) or `/auth/aws-ec2/config/certificates?list=true` (GET)</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-ec2/config/sts/<account_id>
|
|
#### POST
|
|
<dl class="api">
|
|
<dt>Description</dt>
|
|
<dd>
|
|
Allows the explicit association of STS roles to satellite AWS accounts (i.e. those
|
|
which are not the account in which the Vault server is running.) Login attempts from
|
|
EC2 instances running in these accounts will be verified using credentials obtained
|
|
by assumption of these STS roles.
|
|
</dd>
|
|
|
|
<dt>Method</dt>
|
|
<dd>POST</dd>
|
|
|
|
<dt>URL</dt>
|
|
<dd>`/auth/aws-ec2/config/certificate/<account_id>`</dd>
|
|
|
|
<dt>Parameters</dt>
|
|
<dd>
|
|
<ul>
|
|
<li>
|
|
<span class="param">account_id</span>
|
|
<span class="param-flags">required</span>
|
|
AWS account ID to be associated with STS role. If set,
|
|
Vault will use assumed credentials to verify any login attempts from EC2
|
|
instances in this account.
|
|
</li>
|
|
</ul>
|
|
<ul>
|
|
<li>
|
|
<span class="param">sts_role</span>
|
|
<span class="param-flags">required</span>
|
|
AWS ARN for STS role to be assumed when interacting with the account specified.
|
|
The Vault server must have permissions to assume this role.
|
|
</li>
|
|
</ul>
|
|
</dd>
|
|
|
|
<dt>Returns</dt>
|
|
<dd>`204` response code.
|
|
</dd>
|
|
</dl>
|
|
|
|
#### GET
|
|
<dl class="api">
|
|
<dt>Description</dt>
|
|
<dd>
|
|
Returns the previously configured STS role.
|
|
</dd>
|
|
|
|
<dt>Method</dt>
|
|
<dd>GET</dd>
|
|
|
|
<dt>URL</dt>
|
|
<dd>`/auth/aws-ec2/config/sts/<account_id>`</dd>
|
|
|
|
<dt>Parameters</dt>
|
|
<dd>
|
|
None.
|
|
</dd>
|
|
|
|
<dt>Returns</dt>
|
|
<dd>
|
|
|
|
```javascript
|
|
{
|
|
"auth": null,
|
|
"warnings": null,
|
|
"data": {
|
|
"sts_role ": "arn:aws:iam:<account_id>:role/myRole"
|
|
},
|
|
"lease_duration": 0,
|
|
"renewable": false,
|
|
"lease_id": ""
|
|
}
|
|
```
|
|
|
|
</dd>
|
|
</dl>
|
|
|
|
#### LIST
|
|
<dl class="api">
|
|
<dt>Description</dt>
|
|
<dd>
|
|
Lists all the AWS Account IDs for which an STS role is registered
|
|
</dd>
|
|
|
|
<dt>Method</dt>
|
|
<dd>LIST/GET</dd>
|
|
|
|
<dt>URL</dt>
|
|
<dd>`/auth/aws-ec2/config/sts` (LIST) or `/auth/aws-ec2/config/sts?list=true` (GET)</dd>
|
|
|
|
<dt>Parameters</dt>
|
|
<dd>
|
|
None.
|
|
</dd>
|
|
|
|
<dt>Returns</dt>
|
|
<dd>
|
|
|
|
```javascript
|
|
{
|
|
"auth": null,
|
|
"warnings": null,
|
|
"data": {
|
|
"keys": [
|
|
"<account_id_1>",
|
|
"<account_id_2>"
|
|
]
|
|
},
|
|
"lease_duration": 0,
|
|
"renewable": false,
|
|
"lease_id": ""
|
|
}
|
|
```
|
|
|
|
</dd>
|
|
</dl>
|
|
|
|
#### DELETE
|
|
<dl class="api">
|
|
<dt>Description</dt>
|
|
<dd>
|
|
Deletes a previously configured AWS account/STS role association
|
|
</dd>
|
|
|
|
<dt>Method</dt>
|
|
<dd>DELETE</dd>
|
|
|
|
<dt>URL</dt>
|
|
<dd>`/auth/aws-ec2/config/sts/<account_id>`</dd>
|
|
|
|
<dt>Parameters</dt>
|
|
<dd>
|
|
None.
|
|
</dd>
|
|
|
|
<dt>Returns</dt>
|
|
<dd>`204` response code.
|
|
</dd>
|
|
</dl>
|
|
|
|
### /auth/aws-ec2/config/tidy/identity-whitelist
|
|
##### 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-ec2/config/tidy/identity-whitelist`</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 'identity-whitelist/<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-ec2/config/tidy/identity-whitelist`</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-ec2/config/tidy/identity-whitelist`</dd>
|
|
|
|
<dt>Parameters</dt>
|
|
<dd>
|
|
None.
|
|
</dd>
|
|
|
|
<dt>Returns</dt>
|
|
<dd>`204` response code.
|
|
</dd>
|
|
</dl>
|
|
|
|
|
|
|
|
### /auth/aws-ec2/config/tidy/roletag-blacklist
|
|
##### 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-ec2/config/tidy/roletag-blacklist`</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 'roletag-blacklist/<role_tag>' 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-ec2/config/tidy/roletag-blacklist`</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-ec2/config/tidy/roletag-blacklist`</dd>
|
|
|
|
<dt>Parameters</dt>
|
|
<dd>
|
|
None.
|
|
</dd>
|
|
|
|
<dt>Returns</dt>
|
|
<dd>`204` response code.
|
|
</dd>
|
|
</dl>
|
|
|
|
|
|
|
|
### /auth/aws-ec2/role/[role]
|
|
#### POST
|
|
<dl class="api">
|
|
<dt>Description</dt>
|
|
<dd>
|
|
Registers a role in the backend. Only those instances which are using
|
|
the role registered using this endpoint, will be able to perform the login
|
|
operation. Contraints can be specified on the role, that are applied on the
|
|
instances attempting to login. At least one constraint should be specified
|
|
on the role.
|
|
</dd>
|
|
|
|
<dt>Method</dt>
|
|
<dd>POST</dd>
|
|
|
|
<dt>URL</dt>
|
|
<dd>`/auth/aws-ec2/role/<role>`</dd>
|
|
|
|
<dt>Parameters</dt>
|
|
<dd>
|
|
<ul>
|
|
<li>
|
|
<span class="param">role</span>
|
|
<span class="param-flags">required</span>
|
|
Name of the role.
|
|
</li>
|
|
</ul>
|
|
<ul>
|
|
<li>
|
|
<span class="param">bound_ami_id</span>
|
|
<span class="param-flags">optional</span>
|
|
If set, defines a constraint on the EC2 instances that they
|
|
should be using the AMI ID specified by this parameter.
|
|
</li>
|
|
</ul>
|
|
<ul>
|
|
<li>
|
|
<span class="param">bound_account_id</span>
|
|
<span class="param-flags">optional</span>
|
|
If set, defines a constraint on the EC2 instances that the account ID
|
|
in its identity document to match the one specified by this parameter.
|
|
</li>
|
|
</ul>
|
|
<ul>
|
|
<li>
|
|
<span class="param">bound_iam_role_arn</span>
|
|
<span class="param-flags">optional</span>
|
|
If set, defines a constraint on the authenticating EC2 instance that it
|
|
must match the IAM role ARN specified by this parameter. The value is
|
|
prefix-matched (as though it were a glob ending in `*`). The configured
|
|
IAM user or EC2 instance role must be allowed to execute the
|
|
`iam:GetInstanceProfile` action if this is specified.
|
|
</li>
|
|
</ul>
|
|
<ul>
|
|
<li>
|
|
<span class="param">bound_iam_instance_profile_arn</span>
|
|
<span class="param-flags">optional</span>
|
|
If set, defines a constraint on the EC2 instances to be associated with an IAM
|
|
instance profile ARN which has a prefix that matches the value specified by
|
|
this parameter. The value is prefix-matched (as though it were a glob ending
|
|
in `*`).
|
|
</li>
|
|
</ul>
|
|
<ul>
|
|
<li>
|
|
<span class="param">role_tag</span>
|
|
<span class="param-flags">optional</span>
|
|
If set, enables the role tags for this role. The value set for this
|
|
field should be the 'key' of the tag on the EC2 instance. The 'value'
|
|
of the tag should be generated using 'role/<role>/tag' endpoint.
|
|
Defaults to an empty string, meaning that role tags are disabled.
|
|
</li>
|
|
</ul>
|
|
<ul>
|
|
<li>
|
|
<span class="param">ttl</span>
|
|
<span class="param-flags">optional</span>
|
|
The TTL period of tokens issued using this role, provided as "1h", where hour is
|
|
the largest suffix.
|
|
</li>
|
|
</ul>
|
|
<ul>
|
|
<li>
|
|
<span class="param">max_ttl</span>
|
|
<span class="param-flags">optional</span>
|
|
The maximum allowed lifetime of tokens issued using this role.
|
|
</li>
|
|
</ul>
|
|
<ul>
|
|
<li>
|
|
<span class="param">period</span>
|
|
<span class="param-flags">optional</span>
|
|
If set, indicates that the token generated using this role should never
|
|
expire. The token should be renewed within the duration specified by
|
|
this value. At each renewal, the token's TTL will be set to the value
|
|
of this parameter. The maximum allowed lifetime of tokens issued using
|
|
this role.
|
|
</li>
|
|
</ul>
|
|
<ul>
|
|
<li>
|
|
<span class="param">policies</span>
|
|
<span class="param-flags">optional</span>
|
|
Policies to be set on tokens issued using this role.
|
|
</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-ec2/identity-whitelist/<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 role configuration.
|
|
</dd>
|
|
|
|
<dt>Method</dt>
|
|
<dd>GET</dd>
|
|
|
|
<dt>URL</dt>
|
|
<dd>`/auth/aws-ec2/role/<role>`</dd>
|
|
|
|
<dt>Parameters</dt>
|
|
<dd>
|
|
None.
|
|
</dd>
|
|
|
|
<dt>Returns</dt>
|
|
<dd>
|
|
|
|
```javascript
|
|
{
|
|
"auth": null,
|
|
"warnings": null,
|
|
"data": {
|
|
"bound_ami_id": "ami-fce36987",
|
|
"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 roles that are registered with the backend.
|
|
</dd>
|
|
|
|
<dt>Method</dt>
|
|
<dd>LIST/GET</dd>
|
|
|
|
<dt>URL</dt>
|
|
<dd>`/auth/aws-ec2/roles` (LIST) or `/auth/aws-ec2/roles?list=true` (GET)</dd>
|
|
|
|
<dt>Parameters</dt>
|
|
<dd>
|
|
None.
|
|
</dd>
|
|
|
|
<dt>Returns</dt>
|
|
<dd>
|
|
|
|
```javascript
|
|
{
|
|
"auth": null,
|
|
"warnings": null,
|
|
"data": {
|
|
"keys": [
|
|
"dev-role",
|
|
"prod-role"
|
|
]
|
|
},
|
|
"lease_duration": 0,
|
|
"renewable": false,
|
|
"lease_id": ""
|
|
}
|
|
```
|
|
|
|
</dd>
|
|
</dl>
|
|
|
|
|
|
#### DELETE
|
|
<dl class="api">
|
|
<dt>Description</dt>
|
|
<dd>
|
|
Deletes the previously registered role.
|
|
</dd>
|
|
|
|
<dt>Method</dt>
|
|
<dd>DELETE</dd>
|
|
|
|
<dt>URL</dt>
|
|
<dd>`/auth/aws-ec2/role/<role>`</dd>
|
|
|
|
<dt>Parameters</dt>
|
|
<dd>
|
|
None.
|
|
</dd>
|
|
|
|
<dt>Returns</dt>
|
|
<dd>`204` response code.
|
|
</dd>
|
|
</dl>
|
|
|
|
|
|
### /auth/aws-ec2/role/[role]/tag
|
|
#### POST
|
|
<dl class="api">
|
|
<dt>Description</dt>
|
|
<dd>
|
|
Creates a role tag on the role, which help in restricting the capabilities that
|
|
are set on the role. Role tags are not tied to any specific ec2 instance unless
|
|
specified explicitly using the `instance_id` parameter. By default, role tags
|
|
are designed to be used across all instances that satisfies the constraints on
|
|
the role. Regardless of which instances have role tags on them, capabilities
|
|
defined in a role tag must be a strict subset of the given role's capabilities.
|
|
Note that, since adding and removing a tag is often a widely distributed
|
|
privilege, care needs to be taken to ensure that the instances are attached
|
|
with correct tags to not let them gain more privileges than what were intended.
|
|
If a role tag is changed, the capabilities inherited by the instance will be
|
|
those defined on the new role tag. Since those must be a subset of the role
|
|
capabilities, the role should never provide more capabilities than any given
|
|
instance can be allowed to gain in a worst-case scenario.
|
|
</dd>
|
|
|
|
<dt>Method</dt>
|
|
<dd>POST</dd>
|
|
|
|
<dt>URL</dt>
|
|
<dd>`/auth/aws-ec2/role/<role>/tag`</dd>
|
|
|
|
<dt>Parameters</dt>
|
|
<dd>
|
|
<ul>
|
|
<li>
|
|
<span class="param">role</span>
|
|
<span class="param-flags">required</span>
|
|
Name of the role.
|
|
</li>
|
|
</ul>
|
|
<ul>
|
|
<li>
|
|
<span class="param">policies</span>
|
|
<span class="param-flags">optional</span>
|
|
Policies to be associated with the tag. If set, must be a subset of
|
|
the role's policies. If set, but set to an empty value, only the
|
|
'default' policy will be given to issued tokens.
|
|
</li>
|
|
</ul>
|
|
<ul>
|
|
<li>
|
|
<span class="param">max_ttl</span>
|
|
<span class="param-flags">optional</span>
|
|
If set, specifies the maximum allowed token lifetime.
|
|
</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">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-ec2/identity-whitelist 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=:r=dev-role:p=default,prod:d=false:t=300h0m0s:uPLKCQxqsefRhrp1qmVa1wsQVUXXJG8UZP/pJIdVyOI=",
|
|
"tag_key": "VaultRole"
|
|
},
|
|
"lease_duration": 0,
|
|
"renewable": false,
|
|
"lease_id": ""
|
|
}
|
|
```
|
|
|
|
</dd>
|
|
</dl>
|
|
|
|
|
|
### /auth/aws-ec2/login
|
|
#### POST
|
|
<dl class="api">
|
|
<dt>Description</dt>
|
|
<dd>
|
|
Fetch a token. This endpoint verifies the pkcs7 signature of the instance
|
|
identity document. Verifies that the instance is actually in a running state.
|
|
Cross checks the constraints defined on the role with which the login is being
|
|
performed. As an alternative to pkcs7 signature, the identity document along
|
|
with its RSA digest can be supplied to this endpoint.
|
|
</dd>
|
|
|
|
<dt>Method</dt>
|
|
<dd>POST</dd>
|
|
|
|
<dt>URL</dt>
|
|
<dd>`/auth/aws-ec2/login`</dd>
|
|
|
|
<dt>Parameters</dt>
|
|
<dd>
|
|
<ul>
|
|
<li>
|
|
<span class="param">role</span>
|
|
<span class="param-flags">optional</span>
|
|
Name of the role against which the login is being attempted.
|
|
If `role` is not specified, then the login endpoint looks for a role
|
|
bearing the name of the AMI ID of the EC2 instance that is trying to login.
|
|
If a matching role is not found, login fails.
|
|
</li>
|
|
</ul>
|
|
<ul>
|
|
<li>
|
|
<span class="param">identity</span>
|
|
<span class="param-flags">required</span>
|
|
Base64 encoded EC2 instance identity document. This needs to be supplied along
|
|
with the `signature` parameter. If using `curl` for fetching the identity
|
|
document, consider using the option `-w 0` while piping the output to
|
|
`base64` binary.
|
|
</li>
|
|
</ul>
|
|
<ul>
|
|
<li>
|
|
<span class="param">signature</span>
|
|
<span class="param-flags">required</span>
|
|
Base64 encoded SHA256 RSA signature of the instance identity document. This
|
|
needs to be supplied along with `identity` parameter.
|
|
</li>
|
|
</ul>
|
|
<ul>
|
|
<li>
|
|
<span class="param">pkcs7</span>
|
|
<span class="param-flags">required</span>
|
|
PKCS7 signature of the identity document with all `\n` characters removed.
|
|
Either this needs to be set *OR* both `identity` and `signature` need to be
|
|
set.
|
|
</li>
|
|
</ul>
|
|
<ul>
|
|
<li>
|
|
<span class="param">nonce</span>
|
|
<span class="param-flags">optional</span>
|
|
The nonce to be used for subsequent login requests. If this parameter is not
|
|
specified at all and if reauthentication is allowed, then the backend will
|
|
generate a random nonce, attaches it to the instance's identity-whitelist entry
|
|
and returns the nonce back as part of auth metadata. This value should be used
|
|
with further login requests, to establish client authenticity. Clients can
|
|
choose to set a custom nonce if preferred, in which case, it is recommended
|
|
that clients provide a strong nonce. If a nonce is provided but with an empty
|
|
value, it indicates intent to disable reauthentication. Note that, when
|
|
`disallow_reauthentication` option is enabled on either the role or the role
|
|
tag, the `nonce` holds no significance.
|
|
</li>
|
|
</ul>
|
|
</dd>
|
|
|
|
<dt>Returns</dt>
|
|
<dd>
|
|
|
|
```javascript
|
|
{
|
|
"auth": {
|
|
"renewable": true,
|
|
"lease_duration": 1800000,
|
|
"metadata": {
|
|
"role_tag_max_ttl": "0",
|
|
"instance_id": "i-de0f1344"
|
|
"ami_id": "ami-fce36983"
|
|
"role": "dev-role"
|
|
},
|
|
"policies": [
|
|
"default",
|
|
"dev",
|
|
],
|
|
"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-ec2/roletag-blacklist/<role_tag>
|
|
#### POST
|
|
<dl class="api">
|
|
<dt>Description</dt>
|
|
<dd>
|
|
Places a valid role tag in a blacklist. This ensures that the role tag
|
|
cannot be used by any instance to perform a login operation again.
|
|
Note that if the role tag was previously used to perform a successful
|
|
login, placing the tag in the blacklist does not invalidate the
|
|
already issued token.
|
|
</dd>
|
|
|
|
<dt>Method</dt>
|
|
<dd>POST</dd>
|
|
|
|
<dt>URL</dt>
|
|
<dd>`/auth/aws-ec2/roletag-blacklist/<role_tag>`</dd>
|
|
|
|
<dt>Parameters</dt>
|
|
<dd>
|
|
<ul>
|
|
<li>
|
|
<span class="param">role_tag</span>
|
|
<span class="param-flags">required</span>
|
|
Role tag to be blacklisted. The tag can be supplied as-is. In order
|
|
to avoid any encoding problems, it 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 role tag.
|
|
</dd>
|
|
|
|
<dt>Method</dt>
|
|
<dd>GET</dd>
|
|
|
|
<dt>URL</dt>
|
|
<dd>`/auth/aws-ec2/broletag-blacklist/<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 role tags that are blacklisted.
|
|
</dd>
|
|
|
|
<dt>Method</dt>
|
|
<dd>LIST/GET</dd>
|
|
|
|
<dt>URL</dt>
|
|
<dd>`/auth/aws-ec2/roletag-blacklist` (LIST) or `/auth/aws-ec2/roletag-blacklist?list=true` (GET)</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 role tag.
|
|
</dd>
|
|
|
|
<dt>Method</dt>
|
|
<dd>DELETE</dd>
|
|
|
|
<dt>URL</dt>
|
|
<dd>`/auth/aws-ec2/roletag-blacklist/<role_tag>`</dd>
|
|
|
|
<dt>Parameters</dt>
|
|
<dd>
|
|
None.
|
|
</dd>
|
|
|
|
<dt>Returns</dt>
|
|
<dd>`204` response code.
|
|
</dd>
|
|
</dl>
|
|
|
|
|
|
### /auth/aws-ec2/tidy/roletag-blacklist
|
|
#### 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-ec2/tidy/roletag-blacklist`</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-ec2/identity-whitelist/<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-ec2/identity-whitelist/<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": "5defbf9e-a8f9-3063-bdfc-54b7a42a1f95",
|
|
"role": "dev-role"
|
|
},
|
|
"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>LIST/GET</dd>
|
|
|
|
<dt>URL</dt>
|
|
<dd>`/auth/aws-ec2/identity-whitelist` (LIST) or `/auth/aws-ec2/identity-whitelist?list=true` (GET)</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-ec2/identity-whitelist/<instance_id>`</dd>
|
|
|
|
<dt>Parameters</dt>
|
|
<dd>
|
|
None.
|
|
</dd>
|
|
|
|
<dt>Returns</dt>
|
|
<dd>`204` response code.
|
|
</dd>
|
|
</dl>
|
|
|
|
|
|
### /auth/aws-ec2/tidy/identity-whitelist
|
|
#### 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-ec2/tidy/identity-whitelist`</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>
|