Switch to an IAM role (Tools for Windows PowerShell)
A role specifies a set of permissions that you can use to access Amazon resources that you need. In that sense, it is similar to a user in Amazon Identity and Access Management (IAM). When you sign in as a user, you get a specific set of permissions. However, you don't sign in to a role, but once signed in you can switch to a role. This temporarily sets aside your original user permissions and instead gives you the permissions assigned to the role. The role can be in your own account or any other Amazon Web Services account. For more information about roles, their benefits, and how to create and configure them, see IAM roles, and IAM role creation.
Important
The permissions of your IAM user and any roles that you switch to are not cumulative. Only one set of permissions is active at a time. When you switch to a role, you temporarily give up your user permissions and work with the permissions that are assigned to the role. When you exit the role, your user permissions are automatically restored.
This section describes how to switch roles when you work at the command line with the Amazon Tools for Windows PowerShell.
Imagine that you have an account in the development environment and you occasionally need to
work with the production environment at the command line using the Tools for Windows PowerShellUse-STSRole
cmdlet that passes the ARN of a new role as a parameter. The command returns temporary security
credentials for the requested role. You can then use those credentials in subsequent PowerShell
commands with the role's permissions to access resources in production. While you use the role,
you cannot use your user permissions in the Development account because only one set of
permissions is in effect at a time.
Note
For security purposes, administrators can review Amazon CloudTrail logs to learn who performed an action in Amazon. Your administrator might require that you specify a source identity or a role session name when you assume the role. For more information, see sts:SourceIdentity and sts:RoleSessionName.
Note that all access keys and tokens are examples only and cannot be used as shown. Replace with the appropriate values from your live environment.
To switch to a role (Tools for Windows PowerShell)
-
Open a PowerShell command prompt and configure the default profile to use the access key from your current IAM user or from your federated role. If you have previously used the Tools for Windows PowerShell, then this is likely already done. Note that you can switch roles only if you are signed in as an IAM user, not the Amazon Web Services account root user.
PS C:\>
Set-AWSCredentials -AccessKey
-SecretKeyAKIAIOSFODNN7EXAMPLE
-StoreAswJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
MyMainUserProfile
PS C:\>
Initialize-AWSDefaults -ProfileName
MyMainUserProfile
-Regionus-west-2
For more information, see Using Amazon Credentials in the Amazon Tools for Windows PowerShell User Guide.
-
To retrieve credentials for the new role, run the following command to switch to the
role in the 123456789012 account. You get the role ARN from the account administrator who created the role. The command requires that you provide a session name as well. You can choose any text for that. The following command requests the credentials and then captures theRoleName
Credentials
property object from the returned results object and stores it in the$Creds
variable.PS C:\>
$Creds = (Use-STSRole -RoleArn "arn:aws-cn:iam::
123456789012
:role/RoleName
" -RoleSessionName "MyRoleSessionName
").Credentials$Creds
is an object that now contains theAccessKeyId
,SecretAccessKey
, andSessionToken
elements that you need in the following steps. The following sample commands illustrate typical values:PS C:\>
$Creds.AccessKeyId
AKIAIOSFODNN7EXAMPLEPS C:\>
$Creds.SecretAccessKey
wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEYPS C:\>
$Creds.SessionToken
AQoDYXdzEGcaEXAMPLE2gsYULo+Im5ZEXAMPLEeYjs1M2FUIgIJx9tQqNMBEXAMPLECvSRyh0FW7jEXAMPLEW+vE/7s1HRp XviG7b+qYf4nD00EXAMPLEmj4wxS04L/uZEXAMPLECihzFB5lTYLto9dyBgSDyEXAMPLE9/g7QRUhZp4bqbEXAMPLENwGPy Oj59pFA4lNKCIkVgkREXAMPLEjlzxQ7y52gekeVEXAMPLEDiB9ST3UuysgsKdEXAMPLE1TVastU1A0SKFEXAMPLEiywCC/C s8EXAMPLEpZgOs+6hz4AP4KEXAMPLERbASP+4eZScEXAMPLEsnf87eNhyDHq6ikBQ==PS C:\>
$Creds.Expiration
Thursday, June 18, 2018 2:28:31 PM -
To use these credentials for any subsequent command, include them with the
-Credential
parameter. For example, the following command uses the credentials from the role and works only if the role is granted theiam:ListRoles
permission and can therefore run theGet-IAMRoles
cmdlet:PS C:\>
get-iamroles -Credential $Creds
-
To return to your original credentials, simply stop using the
-Credentials $Creds
parameter and allow PowerShell to revert to the credentials that are stored in the default profile.