Problems switching between AWS accounts and using IAM roles

This message is extracted from a ticket originally emailed to Names and URLs have been removed where appropriate.

I’m having issues switching between accounts. I login to the security account and try to switch to my dev and stage account, but always get an error. What do I need to do?

Switching accounts can be tricky because AWS does not provide useful error messages, so it’s never clear why things aren’t working. The basic procedure is simple: you login to your “security” account and to switch to another account (e.g., the “dev”, “stage”, or “prod” account), you “assume” an IAM role in that account.

However, there are lots of gotchas, and the AWS error messages won’t help you figure out which one is tripping you up, so please go through this list carefully:

  1. You must be log into your security account as an IAM user—not the root user!
  2. Your IAM user must have MFA enabled (instructions). The IAM roles in the other accounts require it.
  3. To assume an IAM role X in account Y, your IAM user must be added to an IAM group in the security account called _account.Y-X. For example, to assume the allow-read-only-access-from-other-accounts IAM role in the dev account, your IAM user must be in the IAM group (or a similar name).

Other helpful tips:

  • You can find documentation on how to switch accounts in the cross-account-iam-roles module docs.
  • You can also find the default set of available IAM roles in the cross-account-iam-roles module docs. The most commonly used ones are allow-read-only-access-from-other-accounts and allow-full-access-from-other-accounts.
  • You will need to know the account ID of the account you want to switch to (e.g., the account ID of the dev account). You can ask an admin to find it for you (instructions). The original account IDs from when the Reference Architecture was created are also available in your walkthrough documentation in the _docs folder in infrastructure-live.