---
feature name: cognito-construct-library
start date: 27/01/2020
rfc pr: https://github.com/aws/aws-cdk-rfcs/pull/91
related issue: https://github.com/aws/aws-cdk-rfcs/issues/95
---

# Summary

This RFC covers the design of Cognito's CDK construct library coverage.

# Motivation

The CDK constructs that are currently available in the CDK have a decent level
of usage among customers. However, the current usage is via the 'Cfn' constructs
and some basic features available via the `UserPool` construct. The current
implementation of the `UserPool` construct only covers sign in type, user pool
attributes and triggers.

The goal of this RFC is to review the current `UserPool` construct for
ergonomics in usability and extensibility, and to extend the features covered by
the Cognito module.

# Design Summary

This RFC is structured as a working backwards document. Since the focus of this
RFC is to propose the API design, the best way to propose this is to write up
the future user guide of the Cognito module, as if it was complete.

The bulk of the RFC is in the supporting document -
[working-backwards-readme.md](./0095-cognito-construct-library/working-backwards-readme.md)

# Detailed Design

The design creates a couple of entry points for getting into the Cognito APIs.

The first is the `UserPool` construct. The UserPool resource type itself can be
fully configured via its constructor. Further resource types that are based on
user pool, such as, user pool user, client, etc. can configured from this.

The other entry point is the `IdentityPool` construct. Similar to the user pool,
all subsequent resource types that are based on the identity pool, can be
created and configured from this.

# Adoption Strategy

The proposal looks to adhere as close to the existing set of `UserPool` APIs as
possible, so any breaking change to the current APIs is easy and quick to
resolve.

The Cognito module's API stability is 'experimental'. This is a signal to the
users of this module that breaking changes to the API are to be expected.

# Unresolved questions

None.

# Future Changes / Currently out of scope

The following are currently out of scope for this document. Separate issues will
be created for these, that will then be prioritized based on customer requests
and +1s.

- User Pool
  - Import using user pool name
  - Configure SES email actions.
  - ClientMetadata and ValidationData properties in User
  - Support for
    [Clients and HostedUI](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-app-integration.html)
  - [Identity providers](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-identity-federation.html)
  - [Advanced security features](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pool-settings-advanced-security.html)
- Identity Pool
  - External provider - Cognito. This requires CDK coverage of user pool clients
    (above). While it's available via the APIs and CloudFormation resources, it
    is
    [not listed in the documentation](https://docs.aws.amazon.com/cognito/latest/developerguide/external-identity-providers.html)
    as one of the identity providers, so it might not be a sought after feature.
  - External provider - OpenId connect. This requires coverage for OIDC identity
    providers in the IAM module.
  - External provider - SAML. This requires coverage for SAML identity providers
    in the IAM module.
  - Token based access control - Requires Cognito user pool clients (above).

The following are out of scope of this document and are unlikely to be
implemented.

- Identity pool cognito sync. Reason:
  [Documentation](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-sync.html)
  suggests the use of AWS AppSync instead.