Introduction

This guide takes you through installing and testing the AWS CLI in your local Linux/Windows (WSL2)/MacOS environment.

Downloading/Installing the AWS CLI Package

Select the appropriate tab for your OS below:

$ sudo snap install aws-cli --classic

$ aws --version

$ sudo snap install aws-cli --classic

$ aws --version

$ aws --version

Configuration

There are a number of different methods which can be used to authenticate the AWS CLI, however some of these methods are best avoided to reduce security risks, for example one mechanism involves long term credentials being obtained and stored in the local configuration files and could lead to a security breach if these files were to be compromised.

If you are using a corporate directory with IAM Identity Center, you should follow the instructions here or ask your AWS Administration team about how to configure the AWS CLI.

How you configure authentication for the CLI will depend on whether the IAM Identity Center is enabled and in use for your AWS account.

AWS provides two similar naming products for IAM configuration:

• Identity and Access Management (IAM)

  This is the default system in AWS and will work for all AWS accounts, using this you can easily create users, assign them the appropriate policies and generate long term credentials for them. Nice and simple, but certainly not the most secure method as you could end up with long term keys on systems, perhaps forgotten about over time.

  It is possible to create temporary credentials using the standard IAM system for the users however this it considerably more complex to set up. There is no "generate temporary credentials" button in the standard IAM dashboard. The aws command line tool has a feature to generate temporary credentials, but you need credentials to obtain credentials so a bit of catch 22 and very messy.

  If using standard IAM, over time, the risk of having long term credentials on forgotten systems increases, so it is recommended to move to the IAM Identity Center instead if using the AWS CLI.

• IAM Identity Center

  With improvements introduced to authentication methods in AWS CLI and IAM Identity Center around security, this is the recommended method for using the AWS CLI and should be used if at all possible. Short term credentials can be used with ease from the the CLI command line.

A new AWS account will have Identity and Access Management enabled by default, but not the Identity Center, if you are not sure whether your account has the IAM Identity Center enabled, open IAM Identity Center from the main web console, if it is not enabled you'll see a button prompting you to enable it.

Should I enable IAM Identity Center?

Please reading the guide here to understand the implications to help you decide if it is the right thing to do, but if you or other users in your AWS account will be be making using the AWS CLI, it is strongly encouraged.

Please read the next page to get authenticated with the AWS CLI using IAM Identity Center. If long term credentials without the Identity Center are your only option, instructions are given on page 3.

Authenticating with IAM Identity Center SSO (Recommended)

Step 1: Create the User Which Will Be Used for CLI Access

If the user account you wish to use does not already exist, head to the the IAM Identity Center dashboard and create and create it. If you are using an external directory, this account should be created directly in that external directory instead.

Step 2: Create or Check Existing Permission Sets

If you are setting up an existing user, you can check if the correct permissions set has been assigned on the correct account AWS clicking on Users in the left sidebar of the IAM Identity Center dashboard, selecting the user in question and then clicking on the AWS accounts tab.

If a new permission set is required:

1. Go to Permission Sets in the sidebar.

Here's you'll see a list of existing permission sets, if don't see the one you need or there are none at all:

2. Click Create permission set.

Here you can create an appropriate permission set, if you are new to the IAM Identity Center, I would suggest simply creating a "ReadOnlyAccess" permission set for now:

3. Ensure Predefined permission set is selected, and select ReadOnlyAccess.
4. Click Next.
5. Set a name, e.g., ReadOnlyAccess and click Next and Create.

Step 3: Assign Access (if needed)

Reminder: In AWS, an "account" is a top-level container for resources and billing, tied to a unique ID (e.g., 123456789012), not just a user login like in typical IT systems.

1. Go to AWS accounts in the sidebar.
2. Select one or more accounts (if you have multiple) to assign the users to.
3. Click Assign users or groups.
4. In Users or Groups tab, select the user or group you wish to assign the permission set to.
5. Click Next
6. From the list of permission sets, select the appropriate set (e.g. ReadOnlyAccess)
7. Select Next and Submit

Step 4: Configure AWS CLI for IAM Identity Center

Back an your command line where you installed the AWS CLI, type:

$ aws configure sso

And follow the prompts:

• SSO session name: Enter a name to identify this session (e.g., [username]-sso) or just press Enter.
• SSO start URL: Input your SSO Start URL (e.g., https://d-123abc456.awsapps.com/start - the same URL used for regular SSO logins, and as shown in the IAM Identity Center dashboard under "AWS access portal URL").
• SSO region: Enter the region (e.g., us-east-1 or eu-west-2 - as shown in the IAM Identity Center dashboard under "Region").
• SSO registration scopes: Input sso:account:access or just press enter if this is given as the default.

Note: The SSO registration scopes values has been introduced by AWS to request specific access scopes although I'm not personally aware of examples of any scopes other than sso:account:access being used. That may change in the future though, along with this document. For now, just use sso:account:access.

You'll now be prompted to open a browser and login to the IAM Identity Center, and depending on your configuration:

• A browser window will open for login.
• No browser window will open, but a URL will be presented which you can copy and paste into a browser window.

Log in with your SSO credentials.

Once you've logged in, you'll be asked to give give permission to the AWS CLI (which may have a prefix of botocore-client-), click to allow access.

Back at the command line, you may be asked these questions based on your setup:

• Which account you wish to access (if there is more than one available to your user account, so selected the one you wish to use.)
• Which role to use (if more than one has been assigned to the account, select the one you wish to use.)

You'll then be asked to provide a Default client Region for your CLI queries, which can be different from your SSO region:

• Default client Region: Set a region (e.g., us-east-1 or eu-west-2)

And a default output format:

• Default output format: Enter json (or yaml, text).

Finally, you'll be asked to provide a profile name, which will be used to identify this profile in your configuration files.

Think about how you may need to use different profiles in the future, attached to different accounts, permissions, regions or usernames. Setting suitable profile names will help to identify each. Don't worry too much about getting the perfect naming structure now though, you can return to that later as it is very easy to edit all of these settings in the configuration files.

One you enter a name, or accept the default, you'll be given an example command to obtain temporary credentials for this new profile. Make a note of it.

You can now view the configuration files and see all of the settings you've just entered:

$ cat ~/.aws/credentials

$ cat ~/.aws/config

There is also a cache file created in ~/.aws/sso/cache/ which contains the temporary credentials for the session:

$ ls -al ~/.aws/sso/cache/

Testing the CLI

Before we move on, let's just check what profiles we have available to us:

$ aws configure list-profiles

You should at least see the profile you've just created.

If you have multiple profiles, as may be the case if you have set up CLI previously, you'll either need to add the --profile flag to all of your aws cli commands or set the environment variable AWS_PROFILE. To minimize the amount of typing, we'll set the environment variable.

$ export AWS_PROFILE=[profile-name]

Where [profile-name] is the name of the profile you want to use.

Now type the following command to check that the profile is set:

$ aws sts get-caller-identity

You should see something similar to the following:

{
  "UserId": "AROAXYZ:userabc",
  "Account": "123456789012",
  "Arn": "arn:aws:sts::123456789012:assumed-role/AWSReservedSSO_ReadOnlyAccess_abc123/userabc"
}

This basically tells us who we are. Who is making the request. And so, if all is configured correctly, this is the account we have just configured to use the CLI.

Let's try querying one of our AWS resources, a list of S3 buckets:

$ aws s3 ls

With appropriate permissions, we should see a list of the buckets in the account if there are any, and we can list the files within a bucket:

$ aws s3 ls [bucket-name]

Hopefully that's all working for you. We can also logout of our current profile:

$ aws sso logout

You can log in again to this or any another profiles if we have any, and even be logged in to multiple profiles at the same time:

$ aws sso login --profile [profile-name]

As previously mentioned, we can also ensure future commands use a specific profile without specifying it each time with:

$ export AWS_PROFILE=[profile-name]

That's it. You can return to the beginning of this page for help adding additional profiles if needed. There is no need to read on to the next page, that covers using long term credentials, which is not recommended if SSO as described here is available to you.

Authenticating with Standard IAM Long-Term Credentials (Not Recommended)

Create a new IAM User

Head to the AWS Management Console and navigate to/search for the Identity and Access Management (IAM) dashboard (not to be confused with IAM Identity Center).

1. Select Users from the left hand menu and then click Create user.

2. Type a username (identifying this as a CLI user may be a good idea, e.g. cli-user).

3. Click Next

4. Set your permissions:

   You may already have a permissions in mind for your user, or a group with the appropriate permissions ready to go. In which case set the group or attach policies as needed.

   If you are unsure and just here to learn the process, select Attach existing policies directly, type S3 in the Permissions Policies search box, and select the AmazonS3ReadOnlyAccess policy. We'll test out the CLI by querying S3 later.

5. Select Next and then Create user.

Generate the Access Key

1. Select the user you just created, and click on the Security Credentials tab.

2. Click on the Create access key button.

3. Select the "Command Line Interface" option.

   This screen is here to discourage you from using long-term credentials. As discussed previously, it is not best practice to do so. If you are happy nevertheless, select the Confirmation button at the bottom of the screen.

4. Click Next

5. Add a description.

   Note: Although optional, it's important to have a record of what the access key is for as you will want to ensure any unused keys are removed if no longer needed and to be able to quickly identity them if you were to have and security breach so it is highly recommended to add a description.

6. Click Create access key.

7. Make a more of the access key, and record the secret access key (click to show or copy to clipboard) securely somewhere or download the .csv by clicking on the button.

   Note: You won't be able to retrieve the secret access key after you leave this screen, so make sure you have a note of it. If you lose it, you will need to delete it and create a new one.

8. Click Done

Step 3: Configure AWS CLI with Long-Term Credentials

1. Run Configuration:

In your local shell, type:

$ aws configure

You'll be prompted for the Key ID and Secret Access Key which have just been created:

• AWS Access Key ID: Enter the access key (e.g., AKIA1234567890ABCDEF).
• AWS Secret Access Key: Enter the secret key (e.g., aBcDeFgHiJkLmNoPqRsTuVwXyZ1234567890abcd).

And a default region for your queries, if you wish to enter one:

• Default region name: Set a region (e.g., us-east-1 or eu-west-2)

And a default output format. Leaving this blank will now default to json, I'd recommend explicitly setting it though.

• Default output format: Enter json (or yaml, text).

You should now have two configuration files created, which you may wish to take a look at:

$ cat ~/.aws/credentials

$ cat ~/.aws/config

Testing the Setup

Run these tests to ensure the CLI works with your IAM credentials.

1. Test 1: Check Identity:
   Verify your identity:

$ aws sts get-caller-identity

If your credentials are correct, this should return an object with your user details and you should see your username as part of the Arn value. If not, double check your credentials in ~/.aws/credentials and give it another go.

• Or with a profile:

  aws sts get-caller-identity --profile my-profile

• Example output:

  {
    "UserId": "AKIA1234567890ABCDEF",
    "Account": "123456789012",
    "Arn": "arn:aws:iam::123456789012:user/cli-user"
  }

2. Test 2: List S3 Buckets:

If your assigned the AmazonS3ReadOnlyAccess policy to the account, or another policy allowing read access to S3 buckets, you should now be able to obtain a list of your buckets:

$ aws s3 ls

And files within a bucket:

$ aws s3 ls [bucket-name]

Important Notes

• Remember, long-term credentials don't expire

• If you don't need to continue to use the user/credentials created in this guide, don't forget to delete them in the IAM console

• Consider using IAM Identity Center as an alternative, for improved security (page 2)