The following examples show how to call GetSessionToken and AssumeRole operations and pass MFA authentication parameters. No permissions are required to call GetSessionToken, but you must have a policy that allows you to call AssumeRole. The credentials returned are then used to list all S3 buckets in the account.
The following example shows how to call GetSessionToken and pass MFA authentication information. The temporary security credentials returned by the GetSessionToken operation are then used to list all S3 buckets in the account.
The policy attached to the user who runs this code (or to a group that the user is in) provides the permissions for the returned temporary credentials. For this example code, the policy must grant the user permission to request the Amazon S3 ListBuckets operation.
The following code example shows how to get a session token with AWS STS and use it to perform a service action that requires an MFA token.
SDK for Python (Boto3)
There's more on GitHub. Find the complete example and learn how to set up and run in the AWS Code Examples Repository.
Get a session token by passing an MFA token and use it to list Amazon S3 buckets for the account.
def list_buckets_with_session_token_with_mfa(mfa_serial_number, mfa_totp, sts_client):
"""
Gets a session token with MFA credentials and uses the temporary session
credentials to list Amazon S3 buckets.
Requires an MFA device serial number and token.
:param mfa_serial_number: The serial number of the MFA device. For a virtual MFA
device, this is an Amazon Resource Name (ARN).
:param mfa_totp: A time-based, one-time password issued by the MFA device.
:param sts_client: A Boto3 STS instance that has permission to assume the role.
"""
if mfa_serial_number is not None:
response = sts_client.get_session_token(
SerialNumber=mfa_serial_number, TokenCode=mfa_totp)
else:
response = sts_client.get_session_token()
temp_credentials = response['Credentials']
s3_resource = boto3.resource(
's3',
aws_access_key_id=temp_credentials['AccessKeyId'],
aws_secret_access_key=temp_credentials['SecretAccessKey'],
aws_session_token=temp_credentials['SessionToken'])
print(f"Buckets for the account:")
for bucket in s3_resource.buckets.all():
print(bucket.name)
- For API details, see GetSessionToken in AWS SDK for Python (Boto3) API Reference.
The following examples show how to call AssumeRole and pass MFA authentication information. The temporary security credentials returned by AssumeRole are then used to list all Amazon S3 buckets in the account.
For more information about this scenario, see Scenario: MFA protection for cross-account delegation.
The following code examples show how to assume a role with AWS STS.
AWS SDK for .NET
There's more on GitHub. Find the complete example and learn how to set up and run in the AWS Code Examples Repository.
using Amazon;
using Amazon.SecurityToken;
using Amazon.SecurityToken.Model;
using System;
using System.Threading.Tasks;
namespace AssumeRoleExample
{
class AssumeRole
{
/// <summary>
/// This example shows how to use the AWS Security Token
/// Service (AWS STS) to assume an IAM role.
///
/// NOTE: It is important that the role that will be assumed has a
/// trust relationship with the account that will assume the role.
///
/// Before you run the example, you need to create the role you want to
/// assume and have it trust the IAM account that will assume that role.
///
/// See https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create.html
/// for help in working with roles.
/// </summary>
private static readonly RegionEndpoint REGION = RegionEndpoint.USWest2;
static async Task Main()
{
// Create the SecurityToken client and then display the identity of the
// default user.
var roleArnToAssume = "arn:aws:iam::123456789012:role/testAssumeRole";
var client = new Amazon.SecurityToken.AmazonSecurityTokenServiceClient(REGION);
// Get and display the information about the identity of the default user.
var callerIdRequest = new GetCallerIdentityRequest();
var caller = await client.GetCallerIdentityAsync(callerIdRequest);
Console.WriteLine($"Original Caller: {caller.Arn}");
// Create the request to use with the AssumeRoleAsync call.
var assumeRoleReq = new AssumeRoleRequest()
{
DurationSeconds = 1600,
RoleSessionName = "Session1",
RoleArn = roleArnToAssume
};
var assumeRoleRes = await client.AssumeRoleAsync(assumeRoleReq);
// Now create a new client based on the credentials of the caller assuming the role.
var client2 = new AmazonSecurityTokenServiceClient(credentials: assumeRoleRes.Credentials);
// Get and display information about the caller that has assumed the defined role.
var caller2 = await client2.GetCallerIdentityAsync(callerIdRequest);
Console.WriteLine($"AssumedRole Caller: {caller2.Arn}");
}
}
}
- For API details, see AssumeRole in AWS SDK for .NET API Reference.
SDK for C++
There's more on GitHub. Find the complete example and learn how to set up and run in the AWS Code Examples Repository.
bool AwsDoc::STS::assumeRole(const Aws::String &roleArn,
const Aws::String &roleSessionName,
const Aws::String &externalId,
Aws::Auth::AWSCredentials &credentials,
const Aws::Client::ClientConfiguration &clientConfig) {
Aws::STS::STSClient sts(clientConfig);
Aws::STS::Model::AssumeRoleRequest sts_req;
sts_req.SetRoleArn(roleArn);
sts_req.SetRoleSessionName(roleSessionName);
sts_req.SetExternalId(externalId);
const Aws::STS::Model::AssumeRoleOutcome outcome = sts.AssumeRole(sts_req);
if (!outcome.IsSuccess()) {
std::cerr << "Error assuming IAM role. " <<
outcome.GetError().GetMessage() << std::endl;
}
else {
std::cout << "Credentials successfully retrieved." << std::endl;
const Aws::STS::Model::AssumeRoleResult result = outcome.GetResult();
const Aws::STS::Model::Credentials &temp_credentials = result.GetCredentials();
// Store temporary credentials in return argument.
// Note: The credentials object returned by assumeRole differs
// from the AWSCredentials object used in most situations.
credentials.SetAWSAccessKeyId(temp_credentials.GetAccessKeyId());
credentials.SetAWSSecretKey(temp_credentials.GetSecretAccessKey());
credentials.SetSessionToken(temp_credentials.GetSessionToken());
}
return outcome.IsSuccess();
}
- For API details, see AssumeRole in AWS SDK for C++ API Reference.
SDK for Java 2.x
There's more on GitHub. Find the complete example and learn how to set up and run in the AWS Code Examples Repository.
public static void assumeGivenRole(StsClient stsClient, String roleArn, String roleSessionName) {
try {
AssumeRoleRequest roleRequest = AssumeRoleRequest.builder()
.roleArn(roleArn)
.roleSessionName(roleSessionName)
.build();
AssumeRoleResponse roleResponse = stsClient.assumeRole(roleRequest);
Credentials myCreds = roleResponse.credentials();
// Display the time when the temp creds expire.
Instant exTime = myCreds.expiration();
String tokenInfo = myCreds.sessionToken();
// Convert the Instant to readable date.
DateTimeFormatter formatter =
DateTimeFormatter.ofLocalizedDateTime( FormatStyle.SHORT )
.withLocale( Locale.US)
.withZone( ZoneId.systemDefault() );
formatter.format( exTime );
System.out.println("The token "+tokenInfo + " expires on " + exTime );
} catch (StsException e) {
System.err.println(e.getMessage());
System.exit(1);
}
}
- For API details, see AssumeRole in AWS SDK for Java 2.x API Reference.
SDK for JavaScript (v3)
There's more on GitHub. Find the complete example and learn how to set up and run in the AWS Code Examples Repository.
Create the client.
import { STSClient } from "@aws-sdk/client-sts";
// Set the AWS Region.
const REGION = "us-east-1";
// Create an AWS STS service client object.
export const client = new STSClient({ region: REGION });
Assume the IAM role.
import { AssumeRoleCommand } from "@aws-sdk/client-sts";
import { client } from "../libs/client.js";
export const main = async () => {
try {
// Returns a set of temporary security credentials that you can use to
// access Amazon Web Services resources that you might not normally
// have access to.
const command = new AssumeRoleCommand({
// The Amazon Resource Name (ARN) of the role to assume.
RoleArn: "ROLE_ARN",
// An identifier for the assumed role session.
RoleSessionName: "session1",
// The duration, in seconds, of the role session. The value specified
// can range from 900 seconds (15 minutes) up to the maximum session
// duration set for the role.
DurationSeconds: 900,
});
const response = await client.send(command);
console.log(response);
} catch (err) {
console.error(err);
}
};
- For API details, see AssumeRole in AWS SDK for JavaScript API Reference.
SDK for JavaScript (v2)
There's more on GitHub. Find the complete example and learn how to set up and run in the AWS Code Examples Repository.
// Load the AWS SDK for Node.js
const AWS = require('aws-sdk');
// Set the region
AWS.config.update({region: 'REGION'});
var roleToAssume = {RoleArn: 'arn:aws:iam::123456789012:role/RoleName',
RoleSessionName: 'session1',
DurationSeconds: 900,};
var roleCreds;
// Create the STS service object
var sts = new AWS.STS({apiVersion: '2011-06-15'});
//Assume Role
sts.assumeRole(roleToAssume, function(err, data) {
if (err) console.log(err, err.stack);
else{
roleCreds = {accessKeyId: data.Credentials.AccessKeyId,
secretAccessKey: data.Credentials.SecretAccessKey,
sessionToken: data.Credentials.SessionToken};
stsGetCallerIdentity(roleCreds);
}
});
//Get Arn of current identity
function stsGetCallerIdentity(creds) {
var stsParams = {credentials: creds };
// Create STS service object
var sts = new AWS.STS(stsParams);
sts.getCallerIdentity({}, function(err, data) {
if (err) {
console.log(err, err.stack);
}
else {
console.log(data.Arn);
}
});
}
- For API details, see AssumeRole in AWS SDK for JavaScript API Reference.
SDK for Python (Boto3)
There's more on GitHub. Find the complete example and learn how to set up and run in the AWS Code Examples Repository.
Assume an IAM role that requires an MFA token and use temporary credentials to list Amazon S3 buckets for the account.
def list_buckets_from_assumed_role_with_mfa(
assume_role_arn, session_name, mfa_serial_number, mfa_totp, sts_client):
"""
Assumes a role from another account and uses the temporary credentials from
that role to list the Amazon S3 buckets that are owned by the other account.
Requires an MFA device serial number and token.
The assumed role must grant permission to list the buckets in the other account.
:param assume_role_arn: The Amazon Resource Name (ARN) of the role that
grants access to list the other account's buckets.
:param session_name: The name of the STS session.
:param mfa_serial_number: The serial number of the MFA device. For a virtual MFA
device, this is an ARN.
:param mfa_totp: A time-based, one-time password issued by the MFA device.
:param sts_client: A Boto3 STS instance that has permission to assume the role.
"""
response = sts_client.assume_role(
RoleArn=assume_role_arn,
RoleSessionName=session_name,
SerialNumber=mfa_serial_number,
TokenCode=mfa_totp)
temp_credentials = response['Credentials']
print(f"Assumed role {assume_role_arn} and got temporary credentials.")
s3_resource = boto3.resource(
's3',
aws_access_key_id=temp_credentials['AccessKeyId'],
aws_secret_access_key=temp_credentials['SecretAccessKey'],
aws_session_token=temp_credentials['SessionToken'])
print(f"Listing buckets for the assumed role's account:")
for bucket in s3_resource.buckets.all():
print(bucket.name)
- For API details, see AssumeRole in AWS SDK for Python (Boto3) API Reference.
SDK for Ruby
There's more on GitHub. Find the complete example and learn how to set up and run in the AWS Code Examples Repository.
# Creates an AWS Security Token Service (AWS STS) client with specified credentials.
# This is separated into a factory function so that it can be mocked for unit testing.
#
# @param key_id [String] The ID of the access key used by the STS client.
# @param key_secret [String] The secret part of the access key used by the STS client.
def create_sts_client(key_id, key_secret)
Aws::STS::Client.new(access_key_id: key_id, secret_access_key: key_secret)
end
# Gets temporary credentials that can be used to assume a role.
#
# @param role_arn [String] The ARN of the role that is assumed when these credentials
# are used.
# @param sts_client [AWS::STS::Client] An AWS STS client.
# @return [Aws::AssumeRoleCredentials] The credentials that can be used to assume the role.
def assume_role(role_arn, sts_client)
credentials = Aws::AssumeRoleCredentials.new(
client: sts_client,
role_arn: role_arn,
role_session_name: "create-use-assume-role-scenario"
)
puts("Assumed role '#{role_arn}', got temporary credentials.")
credentials
end
- For API details, see AssumeRole in AWS SDK for Ruby API Reference.
SDK for Rust
This documentation is for an SDK in preview release. The SDK is subject to change and should not be used in production.
There's more on GitHub. Find the complete example and learn how to set up and run in the AWS Code Examples Repository.
async fn assume_role(
config: &SdkConfig,
region: Region,
role_name: String,
session_name: Option<String>,
) -> Result<(), Error> {
match config.credentials_provider() {
Some(credential) => {
let provider = aws_config::sts::AssumeRoleProvider::builder(role_name)
.region(region)
.session_name(session_name.unwrap_or_else(|| String::from("rust-assume-role")))
.build(credential.clone());
let local_config = aws_config::from_env()
.credentials_provider(provider)
.load()
.await;
let client = Client::new(&local_config);
let req = client.get_caller_identity();
let resp = req.send().await;
match resp {
Ok(e) => {
println!("UserID : {}", e.user_id().unwrap_or_default());
println!("Account: {}", e.account().unwrap_or_default());
println!("Arn : {}", e.arn().unwrap_or_default());
}
Err(e) => println!("{:?}", e),
}
}
None => {
println!("No config provided");
}
}
Ok(())
}
- For API details, see AssumeRole in AWS SDK for Rust API reference.
SDK for Swift
This is prerelease documentation for an SDK in preview release. It is subject to change.
There's more on GitHub. Find the complete example and learn how to set up and run in the AWS Code Examples Repository.
public func assumeRole(role: IAMClientTypes.Role, sessionName: String)
async throws -> STSClientTypes.Credentials {
let input = AssumeRoleInput(
roleArn: role.arn,
roleSessionName: sessionName
)
do {
let output = try await stsClient.assumeRole(input: input)
guard let credentials = output.credentials else {
throw ServiceHandlerError.authError
}
return credentials
} catch {
throw error
}
}
- For API details, see AssumeRole in AWS SDK for Swift API reference.