Getting started with AWS Cognito Identity Pool

Prerequisite:

1. AWS Account
2. Basic knowledge of AWS IAM
3. Basic knowledge of AWS Lambda and API Gateway
4. A little bit of Coding

Terminologies to be familiar with:

1. Identity:- An Identity is something by which you recognize your user throughout the scope of your application. It can be a user’s username, email, mobile number or a UUID you assign to them.
2. Cognito Identity Pool:- An identity pool stores your identities and all the information required to authorize a user. All the identities share the privilege that is assigned to the Identity pool. 
3. Developer Authenticated Identity:- There are some Identity providers like Google, Facebook, etc which a developer can trust. They act as login providers for the application but if the developer doesn’t want to rely on any of them and implement his/her own authentication then the developer will become the login provider and the Identities created under his/her authentication will be called Developer Authenticated Identities.

Introduction

Before I get into Cognito Identity Pool let me tell you why I need it. Once, I got the task of creating AWS IAM Authenticated APIs. The task was quite simple, go to your API Dashboard, select resource and turn on IAM Authorization and voila!!.

At first, I thought the same but if you want your user to use this API and access your AWS resources at the client-side, you will need AWS Credentials – A pair of keys(Access Key and Secret key). You can’t just generate a key from the console for yourself and give them to the client. This way the user will be able to use the key outside of the client application.

You will need to invalidate and new generate key every once in a while to make sure that the keys are not used beside their intended purpose. These keys are called temporary credentials. Fortunately, You do not have to manage the keys as AWS already has some services dedicated to it and one of these services is Cognito. Here is how I used it.

How I resolved it

I created a Cognito Identity Pool to create Developer Authenticated Identities and generated IAM credentials for these Identities. I created Developer Authenticated Identities because my application already had its own authentication process.

But the road to complete the task was not straightforward and I got lost in loads of documentation that I found on AWS Docs and it was hard to follow any tutorial without getting confused. After spending many hours in it, I was finally able to do find the right flow that I can follow.

Goals

1. Create a Cognito Identity Pool.
2. Give the required permission to the Identities belong to this Identity Pool.
3. Create Identity
4. Added IAM Authenticated API using API Gateway then create AWS Lambda function and integrate them.
5. Generate temporary credentials for an Identity and use it to call the API.

Steps to use Cognito Identity Pool

Create a Cognito Identity Pool with Developer Authenticated Identities

Step 1: Create an Identity pool in AWS Cognito. Fill name. Choose Authentication providers ->custom and Enter Developer provider name (test.login for example) which is immutable. Click on the “Create Pool” button.

Add permission for identity

Step 2: Next, AWS will ask us to create two Roles for our Identity pool. One for Authenticated Identities and others for Unauthenticated Identities.
We won’t be able to choose already created roles, we have to create new ones.

Edit the policy document. Add relevant permissions to use AWS services. 
We are adding “execute-api:Invoke” because we going to call IAM authenticated API. We can edit or add policy for roles later.

After completing this you will find yourself on this page which shows you have successfully created your Identity Pool.

Note your Identity Pool Id, we will need it later. Also, select your platform in which your going to do the coding part and see its APIs.

Now comes the coding part. To implement this part you will need to install AWS SDK or you can simply code this in AWS Lambda.

Create an Identity

Step 3: Use getOpenIdTokenForDeveloperIdentity() to get an Identity Id and Token for it. It will create Identity if it doesn’t exist. You will need your AWS credentials to call this API so call it from your application backend.

If you have done everything alright then you will get a response.

Response: {
    Token : [A very long Token],
    IdentityID : us-west-2:[and the rest of it]
}

Identity browser from Identity Pool Dashboard and select this Identity.

Get credentials for the Identity

Step 4: Now you have the user’s Identity Id and a temporary token for it, you can exchange it for temporary AWS Credentials. The AWS STS will provide these AWS Credentials but you don’t have to worry about that because once we call this function, behind the scene, AWS Cognito will get the credentials from STS.

You can give these credentials to a user and can let them access AWS services of your account. These temporary credentials will have all the permissions you have assigned to your Identity pool role. To get temporary credentials you have to call getCredentialsForIdentity() API. You don’t need your AWS Credentials to call this API. For example, If you are building an Android App then you can give IdentityId and Token to frontend and call this API then.

You will get a response like this:-

Response: {
  AccessKeyId: [AccessKeyId],
  SecretKey: [SecretKey],
  SessionToken: [Session Token],
  Expiration: 2018-09-21T11:59:15.000Z
}

Now the user can access your AWS resource, we will get to the part where we will test this by calling an AWS Lambda function through IAM authenticated API and getting a response from it.

Testing

Step 5: Create a Lambda function that can return a simple response like “Hello user”.

Step 6: Create an API then create a method in it and integrate the method with the Lambda function. Go to “Method Request” in your method and turn on “AWS_IAM” authorization. It means only permitted AWS Credential associated with your account can access this method. That is why we generated temporary credentials.

Enable CORS and deploy your API.

Step 7: Now, if we want to call an API, we have to insert AWS SigV4(AWS Signature version ) in our request header. There are various methods of generating the signature. We are going to use a node module AWS4 to generate it and subsequently call the API.

open terminal and run command

npm install aws4

Also install the node module ‘request’ to make an HTTP request by running this command:-

npm install request

Here is how to generate a signature from temporary credentials and use it to make an HTTP request.

Conclusion

If the user is getting the response we are sending from Lambda then it means everything went alright and we can either implement all the coding in our server-side and give temporary credentials to the client or we can implement it in a lambda function. integrate it with an unauthenticated API then have our client call this API to get temporary credentials.

Thank you all for reading this. Please provide your much-needed feedback in the comment section.

useful links:

• Identity Pools (Federated Identities) Authentication Flow
• Cognito Identity Reference for Javascript

Liked what you read? Check out my other blog post on AWS Lambda

Understanding one of the most important AWS services – Lambda