GraphQL with Insomnia and AWS Cognito authentication

Insomnia is a free client that allows to perform HTTP and GraphQL requests.

Cognito is the AWS service that handles authentication for your users and applications.

If you work with GraphQL and Cognito authentication you might have faced some configuration pain when testing out your queries and mutation.

One option you have is to manually add an Authentication token in your requests but, considering that token needs to be updated each time it expires, this might be a very demanding task.

Another option is to use a very useful Insomnia plugin to setup the authentication process without the need to handle tokens directly as explained here below.

1. Insomnia plugin

First, you need to install the plugin that will handle authentication for you.

In Insomnia click on Preferences -> Plugins. Search and install insomnia-plugin-aws-cognito-token

Insomnia plugin installation

Update June, 2020

With some version of Insomnia you might get an error when installing the plugin:

Yarn error warning insomnia-plugin-aws-cognito-token > amazon-cognito-identity-js > buffer@4.9.1: This version of 'buffer' is out-of-date. You must update to v4.9.2 or newer
warning insomnia-plugin-aws-cognito-token > aws-sdk > buffer@4.9.1: This version of 'buffer' is out-of-date. You must update to v4.9.2 or newer

You can use the workaround described HERE until the issue is fixed

2. Setup environment

Next, you need to setup some environment variables.

When dealing with several APIs that require different authentications within the same workspace it is good to configure different environments.

To do so, click on the Environment tab and select Manage Environments

Create Environment

Base environment is used to store variables that are always available regardless of which sub-environment is active. This is useful for storing default or fallback values.

In this case, let’s create a Sub Environment.

Private environments have the advantage that when you export your data, the value of variables you setup will not be exported and will not be visible to others. So, let’s create a private environment (E.g.: Users API).

You will need to configure here the variables need for Cognito authentication:

{
 “USERNAME”: “my_username”,
 “PASSWORD”: “my_password”,
 “COGNITO_USER_POOL_ID”: “pool_id”,
 “COGNITO_APP_CLIENT_ID”: “client_id”
}

USERNAME and PASSWORD are the credentials of your Cognito user

COGNITO_USER_POOL_ID and COGNITO_APP_CLIENT_ID are the ones related to your Cognito user pool and app clients within that pool (you can also create a new one)

3. Create GraphQL queries and mutations

1. Create a new directory (E.g.: Users APIs)
2. Create your first query within that directory (E.g.: getUser)
3. Select the environment that you created in the previous step (E.g. Users API)

Graph QL setup

Now click with the right button on the directory and setup the environment that will applies to all the queries/mutations within that dir.

Here is where you are going to setup a variable that will be used by the Authentication for your Graphql operations. Let’s call it COGNITO_TOKEN.

Click on the suggestion AWS Cognito Token. This is thanks to the plugin we installed.

You will get a warning since you have not setup the configuration yet. Click on the warning and configure all the required fields using the Environment Variables you previously setup.

Once you are done and everything is ok you will see that a token is generated in the Live Preview section

4. Configure request Authorization header

Create the Authorization header for your request and set as value the COGNITO_TOKEN

That’s it! You can now perform your queries and mutations forgetting about authentication.

If you need to use a different Cognito user pool for other requests, just create a new directory and configure the COGNITO_TOKEN under its environment.