77

Question

What does exactly "Assume" a role mean in AWS and where is the definitive definition provided?

Background

Assuming a role is frequently used and trying to understand the definition and what it actually means.

I suppose when a principal (IAM user, application running in an EC2 instance, etc which invokes an action to access AWS resource(s)) needs to invoke an action to access an AWS resource:

  1. AWS (API? or some Authorisation runtime in AWS?) identifies the roles which the principal can be granted.

    e.g. if an EC2 user is specified to execute the assume-role API call and run an application which accesses an AWS resources in an EC2 instance to which IAM profile is attached, then:

    • All the IAM roles from the EC2 IAM profile
    • IAM roles and policies requested in the assume-role call
    • IAM roles which the EC2 user is granted

  2. AWS finds a role from the roles which has the policy (action, resource) that allows the principle to do the action on the resource.

  3. AWS switches the role of the principle to the role identified.

When the step 3 has happened, it is said "the principal has assumed the role". Is this correct?

Research

Using IAM Roles

Before an IAM user, application, or service can use a role that you created, you must grant permissions to switch to the role. You can use any policy attached to one of an IAM user's groups or to the user itself to grant the necessary permissions.

Update

Assuming an IAM role in AWS involves a temporary transfer of permissions. By assuming a role, the entity can carry out tasks and utilize resources with the authorized permissions, without making any permanent alterations to their own permissions.

Once the session token for the assumed role has expired, the entity's additional permissions will be revoked.

enter image description here

mon
  • 18,789
  • 22
  • 112
  • 205

3 Answers3

98

Assuming a role means asking Security Token Service (STS) to provide you with a set of temporary credentials -- role credentials -- that are specific to the role you want to assume. (Specifically, a new "session" with that role.)

You can optionally include a policy with this request, which will serve to limit the permissions of the temporary credentials to only a subset of what the role's policies would have allowed.

You then use these credentials to make further requests. These credentials look similar to IAM user credentials with an access-key-id and secret, but the access key begins with ASIA instead of AKIA and there's a third element, called the security token, which must be included in requests signed with the temporary credentials.

When you make requests with these temporary credentials, you have the permissions associated with the role, and not your own (if you have one) because you have taken on a new identity. CloudTrail can be used to trace the role credentials back to the user who assumed the role, but otherwise the service is unaware of who is using the credentials.

tl;dr: Assuming a role means obtaining a set of temporary credentials which are associated with the role and not with the entity that assumed the role.

AWS (API? or some Authorisation runtime in AWS?) identifies the roles which the principal can be granted.

No. You specify the role you want to assume.

When "you" are code running on an EC2 instance, and the instance has an instance role, the EC2 infrastructure actually calls assume-role on behalf of the instance, and you can fetch the temporary credentials from the instance metadata service. These credentials are accessible only from within the instance, but they are not stored on the instance.

When running a Lambda function, the Lambda infrastructure contacts STS and places your temporary credentials in environment variables. Again, these credentials are accessible to the function, without being stored inside the function.

In either case, you could call assume role with these credentials and assume a different role, but that should not be necessary in most environments.

e.g. if an EC2 user is specified to execute the assume-role API call and run an application which accesses an AWS resources in an EC2 instance to which IAM profile is attached, then:

AWS has no awareness of EC2 users. Instance roles are accessible to everything running on the instance.

All the IAM roles from the EC2 IAM profile

An instance profile can only include one role.

IAM roles and policies requested in the assume-role call

You request to assume exactly one role. You do not need to request a policy -- you only specify a policy if you want the temporary credentials to have fewer privileges than the role credentials would allow. This might be something you would do if you needed code running in an untrusted place -- such as code in a browser or an app -- to be able to sign requests with credentials.

AWS finds a role from the roles which has the policy (action, resource) that allows the principle to do the action on the resource.

No. As noted above, you ask for a specific role when you call assume-role.

AWS switches the role of the principle to the role identified.

No. You make the switch by using the temporary credentials provided.

Michael - sqlbot
  • 169,571
  • 25
  • 353
  • 427
  • so when I attach a role 'X' to the EC2 instance, the EC2 instance "assumes" that role? And when I then use the "ec2-user" to make a "aws s3 cp..." request, the "ec2-user" uses the credentials available to the EC2 instance as a result of having assumed the role X? – Sheel Pancholi Apr 14 '19 at 13:49
  • @SheelPancholi the EC2 *service* assumes the role and makes credentials available to the *instance* -- any and all OS users on the instance can access the role credentials via the Instance Metadata Service, as mentioned above. – Michael - sqlbot Apr 14 '19 at 14:59
  • Let's say I have role A and B. Would you be kind enough to tell me what are the 'advantages' of assuming the role B by A instead of just setting up required permissions on A(ones granted by B) yourself? – blahblah Apr 23 '19 at 19:59
  • 1
    @Tomasz if both roles are roles in your own account, there aren't many obvious reasons why this would be useful. – Michael - sqlbot Apr 23 '19 at 20:40
  • @programming_and_math Instead of IAM role A and IAM role B, it's more common to see IAM *user* A and IAM role B where IAM role B confers some higher permissions, for example the ability to read sensitive logs in an S3 bucket. The value of having to assume role B versus simply giving user A access to the bucket is that IAM user credentials are long-term, while IAM role/STS credentials are short-term. Exposure of the STS credentials is lower risk. You can also require MFA when assuming role B whereas it might typically be onerous for the IAM user to supply MFA for everyday usage. – jarmod Sep 12 '19 at 13:23
9

I have created the following diagram for myself to understand what is exactly assume a role in AWS. Hopefully, you will also find it helpful.

In the diagram, I put it in 3 steps:

  1. Prepare the roles (ExecutionRole and AssumedRole)
  2. Create a Lambda Function on Account A (in your case it is EC2)
  3. Execute the LambdaFunction.

The diagram uses cross-account as an example, if it is within the same account step 1.3 is not required.

Typically, you use AssumeRole within your account or for cross-account access. ... Users in the same account as the role do not need explicit permission to assume the role.
Source: https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html

enter image description here

Devs love ZenUML
  • 11,344
  • 8
  • 53
  • 67
3

When step 3 has happened, it is said: "the principal has assumed the role". Is this correct?

The steps you mentioned in assuming a role are correct.

Here the important point is the IAM role's Trust Relationship configuration where you grant each of the IAM user, application, or service to assume the role. That is where you grant the permission to assume the particular role.

This is important in many aspects, where it controls who can assume the role and it is important to provide not only least access to the role but also grant the least amount of entities who can assume the role.

Ashan
  • 18,898
  • 4
  • 47
  • 67