luxolus
/
open-consul
2
0
Fork 0
Code Issues 1 Pull Requests Packages Releases Wiki Activity

Docs: IAM auth method (#12779) 

* Docs: IAM auth method

Co-authored-by: Karl Cardenas <kcardenas@hashicorp.com>
This commit is contained in:
Paul Glass 2022-04-18 14:34:37 -05:00 committed by GitHub
parent 9d0b5bf8e9
commit bbb13b026c
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 215 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

210
website/content/docs/security/acl/auth-methods/aws-iam.mdx Normal file
View File

@ -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.

1
website/content/docs/security/acl/auth-methods/index.mdx
View File

@ -39,6 +39,7 @@ service mesh with minimal operator intervention.
| [`kubernetes`](/docs/security/acl/auth-methods/kubernetes) | 1.5.0+ |
| [`jwt`](/docs/security/acl/auth-methods/jwt) | 1.8.0+ |
| [`oidc`](/docs/security/acl/auth-methods/oidc) | 1.8.0+ <EnterpriseAlert inline /> |
| [`aws-iam`](/docs/security/acl/auth-methods/aws-iam) | 1.12.0+ |
## Operator Configuration

4
website/data/docs-nav-data.json
View File

@ -982,6 +982,10 @@
{
"title": "OIDC",
"path": "security/acl/auth-methods/oidc"
},
{
"title": "AWS IAM",
"path": "security/acl/auth-methods/aws-iam"
}
]
}