How to set up AWS CLI with AWS Single Sign-On (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 Single Sign-On (SSO) in the following 5 steps:

1. Install AWS CLI
2. Enable AWS SSO
3. Create an AWS SSO user
4. Create a permission set and assign it to the AWS SSO user
5. Set up AWS Profile for AWS CLI with AWS SSO configuration
List AWS SSO sessions
Sign out of AWS SSO session

Install 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

Enable AWS SSO

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

Enable AWS Single Sign-On in the AWS SSO Console

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.

Create AWS Organizations in the AWS SSO Console

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.

AWS SSO enabled page with user portal url

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've copied when you've 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).

AWS SSO Console user set up page with newly created user

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.

Give AWS SSO user access on your AWS account through permission sets

Set up AWS Profile for AWS CLI with 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]
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
output = json

[profile aws-sso-demo-cli]
region = eu-west-1
credential_process = /usr/local/bin/aws-vault exec aws-sso-demo --json

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.

As you can see, AWS Vault is used to handle the credential process. Currently, a lot of SDKs and tools don't support AWS SSO by default in AWS CLI v2. Therefore we use AWS Vault to bridge the gap and retrieve temporary credentials that are supplied by AWS SSO. To install AWS Vault on your, run the following command:

brew install --cask aws-vault

Now that everything is configured, we can actually login to the AWS CLI via AWS SSO with AWS Vault. First export the SSO profile in your terminal that we created in the ~/.aws/config file:

export AWS_PROFILE=aws-sso-demo-cli

When we run AWS commands in the terminal it will automatically use the profile that we exported in the shell. To verify we can successfully run AWS commands, type the following in your terminal:

aws sts get-caller-identity

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:

AWS SSO sign-in page

and after that, it validates your sign on and you can return to your terminal. You should see that AWS returned the identity of your AWS SSO user.

~ on aws-sso-demo-cli (eu-west-1)
➜ aws sts get-caller-identity
{
    "UserId": "AROAWNK2CITGHESKW3YIE:danny",
    "Account": "012345678910",
    "Arn": "arn:aws:sts::012345678910:assumed-role/AWSReservedSSO_PowerUserAccess_8c1e59bfe711192a/danny"
}

List AWS SSO sessions

If you're using multiple AWS SSO sessions in your CLI, you can list which sessions are active with the following command:

➜ aws-vault list
Profile          Credentials        Sessions
=======          ===========        ========
aws-sso-demo      -                  -
aws-sso-demo-cli  -                  sso.GetRoleCredentials:3h59m47s

As you can see, the session aws-sso-demo-cli expires in 3h59m47s. This is defined in the permission set that we created for the AWS SSO user. The default AWS SSO session duration is 1 hour and can be set up to 12 hours.

Sign out of AWS SSO session

When you are done using your AWS SSO profile, you can choose to do nothing and let the AWS temporary credentials and your AWS SSO credentials expire. However, you can also choose to run the following command to immediately delete all cached credentials from the secure keystore:

aws-vault clear

👋 Enjoyed this article? Reach out in the comments below or on Twitter to let me know what you think of it.