Identity and Access Management (IAM) in AWS is not just about creating users and groups. You must also consider renaming and removal of users and groups. My last article focused on the creation of these items. In this one, I will be looking at other administration tasks.
Latest posts by Graham Beer (see all)

Dealing with unused groups, users with additional policies after changing roles, and users who have left your company are all tasks that need to be taken care of to keep a clean AWS IAM environment. Using PowerShell, I will be looking to achieve these tasks to allow for automation and reusability.

Some of the areas we will cover are:

  • Renaming a user
  • Group removal process
  • User removal process

Several steps are required before users and groups can be removed. I recommend using a process to automate these steps as much as possible. We will come back to this in a bit. First, we shall look at renaming a user.

Renaming an AWS User

The only possible ways to rename a user in AWS are to use the CLI, PowerShell or the AWS APIs. There is no way you can do this from the console. When you rename a user in AWS, the groups and policies attached to the user all stay in place. In addition, the unique ID remains the same and any resources that reference the user are updated with the name change.

Use the Update-IAMUser cmdlet to change a username:

Get-IAMUser -UserName 'Test_User' |
Update-IAMUser -NewUserName 'Joe_Bloggs'

Note that with a lot of these IAM cmdlets in AWS, you need to use the -PassThru parameter switch if you want to see a result returned to the console.

Checking the user confirms our change worked:

Checking the renaming of the user

Checking the renaming of the user

Let us move on to removing a group.

Group removal process in AWS

The AWS documentation states there is a three-step process before you can delete a group:

  • Remove all users from the group.
  • Delete all inline policies embedded in the group.
  • Detach all managed policies attached to the group.

To remove users from the group, first you need to get the list of users in the group with the Get-IAMGroup. Then pipe the results to Remove-IAMUserFromGroup, as follows:

$GroupName = 'Storage'
Get-IAMGroup -GroupName $GroupName).Users | Remove-IAMUserFromGroup -GroupName $GroupName -Force

Next, we need to look at the removal of polices. There are two types of policies when working with users and groups, inline or managed. The difference between these policy types is as follows:

Managed policies are standalone policies that can be attached to multiple users, groups or roles. These policies are managed by AWS and are generally recommended over inline policies.

Inline policies are policies that you create yourself and manage. They are embedded directly into a single user, group, or role.

To review the policies attached to a group, use Get-IAMAttachedGroupPolicyList. To remove these policies from the group, use with the Unregister-IAMGroupPolicy. Below, I've used a Foreach loop to remove more than one policy.

$GroupName = 'Storage'
Get-IAMAttachedGroupPolicyList -GroupName $GroupName | Foreach-Object {
	Unregister-IAMGroupPolicy -GroupName $GroupName -PolicyArn $_.PolicyArn

Now that the group is clean of users and policies, we are able to delete our group with the Remove-IAMGroup cmdlet:

Remove-IAMGroup -GroupName Storage -Force

User removal process in AWS

Removing a user from AWS requires removing any groups, policies, access keys, logon profiles and the like from the user. It is not as straightforward as just removing the user, as you will get error messages to remove these other items first.

Trying to remove a user before all items have been cleared

Trying to remove a user before all items have been cleared

We've seen how to remove the user from the group in the previous section of this article. Let us now move on to removing the access keys.

Using the Get-IAMAccessKey cmdlet, we can see how many access keys are assigned to the user:

$name = 'Joe_Bloggs'
Get-IAMAccessKey -UserName $name
Viewing access keys attached to user

Viewing access keys attached to user

For our user, we have a single key attached. If there is more than one key assigned to a user, you will be required to use a foreach loop to remove each key. Follow the same pattern we used above for removing users from a group to do this.

$key = Get-IAMAccessKey -UserName $name
Remove-IAMAccessKey -AccessKeyId $key.AccessKeyId -UserName $name -Force

Our next task is to remove any polices attached to the user, should they be directly assigned instead of assigned through a group.

The example user, Joe Bloggs, has two managed polices assigned:

Attached user polices

Attached user polices

Again, we are required to loop through the attached polices and use Unregister-IAMUserPolicy to remove them. The pattern using the foreach loop to remove them should now be familiar if more than a single item is attached to the user:

$UserName = 'Joe_Bloggs'
Get-IAMAttachedUserPolicyList -UserName $UserName | ForEach-Object {
    $params = @{
        PolicyArn = $_.PolicyArn
        UserName  = $UserName
        Force     = $true
    Unregister-IAMUserPolicy @params
Removing the logon profile is simple:
Remove-IAMLoginProfile -UserName $UserName -Force

Removing the logon profile is simple:

Remove-IAMLoginProfile -UserName $UserName -Force

Once the user is clean of these various attached items, we are finally able remove it:

Remove-IAMUser -UserName $UserName -Force

Before wrapping up this article, you should also consider whether you have assigned other additional roles such as MFA, inline policies, or certificates. The respective cmdlets for these are as follows:

  • *-IAMSigningCertificate
  • *-IAMUserPolicies
  • *-IAMMFADevice

Usage of these cmdlets follows the same process and pattern that we used with the other cmdlet examples in this article. But should you need any guidance, use the PowerShell help system to see the documentation on these cmdlets.

Subscribe to 4sysops newsletter!


Removing users and groups in AWS with PowerShell is not as simple as you might expect. Hopefully, this article has shown which cmdlets are necessary to remove the various attached polices, roles, and groups. I recommend combining these cmdlets into a function or script to enable automation. PowerShell with Identity and Access Management (IAM) in AWS is very powerful and I thoroughly recommend exploring it!


Leave a reply

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


© 4sysops 2006 - 2023


Please ask IT administration questions in the forums. Any other messages are welcome.


Log in with your credentials


Forgot your details?

Create Account