Announcing the AWS CDK L2 Construct for Amazon Cognito Identity Pools

Today we’re announcing the general availability (GA) of the new Amazon Cognito Identity Pool Level 2 (L2) construct in the AWS Cloud Development Kit (AWS CDK). This construct simplifies the creation and management of identity pools, permissions, and provider integrations by providing intent-based APIs that help users securely manage their authenticated and unauthenticated (guest) users across multiple identity providers (such as Amazon Cognito user pools, social providers like Facebook or Google, OpenID Connect, and more).

Background

The AWS CDK is an open-source software development framework that allows you to define cloud infrastructure using familiar programming languages, such as TypeScript, Python, Java, C#, and Go. The CDK provides various levels of abstraction through Constructs, which are reusable cloud components. Constructs come in three levels:

• L1 constructs: Lowest level of constructs that are automatically generated from AWS CloudFormation resource specifications and offer no abstraction. They provide a one to one mapping to CloudFormation and can be verbose.
• L2 constructs: Curated, high level abstractions that provide sensible defaults and reduce boilerplate code and glue logic with intuitive, intent-based APIs, making infrastructure provisioning more straightforward.
• L3 constructs: Opinionated patterns that encapsulate multiple resources for a specific use case (for example, an entire web application stack).

Previously, developers who wanted to create Cognito Identity Pools in their CDK applications often had to work directly with L1 CloudFormation resources (for example, CfnIdentityPool and CfnIdentityPoolRoleAttachment). This led to verbose code, manual IAM role handling, and less intuitive support for multiple identity providers. The developer was responsible for all of the glue logic required when connecting Identity Pools to other AWS resources , creating IAM roles and policies and provider references on your own, which introduced more complexity.

The new AWS CDK Cognito Identity Pool L2 construct provides the following out of the box:

• An easy way to create and manage authenticated and unauthenticated roles and permissions.
• Built-in support for a variety of identity providers, including social providers, Amazon Cognito user pools, OpenID Connect providers, and others.
• A high level API that reduces the amount of code and complexity required to manage the lifecycle of your identity pool.

By using this new L2 construct, you can focus on developing your application rather than the intricacies of wiring up roles, trust relationships, and provider configurations.

Using the L2

Let’s walk through an example of creating a new Cognito Identity Pool. In addition to creating the Identity Pool, we will create a Amazon DynamoDB table and then we’ll show you how to grant different levels of access for authenticated and unauthenticated users.

Create the DynamoDB Table and Cognito Identity Pool

// Create an identity pool
const identityPool = new IdentityPool(this, 'MyIdentityPool', { identityPoolName: 'MyIdentityPoolName', // Enable unauthenticated identities, disabled by default, // enabling here for demonstration purposes allowUnauthenticatedIdentities: true
}); // Create a new DynamoDB table
const myTable = new TableV2(this, 'MyTable', { partitionKey: { name: 'id', type: AttributeType.STRING }, billing: dynamodb.Billing.onDemand()
});

// Grant read/write access on the table to authenticated users
myTable.grantReadWriteData(identityPool.authenticatedRole); // Grant read only access to unauthenticated (guest) users
myTable.grantReadData(identityPool.unauthenticatedRole);

Let’s highlight a few key points:

1. Single Declaration: By declaring an IdentityPool construct, you automatically get a role for authenticated users and one for unauthenticated users; however, by default, the construct disables guest access and only allows authenticated users. To enable unathenticated identities (guest access), you can set the allowUnauthenticatedIdentities parameter to true.
2. Role and Policy Creation: You don’t have to manually define policies and roles, attach them or configure trust relationships. The L2 construct sets all of this up for you.
3. Providers: You can specify a variety of identity providers (e.g., Google, Facebook, Amazon, Twitter, OpenID Connect, or Cognito user pools) in the authenticationProviders property.
4. Permissions: With the roles exposed (identityPool.authenticatedRole and identityPool.unauthenticatedRole), you can easily grant or restrict fine-grained AWS resource permissions.

Multiple Authentication Providers

When using multiple providers, pass in the relevant configuration details. For example, to enable sign-in via Facebook and Google, you can provide:

const identityPool = new IdentityPool(this, 'MyIdentityPool', { authenticationProviders: { facebook: { appId: 'your-facebook-app-id' }, google: { clientId: 'your-google-client-id' }, },
});

The L2 takes care of generating the correct roles, trust relationships, and identity provider references behind the scenes.

Considerations for Moving to the New Construct

1. Upgrade Path: If you currently use the L1 resources (CfnIdentityPool, CfnIdentityPoolRoleAttachment, etc.), you can migrate to the L2 construct by replacing those L1 declarations with the new IdentityPool L2. Adjust any references to custom roles or attachments to leverage the provided authenticatedRole and unauthenticatedRole properties.
2. Compatibility: Verify the version of your AWS CDK. This L2 is available in newer CDK releases (check the changelog for specifics).
3. Customization: If you have very specific or advanced requirements, like custom IAM conditions or policy statements, you can still refine or override the default roles or attach custom policies using the roles exposed by the L2.
4. Alpha to GA Changes: Verify any potential feature limitations or changes in the API from the alpha to stabilized (GA) versions of the construct.

Conclusion

We’re thrilled to introduce the AWS CDK Cognito Identity Pool L2 construct, which simplifies identity pool setup and management. By leveraging a higher level API, you reduce the complexity of configuring roles and providers for your application’s user base. Whether you’re supporting social logins, guest access, or both, this new construct empowers you to build secure and scalable applications more quickly.

We invite you to get started with the Cognito Identity Pool L2 construct in your AWS CDK projects. For more information and examples, visit the AWS CDK GitHub repository and the official AWS CDK documentation. Feedback is also very important to us, so please create an issue in GitHub for any bugs or feature requests. We look forward to seeing how this new construct helps you streamline your authentication workflows and deliver exceptional user experiences.