Docs: IAM auth method (#12779)

* Docs: IAM auth method

Co-authored-by: Karl Cardenas <kcardenas@hashicorp.com>

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

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+ <EnterpriseAlert inline /> |
+| [`aws-iam`](/docs/security/acl/auth-methods/aws-iam)       | 1.12.0+                           |
 
 ## Operator Configuration
 

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"
               }
             ]
           }