Example: Authenticate with IAM Identity Center automatic token refresh for use with the AWS CDK CLI

This is the AWS CDK v2 Developer Guide. The older CDK v1 entered maintenance on June 1, 2022 and ended support on June 1, 2023.

This is the AWS CDK v2 Developer Guide. The older CDK v1 entered maintenance on June 1, 2022 and ended support on June 1, 2023.

In this example, we configure the AWS Command Line Interface (AWS CLI) to authenticate our user with the AWS IAM Identity Center token provider configuration. The SSO token provider configuration lets the AWS CLI automatically retrieve refreshed authentication tokens to generate short-term credentials that we can use with the AWS Cloud Development Kit (AWS CDK) Command Line Interface (AWS CDK CLI).

Prerequisites

This example assumes that the following prerequisites have been completed:

Step 1: Configure the AWS CLI

For detailed instructions on this step, see Configure the AWS CLI to use IAM Identity Center token provider credentials with automatic authentication refresh in the AWS Command Line Interface User Guide.

We sign in to the AWS access portal provided by our organization to gather our IAM Identity Center information. This includes the SSO start URL and SSO Region.

Next, we use the AWS CLI aws configure sso command to configure an IAM Identity Center profile and sso-session on our local machine:

$ 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 [sso:account:access]: <ENTER>

The AWS CLI attempts to open our default browser to begin the login process for our IAM Identity Center account. If the AWS CLI is unable to open our browser, instructions are provided to manually start the login process. This process associates the IAM Identity Center session with our current AWS CLI session.

After establishing our session, the AWS CLI displays the AWS accounts available to us:

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

We use the arrow keys to select our DeveloperAccount.

Next, the AWS CLI displays the IAM roles available to us from our selected account:

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

We use the arrow keys to select FullAccess.

Next, the AWS CLI prompts us to complete configuration by specifying a default output format, default AWS Region, and name for our profile:

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

The AWS CLI displays a final message, showing how to use the named profile with the AWS CLI:

To use this profile, specify the profile name using --profile, as shown:

aws s3 ls --profile my-dev-profile

After completing this step, our config file will look like the following:

[profile my-dev-profile]
sso_session = my-sso
sso_account_id = 123456789011
sso_role_name = fullAccess
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

We can now use this sso-session and named profile to request security credentials.

Step 2: Use the AWS CLI to generate security credentials

For detailed instructions on this step, see Use an IAM Identity Center named profile in the AWS Command Line Interface User Guide.

We use the AWS CLI aws sso login command to request security credentials for our profile:

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

The AWS CLI attempts to open our default browser and verifies our IAM log in. If we are not currently signed into IAM Identity Center, we will be prompted to complete the sign in process. If the AWS CLI is unable to open our browser, instructions are provided to manually start the authorization process.

After successfully logging in, the AWS CLI caches our IAM Identity Center session credentials. These credentials include an expiration timestamp. When they expire, the AWS CLI will request that we sign in to IAM Identity Center again.

Using valid IAM Identity Center credentials, the AWS CLI securely retrieves AWS credentials for the IAM role specified in our profile. From here, we can use the AWS CDK CLI with our credentials.

Step 3: Use the CDK CLI

With any CDK CLI command, we use the --profile option to specify the named profile that we generated credentials for. If our credentials are valid, the CDK CLI will successfully perform the command. The following is an example:

$ cdk diff --profile my-dev-profile
Stack CdkAppStack
Hold on while we create a read-only change set to get a diff with accurate replacement information (use --no-change-set to use a less accurate but faster template-only diff)
Resources
[-] AWS::S3::Bucket amzn-s3-demo-bucket amzn-s3-demo-bucket5AF9C99B destroy

Outputs
[-] Output BucketRegion: {"Value":{"Ref":"AWS::Region"}}


✨  Number of stacks with differences: 1

When our credentials expire, an error message like the following will display:

$ cdk diff --profile my-dev-profile
Stack CdkAppStack

Unable to resolve AWS account to use. It must be either configured when you define your CDK Stack, or through the environment

To refresh our credentials, we use the AWS CLI aws sso login command:

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