AWS Identity and Access Management
User Guide

Switching to an IAM Role (API)

A role specifies a set of permissions that you can use to access AWS resources that you need. In that sense, it is similar to a user in AWS Identity and Access Management (IAM). An application assumes a role to receive permissions to carry out required tasks and interact with AWS resources. The role can be in your own account or any other AWS account. For more information about roles, their benefits, and how to create and configure them, see IAM Roles, and Creating IAM Roles.

This section describes how to switch roles from within code that uses the AWS API.

Note that all access keys and tokens are examples only and cannot be used as shown. Replace with the appropriate values from your live environment.

To assume a role, an application calls the AWS STS AssumeRole API and passes the ARN of the role to use. The AssumeRole API returns a set of temporary security credentials that you can use in subsequent AWS API calls to access resources in the account that owns the role. The temporary credentials have whatever permissions are defined in the role's access policy. The call to AssumeRole can optionally pass a supplemental policy that can further restrict (filter) the permissions of the temporary security credentials that the AssumeRole API returns. You can call AssumeRole only IAM user or IAM role credentials. You cannot call AssumeRole with the credentials of the AWS account root user.


For security purposes, you can use AWS CloudTrail to audit the use of roles in the account. The call to AssumeRole must include a role session name between 2 and 64 characters long that can include letters, numbers, and the =,.@- characters. The role session name is used in CloudTrail logs to identify actions performed by the temporary security credentials. For more information, see CloudTrail Event Reference in the AWS CloudTrail User Guide.

The following example in Python using the Boto3 interface to AWS (AWS SDK for Python (Boto) V3) shows how to call AssumeRole and how to use the temporary security credentials returned by AssumeRole to list all Amazon S3 buckets in the account that owns the role.

Copy to clipboard
import boto3 # The calls to AWS STS AssumeRole must be signed with the access key ID # and secret access key of an existing IAM user or by using existing temporary # credentials such as those from antoher role. (You cannot call AssumeRole # with the access key for the root account.) The credentials can be in # environment variables or in a configuration file and will be discovered # automatically by the boto3.client() function. For more information, see the # Python SDK documentation: # # create an STS client object that represents a live connection to the # STS service sts_client = boto3.client('sts') # Call the assume_role method of the STSConnection object and pass the role # ARN and a role session name. assumedRoleObject = sts_client.assume_role( RoleArn="arn:aws:iam::account-of-role-to-assume:role/name-of-role", RoleSessionName="AssumeRoleSession1" ) # From the response that contains the assumed role, get the temporary # credentials that can be used to make subsequent API calls credentials = assumedRoleObject['Credentials'] # Use the temporary credentials that AssumeRole returns to make a # connection to Amazon S3 s3_resource = boto3.resource( 's3', aws_access_key_id = credentials['AccessKeyId'], aws_secret_access_key = credentials['SecretAccessKey'], aws_session_token = credentials['SessionToken'], ) # Use the Amazon S3 resource object that is now configured with the # credentials to access your S3 buckets. for bucket in s3_resource.buckets.all(): print(