Terraform - assume_role_policy - similar but slightly different than standard IAM policy

Question

This page https://www.terraform.io/docs/providers/aws/r/iam_role.html mentions:

NOTE: This assume_role_policy is very similar but slightly different than just a standard IAM policy and cannot use an aws_iam_policy resource. It can however, use an aws_iam_policy_document data source, see example below for how this could work.

Is there any reason why the assume_role_policy is different from the standard IAM policy?

Any why?

Answer 1

An assume role policy is a special policy associated with a role that controls which principals (users, other roles, AWS services, etc) can "assume" the role. Assuming a role means generating temporary credentials to act with the privileges granted by the access policies associated with that role.

An assume role policy differs from a normal policy in the following ways:

• It is a property of the role itself, rather than a separate object associated with the role. There is only one assume role policy per role.
• The only Action values that have any meaning in an assume role policy are sts:AssumeRole and some other variants on it (at the time of writing, sts:AssumeRoleWithSAML and sts:AssumeRoleWithWebIdentity). Those are the API operations used to obtain the temporary credentials for the role.

It is the first of these differences that creates the difference mentioned in the Terraform documentation: since a role has exactly one IAM policy and it is declared directly as part of the role, its policy document must be provided as an attribute of the aws_iam_role resource. The aws_iam_policy_document data source is just a simple transform of its input into an IAM JSON policy document format, so it can be used to generate the value of the assume_role_policy attribute.

When an AWS service makes calls to another API service on your behalf, it is internally obtaining temporary credentials for the role you designate, which it can then use to make calls to other service APIs. It is for this reason that it is necessary to create roles and assign them to services such as AWS Lambda, EC2 (via instance profiles), Kinesis Firehose, etc.

---

I wrote a more elaborate description of this as part of an answer to another question, which gives some examples of practical IAM roles, assume role policies and regular policies.