AWS Identity and Access Management
User Guide

Example Scenario Using Separate Development and Production Accounts

Imagine that your organization has multiple AWS accounts to isolate a development environment from a production environment. Users in the development account might occasionally need to access resources in the production account, such as when you are promoting an update from the development environment to the production environment. Although you could create separate identities (and passwords) for users who work in both accounts, managing credentials for multiple accounts makes identity management difficult. In the following figure, all users are managed in the development account, but some developers require limited access to the production account. The development account has two groups: Testers and Developers, and each group has its own policy.

        Use a role to delegate permissions to a user in a different account
  1. In the production account an administrator uses IAM to create the UpdateAPP role in that account. In the role, the administrator defines a trust policy that specifies the development account as a Principal, meaning that authorized users from the development account can use the UpdateAPP role. The administrator also defines a permissions policy for the role that specifies that users of the role have read and write permissions to the Amazon Simple Storage Service (S3) bucket named productionapp.

    The administrator then shares the account number and name of the role (for AWS console users) or the Amazon Resource Name (ARN) (for AWS CLI, Tools for Windows PowerShell, or AWS API access) of the role with anyone who needs to assume the role. The role ARN might look like arn:aws:iam::123456789012:role/UpdateAPP, where the role is named UpdateAPP and the role was created in account number 123456789012.


    The administrator can optionally configure the role so that users who assume the role must first be authenticated using multi-factor authentication (MFA). For more information, see Configuring MFA-Protected API Access.

  2. In the development account an administrator grants members of the Developers group permission to switch to the role. This is done by granting the Developers group permission to call the AWS Security Token Service (AWS STS) AssumeRole API for the UpdateAPP role. Any IAM user that belongs to the Developers group in the development account can now switch to the UpdateAPP role in the production account. Other users who are not in the developer group do not have permission to switch to the role and therefore cannot access the S3 bucket in the production account.

  3. The user requests switches to the role:

    • AWS console: The user chooses the account name on the navigation bar and chooses Switch Role. The user specifies the account ID (or alias) and role name. Alternatively, the user can click on a link sent in email by the administrator. The link takes the user to the Switch Role page with the details already filled in.

    • AWS API/Tools for Windows PowerShell/AWS CLI: A user in the Developers group of the development account calls the AssumeRole function to obtain credentials for the UpdateAPP role. The user specifies the ARN of the UpdateAPP role as part of the call. If a user in the Testers group makes the same request, the request fails because Testers do not have permission to call AssumeRole for the UpdateAPP role ARN.

  4. AWS STS returns temporary credentials:

    • AWS console: AWS STS verifies the request with the role's trust policy to ensure that the request is from a trusted entity (which it is: the development account). After verification, AWS STS returns temporary security credentials to the AWS console.

    • API/CLI: AWS STS verifies the request against the role's trust policy to ensure that the request is from a trusted entity (which it is: the Development account). After verification, AWS STS returns temporary security credentials to the application.

  5. The temporary credentials allow access to the AWS resource:

    • AWS console: The AWS console uses the temporary credentials on behalf of the user on all subsequent console actions, in this case, to read and write to the productionapp bucket. The console cannot access any other resource in the production account. When the user exits the role, the user's permissions revert to the original permissions held before switching to the role.

    • API/CLI: The application uses the temporary security credentials to update the productionapp bucket. With the temporary security credentials, the application can only read from and write to the productionapp bucket and cannot access any other resource in the Production account. The application does not have to exit the role, but instead stops using the temporary credentials and uses the original credentials in subsequent API calls.