What is exactly "Assume" a role in AWS?

mon picture mon · Apr 29, 2018 · Viewed 14.2k times · Source

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.

Answer

Michael - sqlbot picture Michael - sqlbot · Apr 29, 2018

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.