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.
# Configure security credentials for the AWS CDK CLI
When you use the AWS Cloud Development Kit (AWS CDK) to develop applications in your local environment, you will primarily use the AWS CDK Command Line Interface (AWS CDK CLI) to interact with AWS. For example, you can use the CDK CLI to deploy your application or to delete your resources from your AWS environment.
To use the CDK CLI to interact with AWS, you must configure security credentials on your local machine. This lets AWS know who you are and what permissions you have.
To learn more about security credentials, see [AWS security credentials](https://docs.aws.amazon.com/IAM/latest/UserGuide/security-creds.html) in the *IAM User Guide*.
## Prerequisites
Configuring security credentials is part of the *getting started* process. Complete all prerequisites and previous steps at [Getting started with the AWS CDK](getting-started.md).
## How to configure security credentials
How you configure security credentials depends on how you or your organization manages users. Whether you use AWS Identity and Access Management (IAM) or AWS IAM Identity Center, we recommend that you use the AWS Command Line Interface (AWS CLI) to configure and manage security credentials for the CDK CLI. This includes using AWS CLI commands like `aws configure` to configure security credentials on your local machine. However, you can use alternative methods such as manually updating your `config` and `credentials` files, or setting environment variables.
For guidance on configuring security credentials using the AWS CLI, along with information on configuration and credential precedence when using different methods, see [Authentication and access credentials](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-authentication.html) in the * AWS Command Line Interface User Guide*. The CDK CLI adheres to the same configuration and credential precedence of the AWS CLI. The `--profile` command line option takes precedence over environment variables. If you have both the `AWS_PROFILE` and `CDK_DEFAULT_PROFILE` environment variables configured, the `AWS_PROFILE` environment variable takes precedence.
If you configure multiple profiles, you can use the CDK CLI ` --profile ` option with any command to specify the profile from your `credentials` and `config` files to use for authentication. If you don’t provide `--profile`, the `default` profile will be used.
If you prefer to quickly configure basic settings, including security credentials, see [Set up the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-quickstart.html) in the * AWS Command Line Interface User Guide*.
Once you’ve configured security credentials on your local machine, you can use the CDK CLI to interact with AWS.
## Configure and manage security credentials for IAM Identity Center users
IAM Identity Center users can authenticate with IAM Identity Center or manually by using short-term credentials.
**Authenticate with IAM Identity Center to generate short-term credentials**
You can configure the AWS CLI to authenticate with IAM Identity Center. This is the recommended approach of configuring security credentials for IAM Identity Center users. IAM Identity Center users can use the AWS CLI `aws configure sso` wizard to configure an IAM Identity Center profile and `sso-session`, which gets stored in the `config` file on your local machine. For instructions, see [Configure the AWS CLI to use AWS IAM Identity Center](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-sso.html) in the * AWS Command Line Interface User Guide*.
Next, you can use the AWS CLI `aws sso login` command to request refreshed credentials. You can also use this command to switch profiles. For instructions, see [Use an IAM Identity Center named profile](https://docs.aws.amazon.com/cli/latest/userguide/sso-using-profile.html) in the * AWS Command Line Interface User Guide*.
Once authenticated, you can use the CDK CLI to interact with AWS for the duration of your session. For an example, see [Example: Authenticate with IAM Identity Center automatic token refresh for use with the AWS CDK CLI](configure-access-sso-example-cli.md).
**Manually configure short-term credentials**
As an alternative to using the AWS CLI and authenticating with IAM Identity Center, IAM Identity Center users can obtain short-term credentials from the AWS Management Console and manually configure the `credentials` and `config` files on their local machine. Once configured, you can use the CDK CLI to interact with AWS until your credentials expire. For instructions, see [Authenticate with short-term credentials](https://docs.aws.amazon.com/cli/latest/userguide/cli-authentication-short-term.html) in the * AWS Command Line Interface User Guide*.
## Configure and manage security credentials for IAM users
IAM users can use an IAM role or IAM user credentials with the CDK CLI.
**Use an IAM role to configure short-term credentials**
IAM users can assume IAM roles to gain additional (or different) permissions. For IAM users, this is the recommended approach since it provides short-term credentials.
First, the IAM role and user’s permission to assume the role must be configured. This is typically performed by an administrator using the AWS Management Console or AWS CLI. Then, the IAM user can use the AWS CLI to assume the role and configure short-term credentials on their local machine. For instructions, see [Use an IAM role in the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-role.html) in the * AWS Command Line Interface User Guide*.
**Use IAM user credentials**
To avoid security risks, we don’t recommend using IAM user credentials since they provide long-term access. If you must use long-term credentials, we recommend that you [update access keys](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#rotate-credentials) as an IAM security best practice.
IAM users can obtain access keys from the AWS Management Console. You can then use the AWS CLI to configure long-term credentials on your local machine. For instructions, see [Authenticate with IAM user credentials](https://docs.aws.amazon.com/cli/latest/userguide/cli-authentication-user.html) in the * AWS Command Line Interface User Guide*.
## Additional information
To learn about the different ways that you can sign in to AWS, depending on the type of user you are, see [What is AWS Sign-In?](https://docs.aws.amazon.com/signin/latest/userguide/what-is-sign-in.html) in the * AWS Sign-In User Guide*.
For reference information when using AWS SDKs and tools, including the AWS CLI, see the [AWS SDKs and Tools Reference Guide](https://docs.aws.amazon.com/sdkref/latest/guide/overview.html).
# Example: Authenticate with IAM Identity Center automatic token refresh for use with the AWS CDK CLI
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:
+ Prerequisites required to get set up with AWS and install our starting CLI tools. For more information, see [Prerequisites](configure-access.md#configure-access-prerequisites).
+ IAM Identity Center has been set up by our organization as the method of managing users.
+ At least one user has been created in IAM Identity Center.
## 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](https://docs.aws.amazon.com/cli/latest/userguide/sso-configure-profile-token.html) 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):
SSO start URL [None]:
SSO region [None]:
SSO registration scopes [sso:account:access]:
```
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
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]:
CLI default output format [None]:
CLI profile name [123456789011_FullAccess]:
```
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
```
After completing this step, our `config` file will look like the following:
```
[profile ]
sso_session =
sso_account_id = <123456789011>
sso_role_name =
region =
output =
[sso-session ]
sso_region =
sso_start_url =
sso_registration_scopes =
```
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](https://docs.aws.amazon.com/cli/latest/userguide/sso-using-profile.html) 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
```
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
Stack CdkAppStack
Hold on while we create a read-only change set to get a diff with accurate replacement information (use --method=template 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
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
```