Configure the AWS CLI to use IAM Identity Center token provider credentials with automatic authentication refresh

This topic describes how to configure the AWS CLI to authenticate users with the AWS IAM Identity Center (IAM Identity Center) token provider configuration. Using this SSO token provider configuration, your AWS SDK or tool can automatically retrieve refreshed authentication tokens.

When using IAM Identity Center, you can login to Active Directory, a built-in IAM Identity Center directory, or another IdP connected to IAM Identity Center. You can map these credentials to an AWS Identity and Access Management (IAM) role for you to run AWS CLI commands.

Regardless of which IdP you use, IAM Identity Center abstracts those distinctions away. For example, you can connect Microsoft Azure AD as described in the blog article The Next Evolution in IAM Identity Center.

Note

For information on using bearer auth, which uses no account ID and role, see Setting up to use the AWS CLI with CodeCatalyst in the Amazon CodeCatalyst User Guide.

You can use the SSO token provider configuration to automatically refresh authentication tokens as needed for your application, and to use extended session duration options. You can configure this in the following ways:

• Automatically, using the aws configure sso and aws configure sso-session commands. The following commands are wizards that guide you through configuring your profile and sso-session information are the following:

  • Use aws configure sso to create or edit both your config profiles and sso-session sections.

  • Use aws configure sso-session to create or edit only sso-session sections.

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

Prerequisites

• Install the AWS CLI. For more information, see Install or update to the latest version of the AWS CLI.

• You must first have access to SSO authentication within IAM Identity Center. Choose one of the following methods to access your AWS credentials.

I do not have established access through IAM Identity Center

Follow the instructions in Getting started in the AWS IAM Identity Center User Guide. This process activates IAM Identity Center, creates an administrative user, and adds an appropriate least-privilege permission set.

Note

Create a permission set that applies least-privilege permissions. We recommend using the predefined PowerUserAccess permission set, unless your employer has created a custom permission set for this purpose.

Exit the portal and sign in again to see your AWS accounts and options for Administrator or PowerUserAccess. Select PowerUserAccess when working with the SDK. This also helps you find details about programmatic access.

I already have access to AWS through a federated identity provider managed by my employer (such as Azure AD or Okta)

Sign in to AWS through your identity provider’s portal. If your Cloud Administrator has granted you PowerUserAccess (developer) permissions, you see the AWS accounts that you have access to and your permission set. Next to the name of your permission set, you see options to access the accounts manually or programmatically using that permission set.

Custom implementations might result in different experiences, such as different permission set names. If you're not sure which permission set to use, contact your IT team for help.

I already have access to AWS through the AWS access portal managed by my employer

Sign in to AWS through the AWS access portal. If your Cloud Administrator has granted you PowerUserAccess (developer) permissions, you see the AWS accounts that you have access to and your permission set. Next to the name of your permission set, you see options to access the accounts manually or programmatically using that permission set.

I already have access to AWS through a federated custom identity provider managed by my employer

Contact your IT team for help.

Configure your profile with the aws configure sso wizard

To configure both an IAM Identity Center profile and sso-session to your AWS CLI

1. Gather your IAM Identity Center information by performing the following:

   1. In your AWS access portal, select the permission set you use for development, and select the Access keys link.

   2. In the Get credentials dialog box, choose the tab that matches your operating system.

   3. Choose the IAM Identity Center credentials method to get the SSO Start URL and SSO Region values that you need to run aws configure sso.

   4. For information on which scopes value to register, see OAuth 2.0 Access scopes in the IAM Identity Center User Guide.

2. In your preferred terminal, run the aws configure sso command and provide your IAM Identity Center start URL and the AWS Region that hosts the Identity Center directory.

   $ aws configure sso
   SSO session name (Recommended): my-sso
   SSO start URL [None]: https://my-sso-portal.awsapps.com/start
   SSO region [None]: us-east-1
   SSO registration scopes [None]: sso:account:access

3. The AWS CLI attempts to open your default browser and begin the login process for your IAM Identity Center account.

   Attempting to automatically open the SSO authorization page in your default browser.

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

   If the browser does not open or you wish to use a different device to authorize this request, open the following URL:
    
   https://device.sso.us-west-2.amazonaws.com/
   
   Then enter the code:
   
   QCFK-N451

   IAM Identity Center uses the code to associate the IAM Identity Center session with your current AWS CLI session. The IAM Identity Center browser page prompts you to log in with your IAM Identity Center credentials. This gives permissions to the AWS CLI to retrieve and display the AWS accounts and roles that you are authorized to use with IAM Identity Center.

   Note

   The sign in process may prompt you to allow the AWS CLI access to your data. Since the AWS CLI is built on top of the SDK for Python, permission messages may contain variations of the botocore name.

4. The AWS CLI displays the AWS accounts available for you to use. If you are authorized to use only one account, 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 IAM Identity Center.

   There are 2 AWS accounts available to you.
   > DeveloperAccount, [e-mail] (123456789011) 
     ProductionAccount, [e-mail] (123456789022)

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

5. 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, 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 IAM Identity Center.

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

   Use the arrow keys to select the IAM role you want to use and press <ENTER>.

6. Specify 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 following example, the user enters a default Region, default output format, and the name of the profile. If you have a previously existing configuration, 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, this profile becomes the one used whenever you run an AWS CLI command and do not specify a profile name.

7. A final message describes the completed profile configuration.

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

8. This results in creating the sso-session section and named profile in ~/.aws/config that looks like the following:

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

   You can now use this sso-session and profile to request refreshed credentials. Use the aws sso login command to request and retrieve the credentials needed to run commands. For instructions, see Use an IAM Identity Center named profile .

Configure only your sso-session section with aws configure sso-session wizard

The aws configure sso-session command only updates the sso-session sections in the ~/.aws/config file. This command can be used to create or updates your sessions. This is useful if you already have existing configuration settings and would like to create new or edit existing sso-session configuration.

Run the aws configure sso-session command and provide your IAM Identity Center start URL and the AWS Region that hosts the Identity Center directory.

$ aws configure sso-session
SSO session name: my-sso
SSO start URL [None]: https://my-sso-portal.awsapps.com/start
SSO region [None]: us-east-1
SSO registration scopes [None]: sso:account:access

After entering in your information a message describes the completed profile configuration.

Completed configuring SSO session: my-sso
Run the following to login and refresh access token for this session:

aws sso login --sso-session my-sso

Note

If you are signed in to the sso-session you are updating, refresh your token by running the aws sso login command.

Manual configuration using the config file

The sso-session section of the config file is used to group configuration variables for acquiring SSO access tokens, which can then be used to acquire AWS credentials. The following settings are used:

• (Required) sso_start_url

• (Required) sso_region

• sso_account_id

• sso_role_name

• sso_registration_scopes

You define an sso-session section and associate it to a profile. sso_region and sso_start_url must be set within the sso-session section. Typically, sso_account_id and sso_role_name must be set in the profile section so that the SDK can request SSO credentials.

The following example configures the SDK to request SSO credentials and supports automated token refresh:

[profile dev]
sso_session = my-sso
sso_account_id = 111122223333
sso_role_name = SampleRole

[sso-session my-sso]
sso_region = us-east-1
sso_start_url = https://my-sso-portal.awsapps.com/start

This also allows sso-session configurations to be reused across multiple profiles:

[profile dev]
sso_session = my-sso
sso_account_id = 111122223333
sso_role_name = SampleRole

[profile prod]
sso_session = my-sso
sso_account_id = 111122223333
sso_role_name = SampleRole2

[sso-session my-sso]
sso_region = us-east-1
sso_start_url = https://my-sso-portal.awsapps.com/start

However, sso_account_id and sso_role_name aren't required for all scenarios of SSO token configuration. If your application only uses AWS services that support bearer authentication, then traditional AWS credentials are not needed. Bearer authentication is an HTTP authentication scheme that uses security tokens called bearer tokens. In this scenario, sso_account_id and sso_role_name aren't required. See the individual guide for your AWS service to determine if it supports bearer token authorization.

Additionally, registration scopes can be configured as part of a sso-session. Scope is a mechanism in OAuth 2.0 to limit an application's access to a user's account. An application can request one or more scopes, and the access token issued to the application will be limited to the scopes granted. These scopes define the permissions requested to be authorized for the registered OIDC client and access tokens retrieved by the client. The following example sets sso_registration_scopes to provide access for listing accounts/roles:

[sso-session my-sso]
sso_region = us-east-1
sso_start_url = https://my-sso-portal.awsapps.com/start
sso_registration_scopes = sso:account:access

The authentication token is cached to disk under the ~/.aws/sso/cache directory with a filename based on the session name.