diff --git a/builtin/credential/aws/backend.go b/builtin/credential/aws/backend.go index 809beaefe4..1d4926819a 100644 --- a/builtin/credential/aws/backend.go +++ b/builtin/credential/aws/backend.go @@ -286,13 +286,22 @@ func getAnyRegionForAwsPartition(partitionId string) *endpoints.Region { } const backendHelp = ` -aws-ec2 auth method takes in PKCS#7 signature of an AWS EC2 instance and a client -created nonce to authenticates the EC2 instance with Vault. +The aws auth method uses either AWS IAM credentials or AWS-signed EC2 metadata +to authenticate clients, which are IAM principals or EC2 instances. Authentication is backed by a preconfigured role in the backend. The role represents the authorization of resources by containing Vault's policies. Role can be created using 'role/' endpoint. +Authentication of IAM principals, either IAM users or roles, is done using a +specifically signed AWS API request using clients' AWS IAM credentials. IAM +principals can then be assigned to roles within Vault. This is known as the +"iam" auth method. + +Authentication of EC2 instances is done using either a signed PKCS#7 document +or a detached RSA signature of an AWS EC2 instance's identity document along +with a client-created nonce. This is known as the "ec2" auth method. + If there is need to further restrict the capabilities of the role on the instance that is using the role, 'role_tag' option can be enabled on the role, and a tag can be generated using 'role//tag' endpoint. This tag represents the diff --git a/builtin/credential/aws/path_role.go b/builtin/credential/aws/path_role.go index 6ad33209d3..fe7d76c2e2 100644 --- a/builtin/credential/aws/path_role.go +++ b/builtin/credential/aws/path_role.go @@ -891,12 +891,12 @@ Create a role and associate policies to it. const pathRoleDesc = ` A precondition for login is that a role should be created in the backend. -The login endpoint takes in the role name against which the instance -should be validated. After authenticating the instance, the authorization -for the instance to access Vault's resources is determined by the policies -that are associated to the role though this endpoint. +The login endpoint takes in the role name against which the client +should be validated. After authenticating the client, the authorization +to access Vault's resources is determined by the policies that are +associated to the role though this endpoint. -When the instances require only a subset of policies on the role, then +When an EC2 instance requires only a subset of policies on the role, then 'role_tag' option on the role can be enabled to create a role tag via the endpoint 'role//tag'. This tag then needs to be applied on the instance before it attempts a login. The policies on the tag should be a