Providing Access to an IAM User in Another AWS Account That You Own
You can grant your IAM users permission to switch to roles within your AWS account or to roles defined in other AWS accounts that you own.
If you want to grant access to an account that you do not own or control, see Providing Access to AWS Accounts Owned by Third Parties later in this topic.
Imagine that you have Amazon Elastic Compute Cloud (Amazon EC2) instances that are critical to your organization. Instead of directly granting your users permission to terminate the instances, you can create a role with those privileges and allow administrators to switch to the role when they need to terminate an instance. This adds the following layers of protection to the instances:
You must explicitly grant your users permission to assume the role.
Your users must actively switch to the role using the AWS Management Console.
You can add multi-factor authentication (MFA) protection to the role so that only users who sign in with an MFA device can assume the role.
We recommend using this approach to enforce the principle of least access, that is, restricting the use of elevated permissions to only those times when they are needed for specific tasks. With roles you can help prevent accidental changes to sensitive environments, especially if you combine them with auditing to help ensure that roles are only used when needed.
When you create a role for this purpose, you specify the accounts by ID whose users need
access in the
Principal element of the role's trust policy. You can then grant
specific users in those other accounts permissions to switch to the role.
A user in one account can switch to a role in the same or a different account. While using the role, the user can perform only the actions and access only the resources permitted by the role; their original user permissions are suspended. When the user exits the role, the original user permissions are restored.
For another example, 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.
In the production account an administrator uses IAM to create the
UpdateAPProle 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
UpdateAPProle. 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
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
UpdateAPPand 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.
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)
AssumeRoleAPI for the
UpdateAPProle. Any IAM user that belongs to the Developers group in the development account can now switch to the
UpdateAPProle 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.
The user requests switches to the role:
AWS console: The user clicks the account name in the navigation bar and choosesSwitch 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
AssumeRolefunction to obtain credentials for the
UpdateAPProle. The user specifies the ARN of the
UpdateAPProle 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
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.
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
productionappbucket. 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
productionappbucket. With the temporary security credentials, the application can only read from and write to the
productionappbucket 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.
For details about creating a role to delegate access to IAM users that you control, see Creating a Role to Delegate Permissions to an IAM User.