This is a complete beginner guide to Amazon Cognito. you’ll learn about User Pools, Identity Pools/Federated Identities, and how to tie them together.
Amazon Cognito is a huge service that offers many authentication and authorization features. Folks tend to get intimidated by the service because not only do you need to learn about Amazon Cognito itself, but also key Authentication and Authorization concepts.
The purpose of this article is to explain the core concepts of Cognito from a beginner perspective. I’ll also give you the TLDR of Authentication and Authorization concepts to round out your understanding.
By the end of this article, you’ll have a solid understanding of what Cognito has to offer and how it can be used to provide user login and access control to AWS services. This article requires zero understanding of how authentiction/authorization concepts work. We’ll start from essentially zero knowledge.
But before we get started with the features, lets quickly overview some important definitions you’ll want to understand. I’ve attempted to classify the definitions into categories that are specific to Cognito, and others that are more generally related to authentication/authorization. Don’t get intimidated if you don’t understand the specifics of these definitions right now – they’ll become more clear throughout the article. Feel free to scroll back to the following section if you need a reminder.
Definitions
General Definitions
- Authentication – Sometimes called authN, Authentication refers to identifying who a user is. This is commonly accomplished with a login form and a username/password. However, a user can be authenticated using other means such as biometrics (such as using your face id when opening your iPhone).
- Authorization – Sometimes called authZ, Authorization refers to what a user has access to.
- Authorization Server – Despite having the name Authorization in it, an Authorization Server is also responsible for Authenticating the user. The Authorization Server generates tokens that are used to identify a user and guard access to backend resources. Authorization servers are also responsible for communicate with other Identity Providers such as Social Sign On providers (Google, Facebook, etc) to authenticate the user.
- OAuth 2.0 – The internet standard protocol for authorizing users to an application. Is a delegated authorization framework that allows users to obtain access to applications.
- OpenID Connect – An extension of OAuth 2.0 that offers authentication (login) features.
- Identity Token – An encoded string, that once decoded contains information about the user (name, email, etc).
- Access Token – An encoded string that is used to validate a user’s access to a resource server.
- Authorization Code – A temporary code (string) that is exchanged for an Access Token. Is used in the Authorization Code flow described below.
- Implicit Grant Flow – An OAuth 2.0 flow used to grant access tokens to users. This flow has security loopholes and should be avoided.
- Authorization Code Flow – An OAuth 2.0 flow used to grant authorization codes to users, which are then exchanged for access tokens. This is an improvement upon the Implicit Grant flow that has a better security profile and fewer loopholes.
- Scopes – Scope is a mechanism in OAuth 2.0 to limit an application’s access to a user’s account.
- Claims – Keys/Values about the user encoded in the Access/ID token.
- Identity Provider – Sometimes called IDP, is a system that provides authentication services to client applications. Cognito is an Identity Provider, as is Google and Facebook when leveraging social sign on.
- Social Sign On – A method to use a third party Identity Provider to access your Cognito User Pool.
Cognito Specific Definitions
- User Pools – A directory of users that sign up either directly through Amazon Cognito or via a Social Sign On Identity Provider (Google, Facebook, etc.).
- Federated Identities / Identity Pools – A method to grant Cognito users temporary access to AWS services.
- Hosted UI – A Cognito provided URL / Website that allows users to sign in to your userpool. Post successful authentication, the user is re-directed back to your website (sometimes called callback URL) with either an Access Token (in the case of Implicit Grant flow) or Authorization Code (in the case of Authorization Grant flow).
- Groups – Users in your Cognito User pool can be tagged as a member of a group that you define (i.e. student, instructor) to grant different levels of access.
- Triggers – Snippets of code that can be run at different stages during the login process (i.e. pre-signup, post-signup, post-login). Triggers can be used to add different functionality such as tagging a user as part of a group after they initially register.
Great – now we have an understanding of some common authentication/authorization and Cognito specific terms. Lets jump into discussing the two key categories of Cognito: User Pools and Federated Identities.
User Pools and Federated Identities (previously known as Identity Pools)
The first thing to understand about Amazon Cognito is that it is broadly separated into two distinct categories – User Pools and Federated Identities (up until recently, referred to as Identity Pools). Lets briefly overview what these two are before diving into the details for both.
User Pools at a High Level
To put it simply, a User Pool is a user directory within Amazon Cognito. It contains records of users that either sign up directly in Amazon Cognito, by Social Identity Providers (Google, Facebook, LWA, etc) or by using legacy SAML Identity Providers. Essentially, think of a user pool as a table of user records. User Pools abstract away the complexity of you as a developer having to store and manage usernames, passwords, logins, sign ups, lost passwords, so on and so forth.
As an administrator of Cognito and owner of a User Pool, you set the rules in terms of which Identity Providers an individual can use to register for your application. Some prefer to only allow users to sign up directly within Cognito. Others prefer to offer social sign on which allows you to delegate authentication to the other service like Google, Facebook, and others. Authentication is achieved through a well known OAuth 2.0 extension called Open ID Connect (OIDC). All well known Social Sign On providers like Google and Facebook support this well known protocol. You can learn more about OIDC here.
Here’s a brief image outlining the role of User Pools in the ecosystem of Amazon Cognito:
The key thing to remember is that User Pools are all about user directories and user management.
Now we have a high level understanding of what User Pools are. Lets briefly cover the other half of Cognito – Federated Identities.
Federated Identities at a High Level
Federated Identities (formerly Identity Pools) are a way for you to uniquely identify users and assign temporary access to AWS resources. With an Identity pool you link your User Pool or other Social Identity providers such as Google/Facebook. Afterwards, you can set up IAM Roles that users will inherit. You can set up some pretty complicated rule matching to specify which users (based on attribute or other means) will get to use which IAM Role. As a quick reminder, IAM stands for Identity and Access Management and is the primary AWS service used to manage access to AWS resources.
You can also have “Guest Users” that use a default role. This allows you to create applications that provide restricted temporary credentials to users that do not yet register for an account in your application.
The thing to remember about Federated Identities is that they are used to manage what AWS resources a user has access to.
Now that we have a high level understanding of the two big concepts in Cognito, lets dive into each of them more in detail – starting with User Pools.
User Pools in Detail
Part of the reason many folks get confused by User Pools is that there are so many additional features that Cognito offers. But don’t fret – we’re going to tackle these one at a time. So let’s go.
Creating a User Pool
The first step to use User Pools is to create one. When you initially set up a User Pool there are many settings you as an administrator need to specify. This includes things like:
- The name of your user pool.
- Which attributes you will require from the user (phone number, email, address, etc).
- Password policies such as minimum length or combinations of numbers and special characters.
- Requiring Multi Factor Authentication (MFA).
- Post User Signup Email Verification.
- Triggers to run Lambda functions at specific points during the user sign up, login, and many other hooks to provide custom functionality.
You can see the multitude of options available when creating a user pool in the screen shot below. Do note that the Cognito UI is currently undergoing an overhaul and may look slightly different depending on when you access it. The below screenshot is the original or legacy version of the UI.
Remember that user pools are simply a collection of users. But what if we want to leverage this pool of users for a multitude of different applications? This is where User Pool Application Clients come into the picture. We discuss them in the next section.
User Pool Application Clients
According to AWS, a Cognito Appliction Client is “an entity within a user pool that has permission to call unauthenticated API operations“. This is a pretty meaningless definition that doesn’t tell you much.
I like to think of an Application Client as a literally a different application that wants to interact with (sign up, login) with your user pool. You may use one app client for your web app, and another for your mobile application.
Application Clients are created by the administrator of the user pool. Post creation, you are provided with a public client secret. This secret is to be used in all API interactions with Cognito. The secret is used to identify the Application Client and distinguish it from others.
Remember that in order for a User Pool to provide any functionality, you need at least one application client. This makes sense since a user pool without a client to interact with it is effectively useless.
You don’t need to know too much more about Application Clients. But if you’re curious you can read more about them here.
Once you set up your first application client, you now have access to the Cognito Hosted UI which is our topic for our next section.
Cognito Hosted UI
The Cognito Hosted UI is a website provided by Amazon Cognito that allows the user to sign up or log in to your User Pool. Each Application Client has their own URL to access your User Pool.
Note that you do not HAVE to use the Hosted UI to log in your users. If you are looking to build a custom front end experience that captures the user’s username and password, you can do so by calling specific Cognito APIs using the AWS Cognito SDK. For example, the InitiateAuth API as documented here allows you to submit user usernames/passwords. This option may seem attractive, but it is much more complicated than using the hosted ui. Reason being, you will need to also implement all other API interactions with cognito such as user sign up, password recovery, changing passwords, etc. All of this is handled for you out of the box if you use the hosted UI.
I would suggest folks avoid this approach unless they have a ton of time on their hands or explicitly require a custom login experience.
Setting up your Hosted UI looks something like the screenshot below
The selected Identity Providers is Cognito User Pool. This means that currently, the only way for the user to sign up and log in with your user pool is by registering as a user directly in your user pool. In other words, Cognito will act as the Identity Provider.
Another important section is the Callback URL and Signout URL. These are whitelisted URL endpoints that should be owned by your application. How the flow essentially works is that once a user successfully signs in with their credentials through the hosted ui, Cognito will redirect them to the specific Callback URL. In this case, www.mywebsite.com/cb. Added to the query string will be either an access token (if using the implicit grant flow which is not a suggested approach) or an authorization code (a more secure approach). Additionally, if you are using the profile and openid scope, you will get access to the user’s profile attributes such as name, email, and address. This data is provided through the Identity Token which is also returned post sign in.
I want to take a quick detour to explain the difference between Implicit Grant and Authorization Code Grant. Note that these are OAuth 2.0 concepts and not something specific to Cognito.
Implicit Grant Flow
In the implicit grant flow, the interaction between client and server takes on this form:
As you can see in the diagram, the flow is quite simple – just replace “Okta” with Cognito. Post authentication, Cognito will redirect your client to your application’s callback URL. Embedded within the query string parameters will be an access token. The access token is then used in subsequent calls to your backend APIs. Your backend then cross-checks the access token with Cognito before letting through the request. The downside of this flow is that the access token is directly embedded in the URL. This is a security vulnerability that makes it possible for bad actors (browser extensions, packet sniffers) to get access to your token. This can be a big danger.
The Implicit Grant is kind of outdated and no longer suggested as an approach to use. Instead, you should consider using the Authorization Code Flow/Grant which is described below.
Authorization Code Flow
The Authorization Code Flow is a slightly more complicated flow but has better security characteristics. An Image that describes (again from Okta) can be seen below.
As you can see, there are more steps here, but the flow is much more secure. PKCE stands for Proof Key Code Exchange. It is a way to ensure that only the user who initially made the authentication request is the one that can exchange the authorization code for an access token. The presence of PKCE effectively guards against packet sniffers and rogue browser extensions.
In this flow, a PKCE code is generated by the client application (a random string). The user is then redirected to authenticate and provides the PKCE code as part of the request. The user signs in and is redirected back to the client application. Where this flow diverges from Implicit Flow is that the user receives an Authorization Code in the query string URL. The client application then calls back to the Authorization Server with the Authorization Code and the PKCE code, and it is exchanged for an Access Token.
The general guidance is to not use the Implicit flow and instead use the Authorization Code Flow.
One final thing to note is that both Access Tokens and Identity Tokens are JWTs or JSON Web Tokens. The tokens themselves are encoded strings that once decoded, contain information about the user’s access rights (for access tokens) or the user’s identity (for identity tokens). You use common libraries to convert JWTs to a JSON object where you can extract the value. For example, here is what a decoded Identity Token looks like:
Note that much of what I’m describing here in terms of Access Tokens, ID Tokens, Authorization Codes, etc etc are related to OAuth 2.0 and OpenID Connect. If you’re confused about any of this, by far the best resource I’ve come across to learn OAuth 2.0 fundamentals is this YouTube video. Since this is an article on Cognito and not so much OAuth 2.0 fundamentals, I’d highly encourage you to watch the above video to clarify how it works.
I hope this brief summary has been useful. Anyways lets move back to the final step of setting up our application client.
The final option is specifying Allowed OAuth Scopes. This simply refers to which details are returned back to the caller via the authentication process. More details on this here.
After Saving your Changes, you now have the ability to actually create the hosted UI as seen below.
You have the ability to specify your URL name that has an AWS related suffix. If you would like to use your own domain name you will have to create a certificate in AWS Certificate Manage (ACM) and link it to Cognito. Note that if you choose the former option, the name of your domain prefix must be globally unique. In other words, two users, even if they have different AWS accounts, cannot share the same domain prefix.
After clicking Save Changes and visiting the UI, you will see a screen like below:
This is a pretty bland looking login experience. Note that you can customize the Hosted UI with custom CSS, logos, and other details through the Cognito Console. This allows you to create a more attractive and familiar experience for your users that is app specific.
Adding Social Sign On Providers to Your Hosted UI
Out of the box, Cognito supports registration and sign in for users that have accounts directly within Cognito. A common sign in method these days is Social Sign On. You can essentially use your Google Account to sign in with a third party application. This method is convenient for the user since it reduces the friction they have to run through to start using your app.
From the cognito perspective, you can add other Social Sign On providers to your user pool through a relatively quick linking process. In fact, I have quite a detailed article on how to associate your User Pool’s app client with Google to provide Social Sign On. You can check it out here.
After you configure your social sign on provider, you’ll have the ability to add it as another Identity Provider as seen below.
And moving back to our hosted UI, you will now have the option to sign in using Google as seen below.
And after the user signs in, here is what shows up in your User Pool directory.
Triggers
Triggers are a feature of Cognito that allow you to run custom code in response to certain sign in / login related events. The feature allows you to link a Lambda function to multiple event types and trigger them when the event in question occurs. Here’s a quick table of some of the event types that are available for your to hook into. You can see the full list here.
There are many purposes to use triggers. But broadly speaking, they allow you to add custom business logic to your application when an event type fires. For example, say we are trying to add an additional piece of data in our claims after the user signs in. We can potentially add a Post Authentication Lambda Trigger and within our Lambda function, call a offsite database. We can then use the response to inject additional metadata into the claims section of the response.
The key to this is that triggers provide an input object to your Lambda object that contains context about the user signing in. The can then update the input event object and return it back in your Lambda function. The full decorated objected will then be provided back to the user in the form of the token. Note that the exact event input/output depends on which event trigger you are hooking into.
You can learn more about what triggers are and how to use them here. They are kind of a more advanced feature but for complicated use cases requiring custom business logic, they may be just what you need.
Groups
Cognito offers you the ability to categorize users into Groups. You can “use groups to create collections of users to manage their permissions or to represent different types of users”. You can also use Groups to base specific business logic in your applications.
You can also tag IAM roles with groups to create specific permissions for sets of users. For example you can create a “Student” group with a restricted permission set. And you can create an “Instructor” group with a more relaxed permission set.
There is also a concept of group Precedence which is a integer value that is used to resolve cases of a user belonging to multiple groups.
One final thing you can do with Groups is communicate membership back to your application through the claims. Sent back to the user through the Access Token is an encoded cognito:groups tag that contains all groups hat the user belongs to. You can use this list to create custom application logic for different types of groups. In later sections, we show how to pick specific IAM roles based on a user’s group membership in order to control different access levels to AWS services. This is covered in the Identity Pool section.
Managing Access to Server Side Resources with User Pools
When initially introducing User Pools at the beginning of this article, we discussed how they can be used to provide user login (authentication). However, User Pools can also be used to manage access to server side resources. In other words, this method allows you to protect your API from being used by users who have not logged in with your Cognito Userpool. This is a very popular requirement for any app that hosts sensitive user data.
There are two key ways to accomplish this depending on your backend setup, so let’s run through them now.
Method 1 – Custom Backend
This method is applicable for those of hosting a traditional backend using a Webserver. Say for example, you’re hosting a REST API on a NodeJS backend that calls a database. Your backend does not necessarily need to be hosted on AWS. You c