How to set up AWS CLI with AWS Single Sign-On (AWS SSO)

In short: To get access to your AWS Account with the AWS CLI and AWS SSO, you need to install AWS CLI and enable AWS SSO in the AWS Console. After enabling AWS SSO, you create an SSO user with a permission set.

In this guide, you’ll learn how to set up AWS CLI with AWS IAM Identity Center, formerly called AWS Single Sign-On (SSO) in the following 5 steps.

Install the AWS Command line Interface (AWS CLI)

The AWS CLI allows you to interact with AWS services in your terminal. Currently, there are two versions available v1 and v2, but we’re going to install the latter.

With Homebrew we install AWS CLI v2 with the following command:

brew install awscli

To install AWS CLI v2 on other operation systems, visit the AWS docs

You can validate the version by running aws --version:

aws-cli/2.2.5 Python/3.9.5 Darwin/20.4.0 source/x86_64 prompt/off

Configure and enable AWS SSO

To enable AWS SSO you need to follow these steps on your AWS Account:

Log in to the AWS Management Console and visit the AWS SSO Console and choose Enable AWS SSO.

If you have not yet set up AWS Organizations, you will be prompted to create an organization. Choose Create AWS organization to complete this process.

Once you’ve successfully enabled AWS SSO, you’ll see the user portal URL at the bottom of the page, copy yours and save it, because you’ll need it when you’re setting up the AWS profile in the next step.

Create an AWS SSO user

Now you need to create an AWS SSO user, you’ll need that to authenticate against the AWS SSO user portal URL that you copied when you enabled AWS SSO in the previous step.

You create a new AWS SSO user by clicking the “new user” button on the AWS SSO user page in the AWS Console.

Follow the steps in the wizard to complete the creation and you’ll then see the new user pop up (as shown below).

Create a permission set and assign it to the AWS SSO user

The newly created user needs access to your AWS account, therefore you need to assign a permission set to it.

For this example, I created a permission set based on an AWS-managed policy called “PowerUserAccess”. This policy has a very broad range of access, I would advise limiting the permission if you were to implement the SSO user on a production account.

Set up an AWS Profile for the AWS CLI with your AWS SSO configuration

To Set up an AWS Profile for your AWS CLI we’re going to update the ~/.aws/config file (if it doesn’t exist yet, create the file) with the following configuration of our AWS SSO setup:

#######################
####   AWS SSO     ####
#######################

[profile aws-sso-demo-account]
sso_start_url = https://d-936708b7d6.awsapps.com/start
sso_region = eu-west-1
sso_account_id = 012345678910
sso_role_name = PowerUserAccess
region = eu-west-1

Make sure to change the sso_start_url with the URL you obtained when you enable AWS SSO. Replace sso_account_id with your own AWS account id and update sso_role_name with the permission set that you created.

In order to simplify the authentication against your AWS account, we’re going to use a tool called Granted.

This tool allows you to assume IAM roles and access SSO profiles with ease from the command line. Next to that, you can open up multiple web browser sessions simultaneously!

In order to use Granted, you’ll need to install it on your system. Depending on if you’re running Linux, macOS, or Windows the installation goes like this:

# macOS install method:
brew tap common-fate/granted
brew install granted

# Windows install method:
wget https://releases.commonfate.io/granted/v0.9.1/granted_0.9.1_windows_x86_64.zip
msiexec.exe /i https://releases.commonfate.io/granted/v0.9.1/granted_0.9.1_windows_x86_64.zip

# Linux (Ubuntu) install method:
curl -OL releases.commonfate.io/granted/v0.9.1/granted_0.9.1_linux_x86_64.tar.gz
sudo tar -zxvf ./granted_0.9.1_linux_x86_64.tar.gz -C /usr/local/bin/

Login on AWS CLI via AWS SSO to run commands

Now that everything is configured, we can actually log in to the AWS CLI via AWS SSO with Granted.

Run the assume command with the SSO profile name we created earlier in the ~/.aws/config file:

➜ assume aws-sso-demo-account

[✔] [aws-sso-demo-account](eu-west-1) session credentials will expire in 1 hour

As you can see, we’ve successfully assumed the SSO profile in our terminal and we’re ready to use the AWS CLI on our AWS account.

To double-check the validity of the session, you can run the aws sts get-caller-identity command to see your current session details.

~ on aws-sso-demo-account (eu-west-1)

➜ aws sts get-caller-identity
{
    "UserId": "AROAWNK2CITGHESKW3YIE:danny",
    "Account": "012345678910",
    "Arn": "arn:aws:sts::012345678910:assumed-role/AWSReservedSSO_PowerUserAccess_8c1e59bfe711192a/danny"
}

If you’re running it the first time after exporting the profile it will automatically open the browser and will ask you to sign in with the SSO user that you created:

Login on the AWS Console via AWS SSO

If you want to login to the AWS Console instead of using the AWS CLI, then you can run the same assume command, but instead, add the --console argument.

➜ assume --console aws-sso-demo-account

[i] Opening a console for aws-sso-demo-account in your browser..

This will automatically open your default browser window and then start an AWS Console with the chosen AWS profile.

Note: if you want to switch the default browser, then you can run:

➜ granted browser set

? Select your default browser  [Use arrows to move, type to filter]
> Chrome
  Brave
  Edge
  Firefox
  Chromium

Conclusion

In this article you’ve learned how to get access to your AWS Account using AWS SSO by following these steps:

• Enable AWS SSO in the AWS Console
• Create an AWS SSO user with a permission set
• Install AWS CLI and configure a profile