What I wish I could have learned before starting using AWS Cognito

What often makes starters a bit confused

In the last article, I mentioned that AWS Cognito may cause some unnecessary confusion to starters. I guess the main reason is because there are two products under the umbrella name of Cognito: Cognito User Pool (CUP) and Cognito Identity Pool (CIP); also, it is true that these two services could overlap a bit in certain (quite common) use cases such as simple API-Gateway authorization.

If you encounter some of the confusion mentioned here, you are not alone. Feel free to ask questions, and I will try to answer them.

What is Cognito User Pool in a 1,000 feet view?

In short, it’s a /signin and /signup authentication endpoint offered by AWS — not a super accurate definition, but my goal here is to give new AWS app developers a good metaphor.

Let’s use the words from AWS Cognito User Pool developer document “User pools are user directories that provide sign-up and sign-in options for your app users.” Essentially,

1. if you come from Django / Express.js / … background, just think of someone has already built a /signin and a /signup endpoint for you (and you don’t need to own / maintain that piece of logic — focus on your business logic!);

   

2. Note that Cognito User Pool can serve as an identity provider, i.e., more than /signin and /signup endpoints;

What is Cognito Identity Pool in a 1,000 feet view?

In short, it is a service that issues temporary AWS credentials to users who have authenticated themselves through an identity provider (IdP), which the Cognito Identity Pool has already established its trust with.

Let’s use the words from AWS Cognito Identity Pool developer document “… federate them with identity providers. With an identity pool, you can obtain temporary, limited-privilege AWS credentials to access other AWS services.” CIP is NOT a user catalog service, and it is NOT an identity provider (IdP) — even though its name is Identity Pool. There are several points to pay attention here.

• “…federate them with identity providers” — this is essentially saying a CIP is NOT an identity provider (IdP), and it needs to be configured to build trust relationship with IdPs (CUP is one kind of IdP).

• “temporary, limited-privilege AWS credentials” — think of that CIP is the service that can issue temporary credentials.

  • You may ask “what are temporary AWS credentials?” Let us have a detour here:

    1. when an AWS account user is created, an Access_Key_ID / Secret_Access_Key will be allocated to that user, which then can be used for situations like programing his AWS account with aws-cli by that user — this is an (non-temporary) AWS credential for a user.

       

    2. A temporary credential is very similar to the above credentials, and it expires after a certain time period (just there an extra session token field).

       

Both CUP and CIP can “federate”, but for different purposes:

CUP — Getting a unified authentication token: We can use Cognito User Pool (CUP) as our “facade” to federate different identity providers (IdPs) — this makes your system behave universally after the authentication process, no matter from what IdP a user signs in. What the client gets are tokens (id_token, access_token, optionally refresh_token) issued from CUP — the client never sees the ‘federated’ IdP’s token.

Figure: The Cognito User Pool ‘federates’ identity providers (for AuthN)

CIP — issuing the AWS credentials by examining tokens issued from different IdP: We can use Cognito Identity Pool (CIP) to federate different identity providers (IdPs) as well. What this architecture does is that a users authenticates with the IdPs, and obtains the token issued from them; then the user sends the token to CIP to obtain the AWS temporary credentials.

Figure: The Cognito Identity Pool federates identity providers (for AuthZ)

Using Cognito User Pool and Cognito Identity Pool together

When we follow most of Cognito tutorials on Internet (for example, Amplify get started) the hidden architecture choice is what I called (Social IdP +) CUP + CIP AuthN and AuthZ stack.

Figure from Amplify Tutorial document: CUP (with Social IdP) + CIP Auth stack

There are a lot of reasons why this stack is the right choice when building applications and it likely fits most of the use cases. For example, if I were building quora.com or instagram from scratch today, I would use this AuthN / AuthZ stack:

• Using CUP ‘federate’ social IdPs to reduce friction of needing to sign-up another app (memorizing another set of password) , yet providing a unified user catalog at the CUP layer;

• Using CIP in the stack to enable features that need direct clients to AWS service interaction, such as photo upload to S3 from the mobile app directly.

But this architecture is not always needed, or sometimes it may not be even the right choice. This is a topic that probably would deserve at least 3-4 hours long discussion — let save that here.

Which architecture should I choose, after all?

In this section, I’d like share some of my experienced use case scenarios — if they happen to sound similar to your use case, please use them as input for you to make your architecture decision.

1. If you just wanted to build a Restful API service behind API-Gateway, a simple Cognito User Pool (with or without social / SAML sign-in) architecture is probably all you need

   • you can simply enable “Cognito User Pool Authorizer” by a few clicks on your API-Gateway (certainly, hopefully later on your DevOps friends will codify your clicks into her infrastructure-as-code stack if you are building production services)

2. If you wanted to build an app that your front-end or mobile app needs to access AWS resources (for example, S3 to upload / display photos) directly, then you probably need to have the CUP (with or without social / SAML sign-in) + CIP

Summary

Cognito has a lot to do with authentication and authorization (AuthN / AuthZ) in AWS ecosystem.

• If you need to enable your client to access AWS resources (beyond API-Gateway / Appsync) directly, you most likely will need Cognito Identity Pool;

• If you wanted to have a low cost, scalable authentication and user catalog service, you probably take a look at Cognito User Pool.

PS: If you like this article, please sign up now so you don’t miss the future issues.

In the meantime, I plan to write one article each week in 2021 to demystify and relate the cloud technology to something we are familiar with — please feel free to tell your friends!