IAM User Management using AWS CLI

In our lab walkthrough series, we go through selected lab exercises on our INE Platform. Subscribe or sign up for a 7-day, risk-free trial with INE and access this lab and a robust library covering the latest in Cyber Security, Networking, Cloud, and Data Science!

Purpose: As an AWS Administrator, you will find yourself granting access to various resources. One way to grant this access is through IAM users. So learning how to manage IAM users is important.

In this article, we will look at performing common operations on IAM users using the AWS CLI. These operations include creating, reading, updating, and deleting users.

Technical Difficulty: 

|    Novice   |   Beginner    |   Proficient    |     Expert  

Prerequisites: 

• IAM Administrator user account (not root account) 

• AWS CLI installed and configured with the above Administrator account as the default profile.

What is an IAM user?

An IAM user is an entity that you create in AWS. It may represent a person or an application that uses it to interact with AWS. With IAM users you will be able to grant direct external access to your resources.

Lab Scenario

We have set up the below scenario in our INE labs for our students to practice.

The user will be provided with the credentials for an IAM Administrator user account, using which you can perform the tasks discussed in this article.

Lab Link: https://my.ine.com/Cloud/courses/9a4d93ee/aws-security-basics/lab/a4575bdd-bb6f-4a5a-838a-d257fe3000d9

Objective

Perform various operations on IAM users that involve creating, reading, updating, and deleting users, using the AWS CLI.

Solution: 

Creating users

When you create a user, IAM identifies that user in three ways:

• A "friendly name" for the user. A name you define, such as a username, that you will use to identify the user in the AWS Management Console.

• An Amazon Resource Name (ARN) for the user. The ARN is used to uniquely identify the user across all of AWS.

• A unique identifier for the user. This ID is a part of programmatic responses from the API and other tooling.

For more information about these identifiers, see the AWS documentation on IAM identifiers.

Creating Users Using Arguments

The most common way to create users using the AWS CLI is to pass arguments to the following command: 

Command:

aws iam create-user

Step 1: Once you have configured the AWS CLI with the provided credentials, use the following command to create a user named Alice:

Command:

aws iam create-user --user-name Alice

You should see the output in JSON format confirming the creation of Alice. It will look similar to what you see below:

Creating Users Using Skeleton Files

Like most AWS resources, users can be created using skeleton files. A skeleton file is nothing but a JSON or YAML template file that provides an outline of the command that you want to run. Let’s create a user named Brad using this method.

Step 1: Use the following command to generate a JSON skeleton and direct it to a file called BradIAMUser.json and save it:

Command:

aws iam create-user  --generate-cli-skeleton input > <relative path>/BradIAMUser.json

Step 2: Open the skeleton file in your text editor and remove the "PermissionsBoundary" parameter which is not required right now. Next, fill in the values for the remaining parameters as shown; Your file should now look like this:

{
   "Path": "/",
   "UserName": "Brad",
   "Tags": [
       {
           "Key": "team",
           "Value": "dev"
       },
       {
           "Key": "position",
           "Value": "contractor"
       }
   ]
}

Step 3: Save the file and use the following command to create the user:

Command: 

aws iam create-user --cli-input-json file://<relative path>/BradIAMUser.json

You should see the output in JSON format confirming the creation of Brad. It will look similar to what you see below:

Allowing Users to Login

When you create a user using the AWS CLI, that user is unable to log in to the AWS Management Console, make signed API request, or use tools like the AWS CLI. There are two types of access associated with users:

• Console access

• Programmatic access

To grant a user console access you will need to create a login profile for them. Creating a login profile creates a password for the specified user that allows them to log in to the AWS Management Console.

To grant a user programmatic access in scenarios where the user might need to make API calls, use the AWS CLI, or use the Tools for Windows PowerShell, you will need to create an access key for the user. 

We will first focus on giving the user a login profile. In a later section, we will look at creating an access key for a user.

Let’s look at the following command:

aws iam create-login-profile

The aws iam create-login-profile command expects us to pass a password as a command line argument. There are a few problems with this method of supplying a password, but one that may not be as obvious is the fact that not all terminal applications handle special characters the same way. This makes passing a complex password unpredictable and difficult when using the command line.

Because of this limitation, it is recommended to create a user login profile from a skeleton file. 

Let’s create a login profile for the existing IAM user - Brad.

Step 1: Use the following command to generate a JSON skeleton and direct it to a file called BradIAMLoginProfile.json and save it:

Command:

aws iam create-login-profile --generate-cli-skeleton input > <relative path>/BradIAMLoginProfile.json

Step 2: Open the skeleton file in your text editor and fill in the values for parameters as shown; Your file should look like this. You can supply a password of your choosing.

{
   "UserName": "Brad",
   "Password": "supply your password here",
   "PasswordResetRequired": true
}

Step 3: Save the file and use the following command to create a login profile for Brad:

Command: 

aws iam create-login-profile --cli-input-json file://<relative path>/BradIAMLoginProfile.json

You should see output similar to the following:

Reading Users

Each command in the previous steps returned status output to the screen informing us of the result of the command. However, consider what would happen if you needed to know if the desired username is already in use, how would you get that information?

The AWS CLI has many commands that let administrators easily get user information:

Each command has a different use-case but all fall in the domain of reading users. Now, let’s look at how to use these commands to get detailed user information.

Listing Users

To retrieve a list of users in we simply use the following command:

aws iam list-users

Step 1: Let's list the IAM users associated with the current account. Use the following command:

aws iam list-users

At a minimum, you should see the two users that you created previously. It will look similar to what you see below:

Getting a Single User

Having a list of users is definitely nice, but there are plenty of reasons why administrators need to view just one user in more detail. For that, we have the following command:

aws iam get-user

Step 1: Time to see this in action, from the terminal type the following command:

aws iam get-user --user-name Brad

If you created the user successfully before, you should see similar output to that below:

Viewing Tags Attached to a User

Organization of resources is a key skill for every AWS Administrator. A well-organized environment not only makes administrative tasks easier but can also help keep resource costs in line with expectations. One such way to organize resources, including users, is through the use of tags.

To view the tags attached to a user, we have the following command:

aws iam list-user-tags

Step 1: Earlier you created a user named Brad using the BradIAMUser.json skeleton file. That skeleton file attached two tags to Brad upon creation. Let's see what those tags are by running the following command in the terminal:

aws iam list-user-tags --user-name Brad

You should see similar output to that below:

Finding Only Users With a Specific Tag

Based on the previous step it seems like our demo organization contains a few contractors. Administrators often want to know exactly who may be a contractor. There is no built-in command that will get this information for us, so we need to write a small script that will combine the commands we have covered above to accomplish this task.

Note: The script that will be written relies on Bash. If you are on Windows ensure that you have the Windows Subsytem for Linux installed. If you are using macOS or Linux ensure your shell is Bash.

Step 1: Create a new file named list-users-with-tags.sh and add the following code to it:

#!/bin/bash
 
# Use a query parameter to list just the usernames of the users and store it in a variable called 'users'
users=$(aws iam list-users --query 'Users[].UserName' --output text)
 
for user in $users; do
# store the users TAGS in a variable
tags=$(aws iam list-user-tags --user-name $user --output text)
   # loop through TAGS
   for tag in $tags; do
       # if the tag is 'contractor' then ouput to the screen
       if [ $tag == "contractor" ]; then
           printf "%s\n" $user
       fi
   done
done

The above code snippet loops through the list of usernames stored in the ‘users’ variable and runs aws iam list-user-tags and checks them for a position:contractor key-value pair. 

Step 2: Ensure the script is executable using the sudo chmod +x list-users-with-tags.sh command and execute it. You should only see the username Brad in the output since Brad is the only user who is currently a contractor.

Listing Access Keys for a User

"Who accessed this resource?" A quote by every administrator ever. Luckily finding out who a given access key belongs to is a simple task using the AWS CLI.

Although we can easily list the access keys, it's incredibly important to understand that any secret access keys associated with a user will not be visible.

If a user forgets their secret access key or needs to see it once it's created, the only option an administrator has is to create a new one!

Let’s look at the following command:

aws iam list-access-keys

Step 1: From the terminal let's run the following command to list the access keys for Brad:

aws iam list-access-keys --user-name Brad

At this point, as we not created any access key for Brad, you will see the following output:

We will look at creating an access key for a user in a later section.

Listing Group Membership for a User

There will be plenty of times as an administrator when knowing what groups a user is a part of is an important piece of information to have.

The following command allows administrators to quickly get this information per user:

aws iam list-groups-for-user

We currently have a user named Brad who does not belong to any groups. Let's verify that by listing the group membership for Brad by running the following command in a terminal:

aws iam list-groups-for-user --user-name Brad

The output for this command should return an empty list since `Brad` has no group membership:

We will look at creating groups and adding a user to a group in a different article. For now, let’s proceed further.

Updating Users

Employees get promoted, move around to different departments, change their names, and an overwhelming amount of other behaviors that require their resource access to be updated.

There is a wide range of things we may need to update on a user. Let’s look at some of the common properties that get updated when managing users.

Updating Username or Path of a User

The AWS CLI provides the following command to update a user’s name or the path to their user resource:

aws iam update-user

Note: Although this seems like a straightforward operation, this simple change can cause problems for the user. You can see the implications of renaming an IAM user in the AWS documentation.

Step 1: Let’s rename Brad to Jerry. Use the following command in your terminal to accomplish this:

aws iam update-user --user-name Brad --new-user-name Jerry

There is no output for this command. Use what you have learned in the Reading Users section to verify the user Brad has in fact been renamed to Jerry.

Adding and Removing Tags Associated With a User

You can use the following command to add some tags to a user:

aws iam tag-user

After we add a few tags to a user we can remove unwanted tags by using the following command:

aws iam untag-user

Step 1: From the terminal run the following command to add the tag bread=crumbs to Jerry.

aws iam tag-user --user-name Jerry --tags '{"Key": "bread", "Value": "crumbs"}'

Take special care to account for the quotations around the tags object in the above command.

Step 2: Adding one tag is great, but administrators often find themselves needing to change more than one tag as users and other resources evolve in the environment. Let's use the following command to update an existing tag as well as add a new one at the same time:

aws iam tag-user --user-name Jerry --tags '[{"Key": "position", "Value": "Manager"}, {"Key": "level", "Value": "3"}]'

The value to level may look like a number but tags must be strings, so be sure to quote the value as "3".

To verify if all the desired changes have been made to Jerry, use aws iam list-user-tags --user-name Jerry command. You should see the following output:

Notice that the position that already exists as a tag on this user has been updated. On the other hand, level and bread are new tags that have been attached to the user.

Step 3: Looks like Jerry has a tag that doesn't make much sense, bread=crumbs. Let's use the AWS CLI to remove that tag from Jerry. Help Jerry out by using the following command from your terminal:

aws iam untag-user --user-name Jerry --tag-keys bread

There is no output for this command. But you can verify that the unwanted tag has been removed.

Managing Access Keys for a User

Another common administrative task is managing resource access for a particular user. This section shows you how to use the AWS CLI to create, remove and update user access keys. Since all of these operations are closely related we will look at the commands and their options first, and then perform tasks that implement each command.

Command:

aws iam create-access-key

Command:

aws iam update-access-key

Command:

aws iam delete-access-key

Step 1: There are no access keys attached to Jerry. Use the following command to create and attach an access key to Jerry:

aws iam create-access-key --user-name Jerry

You should see an output similar to the one shown below:

Note: SecretAccessKeys should be kept secret. You will only see this key during the creation of the access key. If this key get's lost the only option you will have is to delete the key and create a new one.

You can also try viewing the access key(s) assigned to a user using the command discussed in Listing Access Keys for a User section.

So, Jerry is going on a long vacation! They won't need access to any resources while they are away, and since they are planning on being gone for an extended period of time it has been determined that marking their access keys as inactive is the best way to secure the environment while they are away.

As an administrator, you may find a wide range of scenarios where you need to suspend the use of an access key without going through the destructive measures of deleting the key. The aws iam update-access-key command allows you to do just that, toggle the status of the access key between Active and Inactive.

Step 2: Use the following command to update the access key assigned to Jerry:

aws iam update-access-key --user-name Jerry --access-key-id "AKIAXCYODBXSRRECZD5X" --status Inactive

Notice the value passed to --access-key-id is the same value from the output when the key was created. This command has no output. You can verify that the status has been changed to inactive by running the aws iam list-access-keys --user-name Jerry command. You should see the following output:

While Jerry was away on vacation, your organization drafted a new policy about access keys that are set to inactive for more than 30 days. You are now required to remove this access key from the environment after 30 days of inactivity.

Step 3: Use the following command to remove the access key from Jerry: 

aws iam delete-access-key --user-name jerry --access-key-id "AKIAXCYODBXSRRECZD5X"

There is no output for this command. However, you can verify that this key has been removed from Jerry. 

Deleting Users

Deleting users through the AWS CLI can be a little tricky. It's important to understand that the process of deleting users through the AWS Management Console and the AWS CLI differ from one another.

The AWS CLI requires that you remove all attached items from the user prior to deleting the user, or else the deletion fails. AWS has listed the items to remove from a user before deletion in the description for the delete-user command.

You can list the current users using the aws iam list-users command. We will delete the users that we created in this article. 

Deleting Alice

As Alice doesn’t have any items attached to it, we can directly delete it using the following command:

aws iam delete-user

Step 1: Run the following command in the terminal to delete Alice:

aws iam delete-user --user-name Alice

There is no output for this command. You can verify if Alice has been deleted using the aws iam list-users command.

Deleting Jerry

Remember that we created a login profile for a user named Brad previously. But we later updated the username to Jerry and so we still have the login profile attached to it.

So we first need to delete the login profile using the following command: 

aws iam delete-login-profile

Step 1: Delete the login profile for Jerry by running the following command in the terminal: 

aws iam delete-login-profile --user-name Jerry

Step 2: Now you can delete Jerry by using the following command:

aws iam delete-user --user-name Jerry

You can verify that Jerry has been deleted by using the aws iam list-users command.

Conclusion

In this article we looked at various operations that you can perform on IAM users using the AWS CLI. These operations involved creating, reading, updating, and deleting users. 

Try the AWS CLI hands-on! Subscribe or sign up for a 7-day, risk-free trial with INE to access this lab and a robust library covering the latest in Cyber Security, Networking, Cloud, and Data Science!