AWS Identity and Access Management (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 and the concepts described in the main auth method documentation.

Overview

The AWS IAM auth method for Consul uses a variation on the approach used by the IAM auth method for Vault. 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. 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 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 evaluates 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

{
    "Name": "example-iam-auth",
    "Type": "aws-iam",
    "Description": "Example AWS IAM auth method",
    "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

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:

  {
    "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:

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

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

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