Use an IAM Identity Center named profile - 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).

Use an IAM Identity Center named profile

This topic describes how to use the Amazon CLI to authenticate users with Amazon IAM Identity Center (IAM Identity Center) to get credentials to run Amazon CLI commands.

Note

Whether your credentials are temporary or automatically refreshing depends on how you previously configured your profile.

Prerequisites

You've configured an IAM Identity Center profile. See Configure the Amazon CLI to use IAM Identity Center token provider credentials with automatic authentication refresh and Legacy non-refreshable configuration for Amazon IAM Identity Center for more information.

Signing in and getting credentials

Note

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

After you configure a named profile, you can invoke it to request credentials from Amazon. Before you can run an Amazon CLI service command, you must retrieve and cache a set of credentials. To get these credentials, run the following command.

$ aws sso login --profile my-dev-profile

The Amazon CLI opens your default browser and verifies your IAM Identity Center log in.

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

If you are not currently signed into IAM Identity Center, you must provide your IAM Identity Center credentials.

If the Amazon CLI can't open your browser, it prompts you to open it yourself and enter the specified code.

$ aws sso login --profile my-dev-profile Using a browser, open the following URL: https://device.sso.us-west-2.amazonaws.com/ and enter the following code: QCFK-N451

The Amazon CLI opens your default browser (or you manually open the browser of your choice) to the specified page, and enter the provided code. The webpage then prompts you for your IAM Identity Center credentials.

Your IAM Identity Center session credentials are cached. If these credentials are temporary, it includes an expiration timestamp and when they expire, the Amazon CLI requests you to sign in to IAM Identity Center again.

If your IAM Identity Center credentials are valid, the Amazon CLI uses them to securely retrieve Amazon credentials for the IAM role specified in the profile.

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

You can also specify which sso-session profile to use when logging in using the --sso-session parameter of the aws sso login command.

$ aws sso login --sso-session my-dev-session Attempting to automatically open the SSO authorization page in your default browser. 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/ and enter the following code: QCFK-N451 Successfully logged into Start URL: https://cli-reinvent.awsapps.com/start

Running a command with your IAM Identity Center profile

You can use these credentials to invoke an Amazon 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.

$ aws 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 IAM Identity Center and those cached credentials are not expired, the Amazon CLI automatically renews expired Amazon credentials when needed. However, if your IAM Identity Center credentials expire, you must explicitly renew them by logging in to your IAM Identity Center account again.

$ aws 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.

Signing out of your IAM Identity Center sessions

When you are done using your IAM Identity Center profiles, you can choose to do nothing and let the Amazon temporary credentials and your IAM Identity Center credentials expire. However, you can also choose to run the following command to immediately delete all cached credentials in the SSO credential cache folder and all Amazon temporary credentials that were based on the IAM Identity Center credentials. This makes those credentials unavailable to be used for any future command.

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

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