AWS IAM Basics using AWS Tools for Windows PowerShell – Roles

So far I’ve covered IAM Users and Groups. Today I’ll be looking at IAM Roles. Here is a brief description of what roles are from the AWS IAM Roles User Guide.

An IAM role is similar to a user, in that it is an AWS identity with permission policies that determine what the identity can and cannot do in AWS. However, instead of being uniquely associated with one person, a role is intended to be assumable by anyone who needs it.

You can use roles to delegate access to users, applications, or services that don’t normally have access to your AWS resources. For example, you might want to grant users in your AWS account access to resources they don’t usually have, or grant users in one AWS account access to resources in another account.

So now that we know a little about what roles are and used for, let’s look at the available PowerShell cmdlet’s we can utilise. There will be mention of IAM Policies and related PowerShell cmdlet’s, however I will not be going into any more detail. If you want to read more about IAM Policies, you can read about them here.

Create Roles

To create an IAM role we call the New-IAMRole cmdlet. We provide the -RoleName parameter with the name of the role we want to create. We also provide the -AssumeRolePolicyDocument the path to a trust policy json document, which grants an entity permission to assume the new role. Below is the contents of TrustPolicy.json (replace aws_account_number with your actual AWS account number) followed by the New-IAMRole cmdlet output.

    "Version": "2012-10-17",
    "Statement": {
        "Effect": "Allow",
        "Principal": { "AWS": "arn:aws:iam::aws_account_number:root" },
        "Action": "sts:AssumeRole"

Once we’ve created the role we can assign a policy (permissions) to it. Below is an example of assigning the AWS IAMReadOnlyAccess policy to the Developers role.

Get Roles

You can get a list of roles in your AWS account by calling the Get-IAMRoles cmdlet. As you can see below, there is the Developers role we created in the step above.

Assume Roles

The benefit of a role is that we can capture the role’s credentials and inherit it’s permissions. To assume the role, we use the Use-STSRole function. We pass the arn of the role we want to assume to -RoleArn, and a role session name to -RoleSessionName. Below I have populated the $Creds variable with the Credentials AWSCredentials object.

With the $Creds variable, we can pass this to AWS PowerShell cmdlet’s -Credentials parameter. This will execute the cmdlets under the security context of the role’s policies.

Remove Roles

To remove a role, we also need to remove any policies attached to the role first. If not we will get the below error:

So the steps should be, unregister (remove) any policies from the role by calling the Unregister-IAMRolePolicy, followed by calling the Remove-IAMRole cmdlet. I have called the Get-IAMRoles to show the role has been successfully removed.

And that’s all for IAM Roles. In my next blog post I will complete the IAM blog series by combining all the cmdlet’s I’ve talked about in Users, Groups and Roles.

Leave a Reply

Your email address will not be published. Required fields are marked *