Legacy non-refreshable configuration for Amazon IAM Identity Center (successor to Amazon Single Sign-On) - Amazon Command Line Interface
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Legacy non-refreshable configuration for Amazon IAM Identity Center (successor to Amazon Single Sign-On)

This topic describes how to configure the Amazon CLI to authenticate users with Amazon IAM Identity Center (successor to Amazon Single Sign-On) (IAM Identity Center) to get credentials to run Amazon CLI commands using the legacy method. When using the legacy non-refreshable configuration, you need to manually refresh the token as it periodically expires.

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 Amazon Identity and Access Management (IAM) role that enables you to run Amazon 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.


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

You can configure one or more of your Amazon CLI named profiles to use a role from a legacy IAM Identity Center in the following ways:

  • Automatically, using the aws configure sso command.

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


You must first enable SSO authentication within IAM Identity Center. For details on enabling SSO authentication, see Getting Started in the Amazon IAM Identity Center (successor to Amazon Single Sign-On) User Guide.

Automatic configuration for legacy configuration

To enable an IAM Identity Center enabled profile to your Amazon CLI
  1. Run the aws configure sso command and provide your IAM Identity Center start URL and the Amazon Region that hosts the Identity Center directory.

    $ aws configure sso SSO session name (Recommended): SSO start URL [None]: https://my-sso-portal.awsapps.com/start SSO region [None]:us-east-1
  2. The Amazon CLI attempts to open your default browser and begin the login process for your IAM Identity Center 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 Amazon 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://device.sso.us-west-2.amazonaws.com/ and enter the following code: QCFK-N451

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

  3. Next, the Amazon CLI displays the Amazon accounts available for you to use. If you are authorized to use only one account, the Amazon CLI selects that account for you automatically and skips the prompt. The Amazon accounts that are available for you to use are determined by your user configuration in IAM Identity Center.

    There are 2 Amazon 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.

  4. Next, the Amazon 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 Amazon 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 with this profile and press <ENTER>.

  5. The Amazon CLI confirms your role selection.

    Using the role name "ReadOnly"
  6. Finish the configuration of your profile by specifying the default output format, the default Amazon Web Services 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. 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>

    If you specify default as the profile name, this profile becomes the one used whenever you run an Amazon 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. 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 IAM Identity Center enabled named profile .

Manual configuration for legacy configuration

Automated token refresh isn't supported using the legacy non-refreshable configuration. We recommend using the SSO token 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).

You can include any other keys and values that are valid in the .aws/config file, such as , , or . To prevent errors, don't include any credential related values, such as role_arn or aws_secret_access_key.

The following is an example IAM Identity Center profile in .aws/config:

[profile my-sso-profile] sso_start_url = https://my-sso-portal.awsapps.com/start sso_region = us-west-2 sso_account_id = 111122223333 sso_role_name = SSOReadOnlyRole region = us-west-2 output = json

Your profile for temporary credentials is complete.

To run commands, you must first use the aws sso login command to request and retrieve your temporary credentials. For instructions, see the next section, Using an IAM Identity Center enabled named profile .The authentication token is cached to disk under the ~/.aws/sso/cache directory with a filename based on the sso_start_url.