Legacy non-refreshable configuration for AWS IAM Identity Center

This topic describes how to configure the AWS CLI to authenticate users with AWS IAM Identity Center (IAM Identity Center) to get credentials to run AWS 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 AWS Identity and Access Management (IAM) role where you can 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 configure one or more of your AWS 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.

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.

Automatic configuration for legacy configuration

To configure an IAM Identity Center profile to your AWS CLI

1. 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):
   SSO start URL [None]: https://my-sso-portal.awsapps.com/start
   SSO region [None]:us-east-1

2. The AWS 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 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://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 AWS CLI session. The IAM Identity Center browser page prompts you to sign 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.

3. Next, 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 with this profile. The ">" character on the left points to the current choice. Press ENTER to make your selection.

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

5. The AWS 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 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. 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. 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 Use an IAM Identity Center 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).

• sso_start_url

• sso_region

• sso_account_id

• sso_role_name

You can include any other keys and values that are valid in the .aws/config file, such as region, output, or s3. 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, Use an IAM Identity Center named profile .The authentication token is cached to disk under the ~/.aws/sso/cache directory with a filename based on the sso_start_url.