James Galley

Web application developer

PHP, Yii, MySQL, Node.js - JavaScript, HTML, CSS & SASS, jQuery - Linux, AWS & serverless

AWS sub-Accounts and cross-Account role switching

Using AWS Sub-accounts within an Organisation is an effective way to isolate your AWS resources

By setting up cross-Account IAM roles you can provide convenient and secure access for users of other AWS Accounts

When creating new cloud-based applications on AWS, I like to use sub-accounts to isolate the account and all the resources within it. As an AWS developer this is very useful to isolate one client from another, even to separate development and production environments and for ease of billing and account management.

Using separate AWS accounts and cross-account roles also means you only need a single IAM user, that of your own IAM user on your primary account - and can use this for accessing all AWS accounts to which you have permission, rather than creating new IAM users within each AWS account. You can also force use of MFA tokens for additional security.

Steps to setup AWS sub-accounts and cross-account role access in the Console

This tuturial assumes you're setting up a new sub-account within your own Organisation, but if you skip to step 9 you can allow cross-Account Role access into existing AWS accounts too.

Phase 1: Within your primary/parent account:

  • 1. Create a new account within your Organisation, also within an Organisational Unit if you wish.
  • 2. Use a fresh email address as the root account user (Google email ‘+' aliases are good for this)
  • 3. Choose a name for the IAM role name, like AccountAccessRole
  • 4. Once the account is created, make a note of the account number.
  • 5. Log out of this account (or open another browser / Incognito window)

Phase 2: In the new account

  • 6. try to log in as the root user. You won’t be able to because at this stage you haven’t chosen a password
  • 7. Follow the reset password process and choose a password
  • 8. Log in to the account as root
  • 9. Go to IAM, find the AccountAccessRole
  • 10. Open the Trust Relationships tab, then the Edit trust relationship button
  • 11. Stick the following JSON in there
  "Version": "2012-10-17",
  "Statement": [
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::{PRIMARY ACCOUNT ID}:root"
      "Action": "sts:AssumeRole",
      "Condition": {
        "Bool": {
          "aws:MultiFactorAuthPresent": "true"

Phase 3: Back in your primary/parent account:

  • 12. Log back into your primary account again.
  • 13. We need to give our IAM user(s) permissions to assume the access role in the sub account. To do this, visit the IAM console and go to Groups.
  • 14. Create a Group with no permissions and save it
  • 15. Find the new group and go to the permissions tab. Find the 'Inline Policies' section and click 'Create group policy'
  • 16. Paste in this JSON and change the values as appropriate:
  "Version": "2012-10-17",
  "Statement": [
      "Effect": "Allow",
      "Action": [
      "Resource": "arn:aws:iam::{SUB ACCOUNT ID}:role/{SUB ACCOUNT ACCESS ROLE NAME}"
  • 17. Go to the Group 'Users' tab and add the users you wish to have access to the sub account

Now you can use the Switch Role URL that the AWS Console provides to assume the new role in the Sub Account. This URL looks something like:

https://signin.aws.amazon.com/switchrole?roleName={SUB ACCOUNT ROLE NAME}&account={SUB ACCOUNT ID}&displayName={ROLE DISPLAY NAME}

This process also applies if you have a separate AWS account that isn't part of your organisation. You can still create a role with a cross-Account Trust Relationship, and allow your primary account IAM users to assume the role in the account.

AWS cross-Account Role CLI access

To use these cross-account roles with the AWS CLI you'll need to add a different style of entry into your .aws/credentials file:

role_arn = arn:aws:iam::{SUB ACCOUNT ID}:role/{SUB ACCOUNT ROLE NAME}
mfa_serial = arn:aws:iam::{PARENT ACCOUNT ID}:mfa/{PARENT IAM USER}

To find out more about AWS development and IAM Roles, please contact me: