mirror of https://github.com/hashicorp/consul
Docs: IAM auth method (#12779)
* Docs: IAM auth method Co-authored-by: Karl Cardenas <kcardenas@hashicorp.com>pull/12818/head
Paul Glass
3 years ago
committed by
GitHub
parent
000d0621b4
commit
90b2cb6128
@ -0,0 +1,210 @@
|
|||||||
|
---
|
||||||
|
layout: docs
|
||||||
|
page_title: AWS IAM Auth Method
|
||||||
|
description: >-
|
||||||
|
The AWS IAM auth method type allows for AWS IAM Roles and Users
|
||||||
|
to be used to authenticate to Consul.
|
||||||
|
---
|
||||||
|
|
||||||
|
# AWS IAM Auth Method
|
||||||
|
|
||||||
|
|
||||||
|
The AWS Identity and Access Management (IAM) auth method type allows for AWS
|
||||||
|
IAM Roles and Users to be used to authenticate to Consul in order to obtain
|
||||||
|
a Consul token.
|
||||||
|
|
||||||
|
This page assumes general knowledge of [AWS
|
||||||
|
IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction.html)
|
||||||
|
and the concepts described in the main [auth method
|
||||||
|
documentation](/docs/security/acl/auth-methods).
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
The AWS IAM auth method for Consul uses a variation on the approach used by the [IAM auth method for
|
||||||
|
Vault](https://www.vaultproject.io/docs/auth/aws#iam-auth-method). Specifically, the IAM auth method
|
||||||
|
for Consul avoids the need to configure Consul servers with AWS credentials by requiring clients to
|
||||||
|
provided pre-signed AWS API requests.
|
||||||
|
|
||||||
|
An IAM role or user authenticates by presenting certain signed AWS API requests in a specific JSON
|
||||||
|
format. The client signs the necessary AWS API requests with its AWS credentials using the [AWS
|
||||||
|
Signature v4 algorithm](https://docs.aws.amazon.com/general/latest/gr/sigv4_signing.html). When the
|
||||||
|
auth method receives the signed AWS API requests, it forwards the requests to AWS. AWS validates the
|
||||||
|
client's signature and, if the signature is valid, responds with the client's identity details. The
|
||||||
|
signature validation performed by AWS on the `sts:GetCallerIdentity` request provides the auth
|
||||||
|
method with a strong guarantee of the client's identity. The auth method compares the Amazon
|
||||||
|
Resource Name (ARN) of the client with the `BoundIAMPrincipalARNs` list to determine if the client
|
||||||
|
is permitted to login.
|
||||||
|
|
||||||
|
## Config Parameters
|
||||||
|
|
||||||
|
The following are the auth method [`Config`](/api-docs/acl/auth-methods#config)
|
||||||
|
parameters for an auth method of type `aws-iam`:
|
||||||
|
|
||||||
|
- `BoundIAMPrincipalARNs` `(array<string>: <required>)` - The list of IAM role or IAM user ARNs
|
||||||
|
which are permitted to login. A client authenticating to Consul must have an ARN that matches one
|
||||||
|
of the ARNs in this list.
|
||||||
|
- If `EnableIAMEntityDetails=false`, then bound ARNs must not contain the full path of the role
|
||||||
|
or user, and wildcards are not supported. For example,
|
||||||
|
`arn:aws:iam::123456789012:user/MyUserName` will permit the IAM user named "MyUserName" to log
|
||||||
|
in, and `arn:aws:iam::123456789012:role/MyRoleName` will permit the IAM role named "MyRoleName"
|
||||||
|
to log in.
|
||||||
|
- If `EnableIAMEntityDetails=true`, then bound ARNs with the full path must be used, such as,
|
||||||
|
`arn:aws:iam::123456789012:role/path/to/MyRoleName`. Additionally, ARNs may contain a single
|
||||||
|
trailing wildcard. For example, `arn:aws:iam::123456789012:*` will permit any role or user in
|
||||||
|
the account `123456789012` to login, while `arn:aws:iam::123456789012:role/path/to/roles/*`
|
||||||
|
will permit only roles at the path `/path/to/roles/`.
|
||||||
|
- `EnableIAMEntityDetails` `(bool: <false>)` - This enables the auth method to fetch the IAM role or
|
||||||
|
IAM user details, including tags and the full role or user path. If enabled, clients must pass the
|
||||||
|
`-aws-include-entity` option to `consul login`. Additionally, an IAM role or user attempting to
|
||||||
|
login must have an `iam:GetRole` or `iam:GetUser` permission, respectively, to retrieve itself.
|
||||||
|
This setting is required in order to fetch the full path and tags of the IAM user or role and in
|
||||||
|
order to use wildcards in the `BoundIAMPrincipalARNs`.
|
||||||
|
- `IAMEntityTags` `(array<string>: [])` - The list of tag keys retrieved from the IAM role or user
|
||||||
|
and made available to binding rules. Tags are only supported when `EnableIAMEntityDetails=true`.
|
||||||
|
By default, no tags are made available to binding rules. Each tag in the `IAMEntityTags` list can
|
||||||
|
be referenced in binding rules using `entity_tags.<tag>`. For example, if `IAMEntityTags` contains
|
||||||
|
`service-name` and if a `service-name` tag exists on the IAM role or user, then you can reference
|
||||||
|
the tag value using `entity_tags.service-name` in binding rules. If the tag is not present on the
|
||||||
|
IAM role or user, then `entity_tags.service-name` evalutes to the empty string in binding rules.
|
||||||
|
- `ServerIDHeaderValue` `(string: "")` - The value to require in the `X-Consul-IAM-ServerID` header
|
||||||
|
in login requests. If set, clients must include the `X-Consul-IAM-ServerID` header in the AWS API
|
||||||
|
requests used to login to the auth method, and the client-provided value for the header must match
|
||||||
|
this setting in order to successfully log in. If not set, no header is required or validated. This
|
||||||
|
can be used to protect against different types of replay attacks - for example, a signed request
|
||||||
|
sent to a dev server being resent to a production server. Consider setting this to the Consul
|
||||||
|
server's DNS name. When this is set, clients must set pass the `-aws-server-id-header-value`
|
||||||
|
option to the `consul login` command.
|
||||||
|
- `MaxRetries` `(integer: 0)` - The maximum number of retries to use for recoverable errors when
|
||||||
|
making AWS API requests.
|
||||||
|
- `IAMEndpoint` `(string: "")` - The URL where `iam:GetRole` and `iam:GetUser` requests are sent.
|
||||||
|
This can be used to send requests to a private endpoint or through a network proxy.
|
||||||
|
- `STSEndpoint` `(string: "")` - The URL where `sts:GetCallerIdentity` requests are sent. This can
|
||||||
|
be used to send requests to a private endpoint or through a network proxy.
|
||||||
|
- `AllowedSTSHeaderValues` `(array<string>: [])` - A list of additional allowed headers on
|
||||||
|
`sts:GetCallerIdentity` requests. In any case, a default list of headers AWS STS expects are
|
||||||
|
allowed.
|
||||||
|
|
||||||
|
### Sample
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
...other fields...
|
||||||
|
"Config": {
|
||||||
|
"BoundIAMPrincipalARNs": ["arn:aws:iam::123456789012:role/MyRoleName"],
|
||||||
|
"EnableIAMEntityDetails": true,
|
||||||
|
"IAMEntityTags": ["consul-namespace"],
|
||||||
|
"ServerIDHeaderValue": "my.consul.server.example.com",
|
||||||
|
"MaxRetries": 3,
|
||||||
|
"IAMEndpoint": "https://iam.amazonaws.com/",
|
||||||
|
"STSEndpoint": "https://sts.us-east-1.amazonaws.com/",
|
||||||
|
"AllowedSTSHeaderValues": ["X-Extra-Header"]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Trusted Identity Attributes
|
||||||
|
|
||||||
|
The authentication step returns the following trusted identity attributes for use in binding rule
|
||||||
|
selectors and bind name interpolation. All of these attributes are strings that can be interpolated
|
||||||
|
and support the following selector operations: `Equal, Not Equal, In, Not In, Matches, Not Matches`
|
||||||
|
|
||||||
|
| Attribute | Description | Requirement |
|
||||||
|
| -------------------- | ----------------------------------- | ---------------------------------------------------------------- |
|
||||||
|
| `entity_name` | Name of IAM role or user | |
|
||||||
|
| `entity_id` | Unique ID of IAM role or user | |
|
||||||
|
| `account_id` | AWS account id of IAM role or user | |
|
||||||
|
| `entity_path` | The path of the IAM role or user | `EnableIAMEntityDetails=true` |
|
||||||
|
| `entity_tags.<key>` | AWS account id of IAM role or user | `EnableIAMEntityDetails=true` and `IAMEntityTags` contains `<key>` |
|
||||||
|
|
||||||
|
## IAM Policies
|
||||||
|
|
||||||
|
When `EnableIAMEntityDetails=false`, no specific IAM policies are needed.
|
||||||
|
|
||||||
|
When `EnableIAMEntityDetails=true`, an authenticating client must provide either a signed
|
||||||
|
`iam:GetRole` or `iam:GetUser` request. This request is signed with the client's AWS credentials, so
|
||||||
|
the client must have permission to fetch the role or user, respectively.
|
||||||
|
|
||||||
|
- If the authenticating client is an IAM role, the client must have an `iam:GetRole` permission to
|
||||||
|
fetch its own role. The following shows an example of an AWS IAM Policy document which grants this
|
||||||
|
permission:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"Statement": [
|
||||||
|
{
|
||||||
|
"Action": ["iam:GetRole"],
|
||||||
|
"Effect": "Allow",
|
||||||
|
"Resource": ["arn:aws:iam::123456789012:role/MyRoleName"]
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"Version": "2012-10-17"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
- If the authenticating client is an IAM user, the client must have an `iam:GetUser` permission to
|
||||||
|
fetch its own role. The following shows an example of an AWS IAM Policy document which grants this
|
||||||
|
permission:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"Statement": [
|
||||||
|
{
|
||||||
|
"Action": ["iam:GetUser"],
|
||||||
|
"Effect": "Allow",
|
||||||
|
"Resource": ["arn:aws:iam::123456789012:user/MyUserName"]
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"Version": "2012-10-17"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Authentication Procedure
|
||||||
|
|
||||||
|
If `EnableIAMEntityDetails=false`, a client must log in with the following `consul login` command.
|
||||||
|
|
||||||
|
```shell-session
|
||||||
|
$ consul login -type aws-iam -aws-auto-bearer-token ...
|
||||||
|
```
|
||||||
|
|
||||||
|
- Format and sign an `sts:GetCallerIdentity` request
|
||||||
|
- Format these request details as JSON to form a bearer token
|
||||||
|
- Send the bearer token to the IAM auth method to authenticate
|
||||||
|
|
||||||
|
Otherwise, if `EnableIAMEntityDetails=true`, the client must log in with the following `consul login` command,
|
||||||
|
in order to include a signed `iam:GetRole` or `iam:GetUser` request in the bearer token.
|
||||||
|
|
||||||
|
```shell-session
|
||||||
|
$ consul login -type aws-iam -aws-auto-bearer-token -aws-include-entity ...
|
||||||
|
```
|
||||||
|
|
||||||
|
This command does the following:
|
||||||
|
|
||||||
|
- Make an `sts:GetCallerIdentity` request to determine its own role or user name
|
||||||
|
- Format a new `sts:GetCallerIdentity` request
|
||||||
|
- Embed a signed `iam:GetRole` or `iam:GetUser` request in the headers of the
|
||||||
|
`sts:GetCallerIdentity` request
|
||||||
|
- Sign the `sts:GetCallerIdentity` request
|
||||||
|
- Format the request details as JSON to form a bearer token
|
||||||
|
- Send the bearer token to the IAM auth method to authenticate
|
||||||
|
|
||||||
|
On the Consul servers, the IAM auth method validates a client's identity during the [Login to Auth
|
||||||
|
Method](/api-docs/acl#login-to-auth-method) API request, using the following steps:
|
||||||
|
|
||||||
|
- Decode the `sts:GetCallerIdentity` request from the bearer token
|
||||||
|
- Optionally, decode the `iam:GetRole` or `iam:GetUser` request from the bearer token,
|
||||||
|
if `EnableIAMEntityDetails=true` in the auth method configuration
|
||||||
|
- Send the `sts:GetCallerIdentity` request to AWS. This request is pre-signed by the client, so no
|
||||||
|
other credentials or permissions are needed to make this request. AWS validates the client's
|
||||||
|
signature when it receives the request. If the signature is valid, AWS returns the client's
|
||||||
|
identity in the response. This is a strong guarantee of the client's identity.
|
||||||
|
- Optionally, the auth method sends the `iam:GetRole` or `iam:GetUser` request to AWS,
|
||||||
|
if `EnableIAMEntityDetails=true` in the auth method configuration. This request is pre-signed
|
||||||
|
by the client, so no other credentials or permisssions are required to make the request. Only the
|
||||||
|
client needs the `iam:GetRole` or `iam:GetUser` permission. AWS validates the client's signature
|
||||||
|
when it receives the request. If the signature is valid, AWS returns the IAM role or user details.
|
||||||
|
This response is not a guarantee of the client's identity - any role or user name may have been
|
||||||
|
included in the request - so the auth method requires the IAM role or user to have a [unique
|
||||||
|
id](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_identifiers.html#identifiers-unique-ids)
|
||||||
|
match with the `sts:GetCallerIdentity` response.
|
||||||
|
- Finally, the auth method makes an authentication decision. If the client's IAM role or user ARN
|
||||||
|
matches one of the configured `BoundIAMPrincipalARNs`, then the client is permitted to login.
|
||||||
Loading…
Reference in new issue