aws-iam: Make setting trust on roles more clear in overview and function descriptions

[sean-beath]

Describe the bug

When running the grant_assume_role on a role with a Service Principle as the input, the role's trust policy is not updated.

Expected Behavior

I expect the role's trust policy to be updated.

Current Behavior

Nothing happens. If I change the Service Principle in the function and run a cdk diff, there is no difference in deployment suggesting the function is not doing anything.

Reproduction Steps

In Python:

        # Create new IAM role for DMS access to Redshift
        dmsRedshiftRole = iam.Role(self, "dmsRedshiftRole",
            assumed_by=iam.ServicePrincipal(
                "dms.{}.amazonaws.com".format(self.region)),
            description="IAM role to be used by DMS for access to Redshift",
            managed_policies=[iam.ManagedPolicy.from_aws_managed_policy_name(
                "service-role/AmazonDMSRedshiftS3Role")],
        )

        # Allow DMS role to be assumed by Redshift.
        dmsRedshiftRole.grant_assume_role(iam.ServicePrincipal("redshift.amazonaws.com"))

Possible Solution

No response

Additional Information/Context

No response

CDK CLI Version

2.43.1

Framework Version

No response

Node.js Version

8.5.4

OS

Mac Monterey 12.5

Language

Python

Language Version

3.9.14

Other information

No response

[peterwoodworth]

The grantAssumeRole function is a bit misleading here in that it isn't updating the trust policy of the role but rather granting the principal passed in to this action sts:AssumeRole permission. This ends up not doing anything because the principal here is a service who doesn't need to be granted this action, but rather needs to be in the trust policy.

To modify the trust policy after it's been created, you will want to access the PolicyDocument on Role.assumeRolePolicy

I think we should clarify this in the readme. I'm going to repurpose this issue as a docs issue

[sean-beath]

The grantAssumeRole function is a bit misleading here in that it isn't updating the trust policy of the role but rather granting the principal passed in to this action sts:AssumeRole permission. This ends up not doing anything because the principal here is a service who doesn't need to be granted this action, but rather needs to be in the trust policy.

To modify the trust policy after it's been created, you will want to access the PolicyDocument on Role.assumeRolePolicy

I think we should clarify this in the readme. I'm going to repurpose this issue as a docs issue

Thanks for explaining :)