Manage Multiple AWS Accounts with Role Switching

Manage Multiple AWS Accounts with Role Switching

April 30, 2018 1 By Eric Shanks

A pretty common question that comes up is how to manage multiple accounts within AWS from a user perspective. Multi-Account setups are common to provide control plane separation between Production, Development, Billing and Shared Services accounts but do you need to setup Federation with each of these accounts or create an IAM user in each one? That makes those accounts kind of cumbersome to manage and the more users we have the more chance one of them could get hacked.

First, lets look at to different patterns that can be used to authenticate with multiple AWS Accounts. The first method we have either an IAM User (Username and Password stored in the AWS Account IAM Service) or a Federated User (Username and Password stored in a local Identity Provider) that can login to any of the accounts in the AWS environment. For this authentication pattern, Identity Federation would need to be setup for every account with the Identity Provider, or an IAM User would need to be created for each account which means many logins to keep track of and manage. The overall pattern would look something like this:



In the second method, we’re using a gateway account to handle all of our authentication into the AWS environment meaning that a single login is required. Federated users or IAM Users would login to this gateway account first and from there would use the Switch Role feature to assume a role in another account. This pattern would look similar to this:


If you prefer the first option, then you have what you need and just need to setup your authentication mechanisms with each account. If you prefer option two where you authenticate against a single gateway account and role switch to your desired destination, then we should look deeper about how that role switching takes place.


Role Switching in the AWS Console

To role switch in the AWS Web console, you would first login to your gateway account. This is usually a shared services or security related account where centralized management of users, groups and roles can take place. From there you’ll go to the login dropdown at the top of the console an select the option “Switch Role”. The Switch Role window will pop open and ask for an account number and a role to assume when you switch accounts. You can then give it a display name for the console and a color which I’ve found really valuable but your mileage may vary. When you’re done click switch role and you’ll be switched to your destination account. You can go back to your gateway account at any time by going back to the login dropdown and clicking the “back to [username]” and you’ll role switch back to the original login.


Once you’ve switched roles once, the browser will cache your last five roles that have been switched and from then on, you don’t need to re-enter your account number and role. If you navigate to the login dropdown and select one of your cached roles, you’ll be able to more quickly switch between accounts going forward, until you delete your browser cache or switch roles to more than five different accounts.

Switch Roles in the AWS CLI

First, lets look at switching roles if we login to the AWS CLI as an IAM User. Once you setup your AWS CLI you’ll have your credentials stored in the .aws/credentials file which includes your access keys and secret keys to log you into your accounts. If you execute a command you’ll receive responses related to the default account that was setup.

You can also modify the .aws/config file to include any roles that you might want to role switch into. To do this, you would give the profile a name and then specify the role_arn of the role that you’d be switching into as well as the profile that would be allowed to switch from.

When it’s all done, you can run the same commands you normally would, but specify the –profile [profile name] command and the cli will run the command in the correct account. Below is an example of two identidal commands that are in different aws accounts specified by the profile switch.

If you’re company requires you to federate, this gets slightly more difficult because now you need to login to your federation server and receive a token, which is passed to AWS for authentication. There is a great tutorial on the AWS blog on how to use python to do this with ADFS 1.0, 2.0, and 3.0 found here: and if you need to do this, I urge you to read this thoroughly. When you’ve implemented the scripts, you’ll have a similar login process but the first federated login will update your .aws/credentials file to use your temporary token for login and then once thats complete, you can role switch like we did before.


Setup Role Switching

For cross account role switching to work properly, you must setup some configurations in both the source account (the account you’ll be logging into and switching from) and the destination account (the account that you’ll role switch into).

First we’ll start with the destination account or the account that you’ll role switch into. The goal here is to create a role that other accounts have permissions to assume. In this example I’m creating a role named “Admins” and I’m going to allow my source account access to assume that role.

Open the IAM console and go to Roles. Click the “Create role” button.

Under the type of trusted identity select the “Another AWS account” option. From there you’ll need to enter in the source account number that will have access to assume this role in this destination account. You could also require MFA or an external ID but that is not covered in this blog post. External ID cannot currently be used through the console so be aware of that. Click the “Next:Permissions” button.

On the the attach permissions policies screen, select what permissions this role will have on the account. I’m assuming my administrators are using this account so I’ve given full access. Click the “Next:Review” button.

On the review screen, give the role a name. and complete the setup. Be sure to remember the name of this role as it will be needed in a future step.


Next we’ll move to the source account or the gateway account that logins are funneled through. So login to the source account and go to the IAM console again. The main task here is that you must add a permission to the users who will have access to the destination accounts. This is done by creating a new policy allowing the assume role permission on the user, group or role that is being provided access.

Create a new policy and add the JSON code from the screenshot. The important part to edit here is the destination account name, and the role that was created.

The JSON starter is here so you can copy and paste to get started.

The next step would be to attach this policy to a user (less preferred) or group (more preferred) that will have access to assume the role in the destination account. I prefer to create a group for each of my accounts and attach a policy specifically to that account as seen in the screenshots below.



There are several ways that your authentication mechanisms can be architected and you should consider the options from both a security and manageability perspective. Is it easier to manage multiple federated accounts or a single federated account that allows you to switch from another role? Is it more difficult to get new IAM roles created for new accounts or re-setup federation when you onboard a new account? Is it too much hassle to login and then role switch before doing work? These are all good questions that should be considered before building out your environment on AWS.