Understanding the Architecture

Before we dive into commands, let's understand exactly what we're building. We have twoAWSaccounts that need to work together securely.

Account A for Production wants to allow specific users from Account B to access certain resources, but with strict controls.

The beauty of cross-account roles is that Account B users don't need permanent credentials in Account A. They use their own credentials to assume a temporary role, getting short-lived tokens.

This is much more secure than creating permanent users in each account or sharing access keys. The credentials expire automatically, and you can track exactly who accessed what and when.

We'll see exactly how the Security Token Service (STS) orchestrates this dance between accounts.

Setting Up the Environment

Let's start by setting up ourAWSCLI environment properly. This is crucial because we'll be working with multiple accounts, and you need to be absolutely sure which account context you're operating in.

The first command,AWSsts get-caller-identity, is your best friend when working with multiple accounts. It tells you exactly which credentials you're using right now.

When you run this, you'll get back three critical pieces of information: your User ID (or Role ID), your Account number, and your ARN. This confirms you're working in the right account with the right permissions.

TheAWSconfigure list command shows you exactly which credential source is being used - is it from ~/.aws/credentials, environment variables, or an IAM role? This is essential for troubleshooting.

Creating the Trust Policy Document

Now we're creating the heart of cross-account access - the trust policy. This JSON document is like a whitelist that says "these specific entities from these specific accounts are allowed to assume this role."

I'm using a here-document (EOF syntax) to create the JSON file cleanly. This is much better than trying to escape quotes in a command line.

The Principal "arn:aws:iam::account B:user/DevUser" is very specific - it allows only the user named "DevUser" from account account B. You could also use "arn:aws:iam::account B:root" to allow any user from that account, but that's less secure.

The ExternalId condition is crucial for security - it prevents the "confused deputy" problem where a malicious user might trick a service into performing actions on the wrong account.

Creating the Cross-Account Role

Now we're actually creating the IAM role using the trust policy we just defined. Let me break down every single parameter in thisAWSiam create-role command.

When this command succeeds,AWSreturns a complete Role object with the ARN, creation date, and the trust policy you just attached. The ARN is what you'll use to reference this role from other accounts.

If you get an error here, it's usually because: 1) You don't have iam:CreateRole permission, 2) A role with that name already exists, or 3) There's a JSON syntax error in your trust policy.

The role exists now, but it has no permissions yet - it's like creating an empty security badge. We'll add permissions next.

Adding Permissions to the Role

A role without permissions is useless, so now we're going to attach a permissions policy. I'm showing you two approaches - using anAWSmanaged policy and creating a custom policy.

AWS managed policies like "ReadOnlyAccess" are maintained byAWSand automatically updated when new services are added. They're great for common use cases and followAWSbest practices.

For custom policies, we use create-policy first, then attach-role-policy. The custom policy I'm showing allows S3 access but only to buckets with "dev" in the name - this is principle of least privilege in action.

When you attach a policy,AWSdoesn't return any output on success - silence is golden here. You can verify the attachment worked by using get-role or list-attached-role-policies.

Setting Up the Trusted Account

Now we switch contexts to Account B. This is where the user who will assume the cross-account role lives.

The user in Account B needs specific permissions to assume roles in other accounts. The sts:AssumeRole permission is what allows them to call the AssumeRole API.

The policy I'm showing allows assuming any role in Account A, but you could be more restrictive and specify exact role ARNs. Notice the condition requiring an ExternalId - this must match what's in the trust policy.

Creating the user and attaching this policy gives them the capability to assume cross-account roles, but they still need to be explicitly allowed by each role's trust policy.

The AssumeRole Process

This is the moment of truth - where Account B's user actually assumes the role in Account A. TheAWSsts assume-role command is the bridge between accounts.

The response contains temporary credentials: AccessKeyId, SecretAccessKey, and SessionToken. These credentials are only valid for the specified duration and only have the permissions granted to the assumed role.

The session name is crucial for auditing - it appears in all CloudTrail logs, so use meaningful names like "DevUser Deployment Task followed by date rather than generic names.

If this fails, check: 1) Trust policy allows your user, 2) ExternalId matches, 3) You have sts:AssumeRole permission, 4) The role exists in the target account.

Using the Temporary Credentials

Once you have the temporary credentials, you need to configure yourAWSCLI to use them. There are several ways to do this, and I'll show you the most practical approaches.

The export commands set environment variables that theAWSCLI automatically picks up. This is temporary - they only last for your current shell session.

Alternatively, you can useAWSconfigure set to store the credentials in a named profile. This is more permanent and allows you to switch between multiple assumed roles easily.

TheAWSsts get-caller-identity command now shows you're using the assumed role - your ARN will show the role name and session name. This confirms the role assumption worked.

Now anyAWSCLI commands you run will use the permissions of the assumed role, not your original user permissions.

Advanced Trust Policy Features

Let's explore advanced trust policy features that give you granular control over when and how roles can be assumed.

Time-based conditions are incredibly powerful for temporary access scenarios. You can create contractor roles that only work during specific time periods or maintenance windows that only activate during scheduled maintenance times.

MFA requirements are essential for privileged roles. The AWS MultiFactor AuthPresent condition ensures the user provided a second factor, and AWS MultiFactorAuthAge ensures it was recent.

IP address restrictions are great for hybrid environments where you want to ensure access only comes from your corporate network or specific VPNs.

When you have multiple conditions, they all must be true (AND logic). Use multiple statements for or logic.

Automation and Scripting

In real-world scenarios, you'll want to automate the role assumption process. Let me show you a practical script that handles the entire workflow.

This script demonstrates several best practices: error handling, credential validation, and automatic session cleanup.

The jq tool is invaluable for parsing JSON responses fromAWSCLI. The -r flag outputs raw strings (without quotes), making them suitable for shell variables.

Always validate that the role assumption worked before proceeding with other operations. A simpleAWSsts get-caller-identity check can prevent confusing errors later.

Consider adding logging to your automation scripts - knowing when roles were assumed and by whom is crucial for security auditing.

Monitoring and Auditing

Cross-account access creates additional security considerations, so monitoring and auditing become even more critical.

CloudTrail logs every AssumeRole call with details about who assumed what role, when, and from where. The sourceIPAddress field is particularly valuable for detecting anomalous access patterns.

TheAWSlogs filter-log-events command lets you search CloudTrail logs programmatically. You can create automated alerts for unusual patterns like role assumptions from unexpected IP addresses or outside business hours.

Access Analyzer can help you identify unused cross-account access - if a role hasn't been assumed in 90 days, maybe it's time to review whether it's still needed.

Set up CloudWatch alarms for failed AssumeRole attempts - repeated failures might indicate an attack or misconfiguration.

Troubleshooting Common Issues

Let's walk through the most common issues you'll encounter with cross-account access and how to debug them systematically.

The first step in any troubleshooting is alwaysAWSsts get-caller-identity to confirm which account and user you're operating as. Many issues stem from being in the wrong account context.

TheAWSiam simulate-principal-policy command is incredibly valuable for testing permissions without actually performing actions. You can test whether a specific user can assume a specific role.

CloudTrail is your forensic tool - look for AssumeRole events to see exactly what happened and why it failed. The errorCode and errorMessage fields provide specific failure reasons.

Remember that IAM is eventually consistent - if you just created a role or policy, wait a few seconds before testing. This catches many mysterious "access denied" errors.

Security Best Practices

Cross-account access amplifies both the benefits and risks of yourAWSsecurity posture, so following best practices is crucial.

External IDs are your first line of defense against confused deputy attacks. Always use them for third-party integrations, and make them unique and unpredictable.

Principle of least privilege is even more important in cross-account scenarios. Start with minimal permissions and add only what's needed. The ReadOnlyAccess policy is often sufficient for initial integrations.

Consider usingAWSOrganizations SCPs (Service Control Policies) to add guardrails around cross-account access. You can prevent certain roles from being created or assumed.

Regular access reviews should include cross-account relationships. Use Access Analyzer findings to identify overly permissive trusts or unused access paths.

Real-World Implementation Guide

Let's wrap up with a comprehensive implementation checklist that you can use in production environments.

Start with a pilot implementation between non-production accounts to validate your approach. This lets you work out the kinks without risking production systems.

Always have a rollback plan. Cross-account access can be removed quickly by updating trust policies, but make sure you understand the impact on dependent systems.

Document your external IDs and session naming conventions. Future troubleshooting will be much easier if you have consistent, meaningful naming patterns.

Consider implementing automated credential rotation for long-term cross-account relationships. While assumed role credentials are temporary, the base credentials used to assume them should be rotated regularly.

Thank you for following this comprehensive guide! You now have all the tools and knowledge needed to implement secure, auditable cross-account access in AWS.