Granting a User Permissions to Switch Roles
When you create a role for cross-account
access, you establish trust from the account that owns the role and the resources
(trusting account) to the account that contains the users (trusted account). To do
this, you
specify the trusted account number as the Principal in the role's trust policy.
That allows potentially any user in the trusted account to
assume the role. To complete the configuration, the administrator of the trusted account
must
give specific groups or users in that account permission to switch to the role.
To grant a user permission to switch to a role, you create a new policy for the user or edit an existing policy to add the required elements. You can then send the users a link that takes the user to the Switch Role page with all the details already filled in. Alternatively, you can provide the user with the account ID number or account alias that contains the role and the role name. The user then goes to the Switch Role page and adds the details manually. For details on how a user switches roles, see Switching to a Role (AWS Management Console).
Note that you can switch roles only when you sign in as an IAM user. You cannot switch roles when you sign in as the AWS account root user.
Important
You cannot switch roles in the AWS Management Console to a role that requires an ExternalID value. You can switch to
such a role only by calling the AssumeRole API that supports the ExternalID
parameter.
Notes
-
This topic discusses policies for a user, because we are ultimately granting permissions to a user to accomplish a task. However, it is best practice not to grant permissions directly to an individual user. For easier management, we recommend assigning policies and granting permissions to IAM groups and then making the users members of the appropriate groups.
-
When you switch roles in the AWS Management Console, the console always uses your original credentials to authorize the switch. This applies whether you sign in as an IAM user, as a SAML-federated role, or as a web-identity federated role. For example, if you switch to RoleA, it uses your original user or federated role credentials to determine if you are allowed to assume RoleA. If you then try to switch to RoleB while you are using RoleA, it still uses your original user or federated role credentials to authorize your attempt to switch to RoleB, not the credentials for RoleA.
Creating or Editing the Policy
A policy that grants a user permission to assume a role must include a statement with
the
Allow effect on the sts:AssumeRole action and the Amazon Resource
Name (ARN) of the role in a Resource element, as shown in the following example.
Users that get the policy (either through group membership or directly attached) are
allowed
to switch to the specified role.
Note
Note that if Resource is set to *, the user can assume any
role in any account that trusts the user's account (the role's trust policy specifies
the
user's account as Principal). As a best practice, we recommend that you follow
the principle of
least privilege and specify the complete ARN for only the role(s) that the user
needs.
The following example shows a policy that lets the user assume roles in only one account and additionally specifies by wildcard (*) that the user can only switch to a role in that account if the role name begins with the letters "Test" followed by any other combination of characters.
{ "Version": "2012-10-17", "Statement": { "Effect": "Allow", "Action": "sts:AssumeRole", "Resource": "arn:aws:iam::ACCOUNT-ID-WITHOUT-HYPHENS:role/Test*" } }
Note
The permissions that the role grants to the user do not add to the permissions already
granted to the user. When a user switches to a role, the user temporarily gives up
his or
her original permissions in exchange for those granted by the role. When the user
exits the
role, then the original user permissions are automatically restored. For example,
if the
user's permissions allow working with Amazon EC2 instances, but the role's permissions
policy
does not grant those permissions, then while using the role the user cannot work with
Amazon EC2
instances in the console, and temporary credentials obtained via AssumeRole do
not work with Amazon EC2 instances programmatically.
Providing Information to the User
After you create a role and grant your user permissions to switch to it, you must provide the user with the role name and the account ID number or account alias that contains the role. You can make things easier for your users by sending them a link that is preconfigured with the account ID and role name. You can see the role link on the final page of the Create Role wizard or in the Role Summary page for any cross-account enabled role.
Note
If you create the role with the AWS CLI , Tools for Windows PowerShell,or the AWS
API, then you can create the
role with a path in addition to a name. If you do so, then you must
provide the complete path and role name to your users to type on the Switch
Role page of the AWS Management Console. For example:
division_abc/subdivision_efg/role_XYZ.
Important
If you create the role programmatically instead of in the IAM console, then you have
an option to add a Path of up to 512 characters in addition to the
RoleName, which can be up to 64 characters long. However, to use a role with
the Switch Role feature in the AWS console, the combined Path and
RoleName cannot exceed 64 characters.
You can also use the following format to manually construct the link. Substitute your account ID or alias and the role name for the two parameters in the request:
https://signin.aws.amazon.com/switchrole?account=YourAccountIDorAliasHere&roleName=pathIfAny/YourRoleNameHere
We recommend that you direct your users to the topic Switching to a Role (AWS Management Console) to step them through the process.
Note
For security purposes, you can use AWS CloudTrail to audit role switching. If CloudTrail is turned on for the account, IAM logs actions that are performed with the role's temporary security credentials. For more information, see CloudTrail Event Reference in the AWS CloudTrail User Guide.
