Insomnia Core: Testing APIs secured with Auth0

Introduction

After having been a long time Postman user I recently switched to Insomnia Core, a lightweight and simple tool to test REST but also GraphQL and gRPC services.

One of the key capabilities of Insomnia is the support for different authentication methods including AWS IAM, NTLM and OAuth 2.0 (which is technically not authentication 🙃 ). The support for OAuth 2.0 and its different grants makes it extremely easy to test your APIs which are secured with Auth0. Let's take a look.

Client Credentials Grant

A very popular capability in Auth0 is the support for machine-to-machine scenarios with the OAuth 2.0 client_credentials grant. In this example I've created an API in Auth0 (optionally with some scopes) and then I've also created a Machine to Machine application:

This application then needs to be authorized for the API I created:

Similar to Postman it's also possible to create environments with Insomnia, in which you can define all of your settings, secrets, URLs, ... as variables. I've gone ahead and created some variables for my Auth0 account:

{
  "AUTH0_TOKEN_ENDPOINT": "https://sandrino-dev.auth0.com/oauth/token",
  "AUTH0_CLIENT_ID": "xYHne6VBWIhWBzxF4Hy8ZTiDCrex00N3",
  "AUTH0_CLIENT_SECRET": "bNZ2xSbbS3Mvq1ND1xZC0J2zu...",
  "AUTH0_AUDIENCE": "urn:my-api"
}

This then allows me to use these values in my requests without having to copy them all over the place. As a next step Ican enable authentication for my request and configure OAuth 2 with the Client Credentials grant type with the following settings:

• ACCESS TOKEN URL: The /oauth/token endpoint for your Auth0 tenant
• CLIENT ID: The Client ID of your Machine to Machine application
• CLIENT SECRET: The Client Secret of your Machine to Machine application
• HEADER PREFIX: Set to Bearer
• AUDIENCE: The identifier of your API

The Fetch Tokens button can now be used to request a new access_token from Auth0. Once that's done I can call my protected API endpoint:

The Timeline tab allows you to inspect the HTTP request in more detail, including the Authorization header and the access_token which was sent to the API:

Authorization Code Grant

For testing any user based flows you can choose to create a Regular Web Application, a Single Page Application or Native application and also test the authorization_code grant with Insomnia.

In this example I've gone and created a Regular Web Application and an API with Offline Access enabled (for requesting a refresh_token). The Callback URL of the application has to be set to something, so for this test I'm just setting it to http://insomnia

As a next step I've updated the Insomnia Environment to also include the AUTH0_AUTHORIZE_ENDPOINT:

{
  "AUTH0_AUTHORIZE_ENDPOINT": "https://sandrino-dev.auth0.com/authorize",
  "AUTH0_TOKEN_ENDPOINT": "https://sandrino-dev.auth0.com/oauth/token",
  "AUTH0_CLIENT_ID": "DVIiCVJccDTscB1eBFS3BFrQ8JACl3EF",
  "AUTH0_CLIENT_SECRET": "ZLSi5XpuG6YLdryNX2dKsicU1....",
  "AUTH0_AUDIENCE": "urn:my-api"
}

On the request authentication the Authorization Code grant type can now be selected in OAuth 2:

Pay close attention to the following settings:

• REDIRECT URL: Also set to http://insomnia. When you fetch the tokens a browser window will open in which you'll be able to sign in as a user. At the end Auth0 will redirect to http://insomnia where Insomnia will catch that redirect and perform a code exchange.
• SCOPE: You'll want to use the offline_access scope if you need a refresh_token or require any scope for your API.

Clicking Fetch Tokens will open a browser window in which I'm able to sign in and Insomnia will take care of the OAuth 2 dance.

Any subsequent Fetch Tokens will use the refresh_token if it was originally requested using the offline_access scope, so you won't have to login again.

One nice thing here is that Insomnia also supports Refresh Token Rotation, so if your Authorization Server returns a new refresh_token for each exchange.

Resource Owner Password Grant

And finally if you have legacy applications which use the Resource Owner Password Grant you can also use this in Insomnia:

Note that for Auth0 you'll need to configure the credentials to be In Request Body

When using multiple Database Connections in Auth0 you might run into issues because Insomnia won't allow you to define which connection to use. A default Database Connection can be configured in the Auth0 Tenant Settings instead:

✅ Success!

And there we go. Testing APIs which are secured with Auth0 has never been easier! You can even take it one step further and use the Insomnia CLI (inso) to automate your tests.