Switching to an IAM Role (Tools for Windows PowerShell)
A role specifies a set of permissions that you can use to access AWS resources that you need. In that sense, it is similar to a user in AWS 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 AWS account. For more information about roles, their benefits, and how to create and configure them, see IAM Roles, and Creating IAM Roles.
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 AWS 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 PowerShell. You already have one access key
credential set available to you. These can be an access key pair assigned to your standard IAM
user; or, if you signed-in as a federated user, they can be the access key pair for the role
initially assigned to you. You can use these credentials to run the
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 make use of your user privileges in the Development account because only one set of
permissions can be in effect at a time.
For security purposes, you can use AWS CloudTrail to audit the use of roles in the account. The
Use-STSRole must include a
-RoleSessionName parameter with a
value between 2 and 64 characters long that can include letters, numbers, and the
=,.@- characters. The role session name identifies actions in CloudTrail logs that
are performed with the temporary security credentials. For more information, see CloudTrail Event Reference in the
AWS CloudTrail User Guide.
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 from the 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 AWS account root user.Copy
PS C:\> Set-AWSCredentials -AccessKey
MyMainUserProfilePS C:\> Initialize-AWSDefaults -ProfileName
For more information, see Using AWS Credentials in the AWS 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 the
Credentialsproperty object from the returned results object and stores it in the
$Creds = (Use-STSRole -RoleArn "arn:aws:iam::
RoleName" -RoleSessionName "
$Credsis an object that now contains the
SessionTokenelements that you need in the following steps. The following sample commands illustrate typical values:Copy
PS C:\> $Creds.AccessKeyId AKIAIOSFODNN7EXAMPLE PS C:\> $Creds.SecretAccessKey wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY PS C:\> $Creds.SessionToken AQoDYXdzEGcaEXAMPLE2gsYULo+Im5ZEXAMPLEeYjs1M2FUIgIJx9tQqNMBEXAMPLECvSRyh0FW7jEXAMPLEW+vE/7s1HRp XviG7b+qYf4nD00EXAMPLEmj4wxS04L/uZEXAMPLECihzFB5lTYLto9dyBgSDyEXAMPLE9/g7QRUhZp4bqbEXAMPLENwGPy Oj59pFA4lNKCIkVgkREXAMPLEjlzxQ7y52gekeVEXAMPLEDiB9ST3UuysgsKdEXAMPLE1TVastU1A0SKFEXAMPLEiywCC/C s8EXAMPLEpZgOs+6hz4AP4KEXAMPLERbASP+4eZScEXAMPLEsnf87eNhyDHq6ikBQ== PS C:\> $Creds.Expiration Thursday, June 18, 2015 2:28:31 PM
To use these credentials for any subsequent command, include them with the
-Credentialsparameter. For example, the following command uses the credentials from the role and works only if the role is granted the
iam:ListRolespermission and can therefore run the
get-iamroles -Credential $Creds
To return to your original credentials, simply stop using the
-Credentials $Credsparameter and allow PowerShell to revert to the credentials that are stored in the default profile.