Introducing cognitocurl. Now you can seamlessly use curl to call AWS API Gateway with AWS Cognito based authorizer

AWS Cognito and API Gateway play really well together — it’s a statement that's really hard to disagree with. Last year we decided to switch all of our API authorizers to Cognito based ones, but then we’ve realized that there is a gap that we need to fill in — how to easily sign calls to API Gateway made from CLI? 🤔 Our frontend applications use AWS Amplify so it was seamless for our frontend team to work with the stack, but our products are used both via CLI/cURL and GUI…

…the solution

Inspired by Amplify I’ve decided to create a CLI tool that takes care of signing in against Cognito User Pool, persists tokens and takes care of token rotation behind the scenes. Having simplicity of future usage in mind, I’ve decided that our tool should add an additional header to the provided curl call.

We love open source at Nordcloud, so we’ve decided to share the tool with the community. You can download it using npm. The source code and documentation are available at https://github.com/nordcloud/cognitocurl.

cognitocurl in action 🔥

How it works

The CLI is built with TypeScript using Oclif. Oclif helped a lot, creating CLI with it is truly straightforward.

Our tool needs to do a few things:

1. Get credentials from the user.
2. Exchange credentials for Cognito tokens.
3. Store the tokens for future usage and refreshing.
4. Add the identity token to provided curl command using -H .

If you want to learn more about tokens in AWS Cognito you can check the AWS documentation.

Long story short — there are two ways of getting tokens from Cognito using this tool: basic one and a complicated one.

The basic one just lets a user enter their login and password, and then uses Amazon Cognito Identity SDK to sign against user pool. Tokens are persisted using node-persist, and the tool takes care of rotating identity token using the refresh token.

The second way is a bit more complicated but allows to use Social SignIn — and it’s based on hosted UI. If the hosted UI flag is provided, our tool creates a Web server that hosts a tiny webpage and a WebSocket. The webpage is responsible for opening hosted UI, and then passing received tokens to the WebSocket. When WS server receives the token it closes itself and the web server.

After getting the token cognitocurl adds Authorization header with an identity token to provided curl command.

The tool is pretty simple but makes using API Gateway and Cognito Authorizer a lot less painful to use with CLI calls. It saved my peers a lot of effort on a day to day basis and hopefully, it can help you as well!

At Nordcloud we are always looking for talented people. If you enjoy reading this post, love open source and would like to work with public cloud projects on a daily basis — check out our open positions here.