40
votes

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.

3

3 Answers

50
votes

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.

6
votes

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

2
votes

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.