AWS Command Line Interface
User Guide

Configuring the AWS CLI to use AWS Single Sign-On (AWS SSO)

This feature is available only with version 2 of the AWS CLI

The following feature is available only if you use version 2 of the AWS CLI. It isn't available if you run version 1. For information about how to install the preview of version 2, see Installing the AWS CLI version 2.

If your organization uses AWS SSO, then your users can sign in to Microsoft Active Directory or a built in AWS SSO directory and get mapped to an IAM role that enables you to run AWS CLI commands. For more information about AWS SSO, see the AWS Single Sign-On User Guide.

This topic describes how to configure the AWS CLI to authenticate the user with AWS SSO to get short term credentials to run AWS CLI commands. It includes the following sections:

Configuring a Named Profile to Use AWS SSO

You can configure one or more of your AWS CLI named profiles to use a role from AWS SSO You can create and configure multiple profiles and configure each one to use a a different AWS SSO user portal or SSO-defined role.

You can configure the profile in the following ways:

  • Automatically, using the command aws2 configure sso

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

Automatic configuration

You can add an AWS SSO enabled profile to your AWS CLI by running the following command, providing your AWS SSO start URL and the AWS region that hosts the AWS SSO directory.

$ aws2 configure sso SSO start URL [None]: [None]: https://my-sso-portal.awsapps.com/start SSO region [None]:us-east-1

The AWS CLI attempts to open your default browser and begin the login process for your AWS SSO account.

SSO authorization page has automatically been opened in your default browser. Follow the instructions in the browser to complete this authorization request.

If the AWS CLI cannot open the browser, the following message appears with instructions on how to manually start the login process.

Using a browser, open the following URL: https://my-sso-portal.awsapps.com/verify and enter the following code: QCFK-N451

AWS SSO uses the code to associate the AWS SSO session with your current AWS CLI session. The AWS SSO browser page prompts you to sign in with your AWS SSO account credentials. This enables the AWS CLI (thru the permissions associated with your AWS SSO account) to retrieve and display the AWS accounts and roles that you are authorized to use with AWS SSO.

Next, you the AWS CLI displays the AWS accounts available for you to use. If you are authorized to use only one account, then the AWS CLI selects that account for you automatically and skips the prompt. The AWS accounts that are available for you to use are determined by your user configuration in AWS SSO.

There are 2 AWS accounts available to you. > DeveloperAccount, developer-account-admin@example.com (123456789011) ProductionAccount, production-account-admin@example.com (123456789022)

Use the arrow keys to select the account you want to use with this profile. The '>' character on the left points to the current choice. Press ENTER to make your selection.

Next, the AWS CLI confirms your account choice, and displays the IAM roles that are available to you in the selected account. If the selected account lists only one role, then the AWS CLI selects that role for you automatically and skips the prompt. The roles that are available for you to use are determined by your user configuration in AWS SSO.

Using the account ID 123456789011 There are 2 roles available to you. > ReadOnly FullAccess

As before, use the arrow keys to select the IAM role you want to use with this profile. The '>' character on the left points to the current choice. Press ENTER to make your selection.

The AWS CLI confirms your role selection.

Using the role name "ReadOnly"

Now you can finish the configuration of your profile, by specifying the default output format, the default AWS Region to send commands to, and providing a name for the profile so you can reference this profile from among all those defined on the local computer. In the example below, the user enters a default Region, default output format, and the name of the profile. You can alternatively press <ENTER> to select any default values that are shown between the square brackets. The suggested profile name is the account ID number followed by an underscore followed by the role name.

CLI default client Region [None]: us-west-2<ENTER> CLI default output format [None]: json<ENTER> CLI profile name [123456789011_ReadOnly]: my-dev-profile<ENTER>

Note

If you specify default as the profile name then this profile becomes the one used whenever you run an AWS CLI command and do not specify a profile name.

A final message describes the completed profile configuration.

To use this profile, specify the profile name using --profile, as shown: aws2 s3 ls --profile my-dev-profile

The previous example entries would result in a named profile in ~/.aws/config that looks like 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 = 123456789011 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. You must use the aws sso login command to actually request and retrieve the temporary credentials needed to run commands. For instructions, see Using an AWS SSO enabled named profile.

Note

You can also run an AWS CLI command using the specified profile. If you are not currently signed-in to the AWS SSO portal, then it starts the sign-in process for you automatically, just as if you had manually ran the command aws sso login command.

Manual configuration

To manually add AWS SSO 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

The URL that points to the organization's AWS SSO user portal.

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

The AWS Region that contains the AWS SSO 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 AWS SSO 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 AWS SSO 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 = 123456789011 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 AWS SSO enabled named profile.

Using an AWS SSO enabled named profile

Signing in and getting temporary credentials

After you complete the steps in either of the preceding sections, you have a named profile that you can invoke to request temporary credentials from AWS. Before you can run a AWS CLI service command, you must first retrieve and cache a set of temporary credentials. To get these temporary credentials, run the following command:

$ aws2 sso login --profile my-dev-profile

The AWS CLI opens your default browser and verifies your AWS SSO log in.

SSO authorization page has automatically been opened in your default browser. Follow the instructions in the browser to complete this authorization request. Successully logged into Start URL: https://my-sso-portal.awsapps.com/start

If you are not currently signed in to your AWS SSO account, then you must provide your AWS SSO user name and password.

If the AWS CLI can't open your browser, then you are prompted to open it yourself and enter the specified code.

$ aws2 sso login --profile my-dev-profile Using a browser, open the following URL: https://my-sso-portal.awsapps.com/verify and enter the following code: QCFK-N451

The AWS CLI opens your default browser (or you manually open the browser of your choice) to the specified page, and enter the provided code. The web page then prompts you for your AWS SSO credentials.

Your AWS SSO session credentials are cached and include an expiration time stamp. When the credentials expire, the AWS CLI requests you to sign in to AWS SSO again.

If your AWS SSO credentials are valid then the AWS CLI uses them to securely retrieve AWS temporary credentials for the IAM role specified in the profile.

Welcome, you have successfully signed-in to the AWS-CLI.

Running a command with your AWS SSO enabled profile

You can use these temporary credentials to invoke a AWS CLI command with the associated named profile. The following example shows that the command was run under an assumed role that is part of the specified account.

$ aws2 sts get-caller-identity --profile my-dev-profile { "UserId": "AROA12345678901234567:test-user@example.com", "Account": "123456789011", "Arn": "arn:aws:sts::123456789011:assumed-role/AWSPeregrine_readOnly_12321abc454d123/test-user@example.com" }

As long as you signed in to AWS SSO and those cached credentials are not expired, the AWS CLI automatically renews expired AWS temporary credentials when needed. However, if your AWS SSO credentials expire, then you must explicitly renew them by logging in to your AWS SSO account again.

$ aws2 s3 ls --profile my-sso-profile Your short-term credentials have expired. Please sign-in to renew your credentials SSO authorization page has automatically been opened in your default browser. Follow the instructions in the browser to complete this authorization request.

You can create multiple AWS SSO enabled named profiles that each point to a different AWS account or role. You can also use the aws sso login command on more than one profile at a time. If any of them share the same AWS SSO user account, you must login to that AWS SSO user account only once and then they all share a single set of AWS SSO cached credentials.

# The following command retrieves temporary credentials for the AWS account and role # specified in one named profile. If you are not yet signed in to AWS SSO or your # cached credentials have expired, it opens your browser and prompts you for your # AWS SSO user name and password. It then retrieves AWS temporary credentials for # the IAM role associated with this profile. $ aws2 sso login --profile my-first-sso-profile # The next command retrieves a different set of temporary credentials for the AWS # account and role specified in the second named profile. It does not overwrite or # in any way compromise the first profile's credentials. If this profile specifies the # same AWS SSO portal, then it uses the SSO credentials that you retrieved in the # previoius command. The AWS CLI then retrieves AWS temporary credentials for the # IAM role associated with the second profile. You don't have to sign in to # AWS SSO again. $ aws2 sso login --profile my-second-sso-profile # The following command lists the Amazon EC2 instances accessible to the role # identified in the first profile. $ aws2 ec2 describe-instances --profile my-first-sso-profile # The following command lists the Amazon EC2 instances accessible to the role # identified in the second profile. $ aws2 ec2 describe-instances --profile my-second-sso-profile

Signing out of your AWS SSO sessions

When you are done using your AWS SSO enabled profiles, 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 in the SSO credential cache folder as well as all AWS temporary credentials that were based on the AWS SSO credentials. This makes those credentials unavailable to be used for any future command.

$ aws2 sso logout Successfully signed out of all SSO profiles.

If you later want to run commands with one of your AWS SSO enabled profiles, you must again run the aws sso login command (see the previous section) and specify the profile you want to use.