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

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.

AWS SSO makes it easy to centrally manage SSO Access to multiple AWS accounts, moves the authentication to the IdP (Identity Provider) and removes the need for managing static, long-lived credentials.

Prep Steps

In order to take advantage of SSO at the CLI, you’ll first need to gather some information and get your workspace configured.

What you’ll need:

1. Install the AWS CLI
2. Your SSO sign-in URL
3. The region for your SSO env (usually us-east-1)
4. (Optional) The role you want to use for this profile — you may have more than one role assigned to your account (like read and admin), and you’ll need to figure out which one you want to use with the AWS CLI for your given task.

You can configure the AWS CLI profile using SSO in the following two ways:

• 1. Manually, by editing the .aws/config file that stores the named profiles.
• 2. Automatically, using the command aws configure sso

1. Manually, by editing the .aws/config file that stores the named profiles:

• Manual configuration

To manually add IAM Identity Center support to a named profile, you must add the following keys and values to the profile definition in the file ~/.aws/config (Linux or macOS) or %USERPROFILE%/.aws/config (Windows).

sso_start_url : Specifies the URL that points to the organization’s AWS access portal. The AWS CLI uses this URL to establish a session with the IAM Identity Center service to authenticate its users. To find your AWS access portal URL, use one of the following:

• Open your invitation email, the AWS access portal URL is listed.
• Open the AWS IAM Identity Center (successor to AWS Single Sign-On) console at https://console.aws.amazon.com/singlesignon/. The AWS access portal URL is listed in your settings.

sso_start_url = https://my-sso-portal.awsapps.com/start

sso_region : The AWS Region that contains the AWS access portal host. This is separate from, and can be a different Region than the default CLI region parameter.

sso_region = us-west-2

sso_account_id : The AWS account ID that contains the IAM role that you want to use with this profile.

sso_account_id = 123456789011

sso_role_name : The name of the IAM role that defines the user’s permissions when using this profile.

sso_role_name = ReadAccess

The presence of these keys identify this profile as one that uses IAM Identity Center to authenticate the user.

You can also include any other keys and values that are valid in the .aws/config file, such as region, output, or s3. However, you can't include any credential related values, such as role_arn or aws_secret_access_key. If you do, the AWS CLI produces an error.

So a typical IAM Identity Center profile in .aws/config might look similar to the following example.

[profile my-dev-profile]
sso_start_url = https://my-sso-portal.awsapps.com/start
sso_region = us-east-1
sso_account_id = XXXXXXXXXXXX
sso_role_name = readOnly
region = us-west-2
output = json

At this point, you have a profile that you can use to request temporary credentials. However, you can’t yet run an AWS CLI service command. You must first use the aws sso login command to actually request and retrieve the temporary credentials needed to run commands. For instructions, see the next section, Using an IAM Identity Center enabled named profile.

2. Automatically, using the command aws configure sso:

Similar to the aws configure command that creates a new profile in ~/.aws/config with long-lived access keys aws configure sso command creates a new SSO profile.

aws configure sso will prompt you for:

ep@macbook-pro-73 aws % aws configure sso # This is the URL that you defined when you setup the AWSSSO start URL [None]: [https://your-url.awsapps.com/start](https://your-url.awsapps.com/start) # This is the region that you enabled AWS SSO inSSO Region [None]: us-east-1 # This step will take you to the browser and you will have to click login and allow

# This will suggest to choose an account from which are available to youThere are 6 AWS accounts available to you. Using the account ID xxxxxxxxxxxx # This will suggest a role available to you for this accountThe only role available to you is: AdministratorAccess Using the role name "AdministratorAccess" # Optional: you can choose a default regionCLI default client Region [None]: # Optional: you can choose a default output form. You can skip this to use the defaultCLI default output format [None]: # Here pick a name that you will be able to use later as an alias for this account for –profile argumentCLI profile name [AdministratorAccess-XXXXXXXXXX]: cq-dev-admin

That’s it you configured a new profile (in that case named cq-dev-admin) and to test it run the following command:

aws s3 ls --profile cq-dev-admin## wil output available s3 buckets