diff --git a/website/content/docs/security/acl/auth-methods/aws-iam.mdx b/website/content/docs/security/acl/auth-methods/aws-iam.mdx new file mode 100644 index 0000000000..b6422c5f12 --- /dev/null +++ b/website/content/docs/security/acl/auth-methods/aws-iam.mdx @@ -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: )` - 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: )` - 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: [])` - 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.`. 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: [])` - 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.` | AWS account id of IAM role or user | `EnableIAMEntityDetails=true` and `IAMEntityTags` contains `` | + +## 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. diff --git a/website/content/docs/security/acl/auth-methods/index.mdx b/website/content/docs/security/acl/auth-methods/index.mdx index 0c47504862..b2062fcf14 100644 --- a/website/content/docs/security/acl/auth-methods/index.mdx +++ b/website/content/docs/security/acl/auth-methods/index.mdx @@ -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+ | +| [`aws-iam`](/docs/security/acl/auth-methods/aws-iam) | 1.12.0+ | ## Operator Configuration diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index 0fa575b630..63727c41d5 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -982,6 +982,10 @@ { "title": "OIDC", "path": "security/acl/auth-methods/oidc" + }, + { + "title": "AWS IAM", + "path": "security/acl/auth-methods/aws-iam" } ] }