Cross-Account IAM Role Assumption with MFA

Intermediate10 minTrending

Securely assume IAM roles across AWS accounts using MFA-protected temporary credentials for least-privilege access.

Prerequisites

-AWS CLI v2 installed and configured
-IAM role with trust policy allowing your account
-MFA device registered on your IAM user

Steps

Get your MFA device ARN

List the virtual MFA devices associated with your IAM user to retrieve the ARN needed for authentication.

$ aws iam list-mfa-devices --user-name your-username

You can also find your MFA ARN in the IAM console under your user's Security credentials tab.

Get a session token with MFA

Request temporary session credentials by providing your MFA device ARN and a current TOTP code from your authenticator app.

$ aws sts get-session-token --serial-number arn:aws:iam::111111111111:mfa/your-username --token-code 123456 --duration-seconds 3600

The TOTP code expires every 30 seconds. Enter the command quickly after generating a fresh code.

Assume the cross-account role

Use the MFA-authenticated session to assume a role in the target account. This returns a new set of temporary credentials scoped to that role.

$ aws sts assume-role --role-arn arn:aws:iam::222222222222:role/CrossAccountAdmin --role-session-name cross-acct-session --serial-number arn:aws:iam::111111111111:mfa/your-username --token-code 654321

Add --duration-seconds to extend the session up to the role's MaxSessionDuration (default 1 hour, max 12 hours).

Export the temporary credentials

Set the returned temporary credentials as environment variables so subsequent AWS CLI commands use the assumed role.

$ CREDS=$(aws sts assume-role --role-arn arn:aws:iam::222222222222:role/CrossAccountAdmin --role-session-name mysession --output json) export AWS_ACCESS_KEY_ID=$(echo $CREDS | jq -r .Credentials.AccessKeyId) export AWS_SECRET_ACCESS_KEY=$(echo $CREDS | jq -r .Credentials.SecretAccessKey) export AWS_SESSION_TOKEN=$(echo $CREDS | jq -r .Credentials.SessionToken)

Use jq to parse the JSON output cleanly. Install it with your package manager if not available.

Verify the assumed identity

Confirm that your CLI session is now operating under the assumed role in the target account.

$ aws sts get-caller-identity

The output should show the target account ID and the assumed role ARN, not your original user.

Unset credentials when done

Clear the temporary credentials from your environment to return to your default AWS profile.

$ unset AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN

Always unset assumed role credentials when finished to avoid accidentally running commands in the wrong account.

Full Script

full-script.sh

#!/bin/bash
# Cross-Account IAM Role Assumption with MFA
# Usage: ./assume-role.sh <target-role-arn> <mfa-arn> <mfa-code>

set -euo pipefail

TARGET_ROLE_ARN="${1:?Usage: $0 <target-role-arn> <mfa-arn> <mfa-code>}"
MFA_ARN="${2:?Provide your MFA device ARN}"
MFA_CODE="${3:?Provide your current MFA code}"
SESSION_NAME="cross-acct-$(date +%s)"

echo "Assuming role: $TARGET_ROLE_ARN"

CREDS=$(aws sts assume-role \
  --role-arn "$TARGET_ROLE_ARN" \
  --role-session-name "$SESSION_NAME" \
  --serial-number "$MFA_ARN" \
  --token-code "$MFA_CODE" \
  --duration-seconds 3600 \
  --output json)

export AWS_ACCESS_KEY_ID=$(echo "$CREDS" | jq -r '.Credentials.AccessKeyId')
export AWS_SECRET_ACCESS_KEY=$(echo "$CREDS" | jq -r '.Credentials.SecretAccessKey')
export AWS_SESSION_TOKEN=$(echo "$CREDS" | jq -r '.Credentials.SessionToken')

echo "Assumed role successfully:"
aws sts get-caller-identity

echo ""
echo "Credentials expire at: $(echo "$CREDS" | jq -r '.Credentials.Expiration')"
echo "Run 'unset AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN' to revert."

FAQ

Discussion

Loading comments...

#!/bin/bash # Cross-Account IAM Role Assumption with MFA # Usage: ./assume-role.sh <target-role-arn> <mfa-arn> <mfa-code> set -euo pipefail TARGET_ROLE_ARN="${1:?Usage: $0 <target-role-arn> <mfa-arn> <mfa-code>}" MFA_ARN="${2:?Provide your MFA device ARN}" MFA_CODE="${3:?Provide your current MFA code}" SESSION_NAME="cross-acct-$(date +%s)" echo "Assuming role: $TARGET_ROLE_ARN" CREDS=$(aws sts assume-role \ --role-arn "$TARGET_ROLE_ARN" \ --role-session-name "$SESSION_NAME" \ --serial-number "$MFA_ARN" \ --token-code "$MFA_CODE" \ --duration-seconds 3600 \ --output json) export AWS_ACCESS_KEY_ID=$(echo "$CREDS" | jq -r '.Credentials.AccessKeyId') export AWS_SECRET_ACCESS_KEY=$(echo "$CREDS" | jq -r '.Credentials.SecretAccessKey') export AWS_SESSION_TOKEN=$(echo "$CREDS" | jq -r '.Credentials.SessionToken') echo "Assumed role successfully:" aws sts get-caller-identity echo "" echo "Credentials expire at: $(echo "$CREDS" | jq -r '.Credentials.Expiration')" echo "Run 'unset AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN' to revert."