AWS CDK Cognito (v1)

1.204.0 · maintenance · verified Fri Apr 17

The `aws-cdk-aws-cognito` library provides AWS Cloud Development Kit (CDK) constructs for defining AWS Cognito resources programmatically. This specific package and version (1.204.0) are part of the AWS CDK v1 ecosystem, where construct libraries for individual AWS services were distributed as separate PyPI packages. AWS CDK generally follows a rapid release cadence, often with weekly or bi-weekly updates aligning with new AWS service features and bug fixes.

Common errors

```
ModuleNotFoundError: No module named 'aws_cdk.aws_cognito'
```
cause The `aws-cdk-aws-cognito` package (for v1) or `aws-cdk-lib` (for v2) is not installed, or the Python environment is not configured correctly.

fix For AWS CDK v1, run `pip install aws-cdk-aws-cognito`. For AWS CDK v2 (recommended for new projects), run `pip install aws-cdk-lib`.
```
AttributeError: module 'aws_cdk.aws_cognito' has no attribute 'UserPool'
```
cause This typically indicates a version mismatch where an older version of the `aws-cdk-aws-cognito` package is installed, or an incorrect import path (e.g., trying to import a v2 construct into a v1 environment or vice-versa).

fix Verify your `aws-cdk-aws-cognito` package version using `pip show aws-cdk-aws-cognito`. Ensure it's compatible with your CDK CLI version. If migrating to v2, ensure `aws-cdk-lib` is installed and imports are `from aws_cdk.aws_cognito import UserPool` or `import aws_cdk.aws_cognito as cognito`.
```
User: arn:aws:iam::xxxxxxxxxxxx:user/YourUser is not authorized to perform: cognito-idp:CreateUserPool on resource: arn:aws:cognito-idp:us-east-1:xxxxxxxxxxxx:userpool/*
```
cause The IAM user or role used to deploy the CDK stack lacks the necessary permissions to create or modify Cognito User Pool resources.

fix Grant the `cognito-idp:CreateUserPool`, `cognito-idp:UpdateUserPool`, `cognito-idp:DeleteUserPool` (and related `cognito-idp:*`) permissions to the IAM identity performing the `cdk deploy`. Ensure `iam:PassRole` is also present if using Lambda triggers.
```
Error: The stack named 'MyCognitoStack' is not in a 'REVIEW_IN_PROGRESS' state.
```
cause This is a generic CloudFormation error often seen when trying to update a stack that previously failed or was manually modified out-of-band, preventing CDK from applying changes.

fix Manually delete the failed CloudFormation stack from the AWS Console if it's stuck, then retry `cdk deploy`. Alternatively, if the resource causing the issue can be identified, import it into the stack state if manual changes were made (more advanced).

Warnings

breaking AWS CDK v1 (where this package resides) is no longer actively developed with new features. AWS CDK v2 consolidates all official construct libraries into a single `aws-cdk-lib` package. Projects should migrate to v2 for new features, bug fixes, and security updates.
Fix: Migrate your CDK application to v2. Install `aws-cdk-lib` instead of individual service packages. Adjust imports from `from aws_cdk import aws_cognito` to `from aws_cdk import aws_cognito as cognito` (or similar for specific symbols from `aws_cdk.aws_cognito`). Refer to the official AWS CDK v1 to v2 migration guide.
deprecated Individual `aws-cdk-aws-*` packages are functionally deprecated for new development. While existing v1 applications using them will continue to work, new applications should use `aws-cdk-lib`.
Fix: Start new projects with `aws-cdk-lib` (AWS CDK v2). For existing v1 projects, plan a migration to v2 to leverage ongoing support and new features.
gotcha Deploying Cognito resources often requires specific IAM permissions that might not be included in default CDK deployment roles, especially for custom attributes, lambda triggers, or advanced settings.
Fix: Ensure the IAM user/role executing `cdk deploy` has sufficient permissions (e.g., `cognito-idp:*`, `iam:PassRole` for lambda triggers, etc.). Check CloudFormation event logs for specific permission errors. Consider granting `AdministratorAccess` temporarily for initial deployment and then narrowing down permissions.
gotcha When integrating Lambda functions as Cognito User Pool triggers, the User Pool requires explicit permission to invoke the Lambda function. For custom Lambda resource policies, ensure the User Pool ARN is correctly configured.
Fix: Use the `add_trigger` method on the `UserPool` construct, which automatically handles the necessary permissions. If manually configuring, ensure `lambda.CfnPermission` is created allowing `cognito-idp.amazonaws.com` to invoke the Lambda.

Install

pip install aws-cdk-aws-cognito==1.204.0 Install specific version (AWS CDK v1)

Imports

UserPool
wrong:
```
from aws_cdk_aws_cognito import UserPool
```
correct:
```
from aws_cdk import aws_cognito as cognito
# then use cognito.UserPool(...)
```
CDK construct libraries are typically imported from the `aws_cdk` namespace, not directly from their PyPI package name. The `aws_cognito` alias is common practice.
UserPool
wrong:
```
from aws_cdk_aws_cognito.aws_cognito import UserPool
```
correct:
```
from aws_cdk.aws_cognito import UserPool
```
Direct import of specific classes from the `aws_cdk.aws_cognito` module is also common.

Quickstart

This quickstart demonstrates how to define a basic AWS Cognito User Pool and a User Pool Client using `aws-cdk-aws-cognito` within an AWS CDK v1 application. It sets up email as a sign-in alias, requires email verification, and enforces a strong password policy. The User Pool ID and Client ID are exported as CloudFormation outputs.

import aws_cdk as cdk
from aws_cdk import aws_cognito as cognito
from constructs import Construct

class MyCognitoStack(cdk.Stack):
    def __init__(self, scope: Construct, id: str, **kwargs) -> None:
        super().__init__(scope, id, **kwargs)

        # Create an AWS Cognito User Pool
        user_pool = cognito.UserPool(self, "MyApplicationUserPool",
            user_pool_name="MyWebAppUsers",
            sign_in_aliases=cognito.SignInAliases(email=True),
            standard_attributes=cognito.StandardAttributes(
                email=cognito.StandardAttribute(required=True, mutable=True)
            ),
            auto_verify=cognito.AutoVerifiedAttrs.EMAIL,
            password_policy=cognito.UserPoolPasswordPolicy(
                min_length=8,
                require_lowercase=True,
                require_uppercase=True,
                require_digits=True,
                require_symbols=True
            )
        )

        # Create a User Pool Client for web applications
        user_pool_client = cognito.UserPoolClient(self, "MyWebAppClient",
            user_pool=user_pool,
            generate_secret=False, # Typically False for client-side applications
            supported_identity_providers=[
                cognito.UserPoolClientIdentityProvider.COGNITO
            ]
        )

        cdk.CfnOutput(self, "UserPoolIdOutput", value=user_pool.user_pool_id)
        cdk.CfnOutput(self, "UserPoolClientIdOutput", value=user_pool_client.user_pool_client_id)

# Instantiate the CDK App and Stack
app = cdk.App()
MyCognitoStack(app, "MyCognitoV1Stack")
app.synth()

view raw JSON →