Exposing Curity Using ngrok

Exposing Curity Using ngrok

OAuth.tools is a handy tool for testing OAuth flows. It’s a public web application that communicates with Curity endpoints.

This isn’t a problem when dealing with installations of Curity that are publicly available over the Internet (for example, AWS, Azure, or GCP). However, when Curity is installed locally, OAuth.tools can’t access the Curity instance directly. It’s also not advisable to open up ports to allow OAuth.tools to reach the Curity instance.

One approach to solve this is to use a reverse proxy. In this article, we describe how to configure Curity on a local system together with ngrok. This will enable your team to use OAuth.tools to test local installations.


Ngrok acts as a reverse proxy. It can expose a local service or port through a publicly available domain name. Depending on your level of service, ngrok will randomly generate a public name for the given session, or, with a paid plan, you can allocate a static name.

Detailed ngrok installation and configuration instructions are available on the ngrok getting started page.

Configure authtoken

Make sure to configure the ngrok authtoken as outlined in the ngrok documentation.

Ngrok Inspection and Status

When ngrok is running, information will be exposed at http://localhost:4040 by default. There are two tabs available: inspect and status. Inspect shows details of the requests and responses going through the proxy — helpful for troubleshooting purposes. Status shows how many tunnels are open, along with other useful metrics.

Configuring Curity

Configuring the Curity Identity Server to work with ngrok is very straightforward. There are three things that you must configure:

  1. Set the correct base URL. This will be the URL of ngrok and not the localhost running Curity.
  2. Disable TLS/SSL for the runtime service. ngrok will terminate TLS, and the communication between ngrok and Curity will be unencrypted. The unencrypted traffic is all on the local system itself. It is possible to use end-to-end TLS when using a ngrok Pro plan.
  3. Enable webfinger. This is not mandatory but will definitely help when testing using OAuth.tools .

To make things easier, we wrote a script for the above configurations. You can download the script here on GitHub. You’ll also find a link to it at the bottom of OAuth.tools .

The Ngrok Script

The ngrok script handles all the configuration aspects above. A couple of things to note in order to run the script:

  • Makes sure that jq is installed (on Mac, brew install jq works).
  • Configure idsh, the Curity shell command, on the PATH.

Configuring OAuth.tools

When you execute the ngrok script, a line in the output will display something like this:

To begin using this, click here: https://oauth.tools#new-env=https://iggbom-curity.ngrok.io/&webfinger=true

By visiting the listed URL in a browser, OAuth.tools will automatically initiate using the exposed ngrok URL and will automatically fetch all the endpoints using webfinger.

Next step is to configure client(s) in OAuth.tools . You can do so manually, but it’s also possible to have the configuration populate automatically when initiated from the Curity Identity Server WebUI. To do so, go to the main page of the client and click Open in OAuth.tools at the top. This will open OAuth.tools and populate the configuration for that specific client.


A local installation of the Curity Identity Server cannot access OAuth.tools unless ports are opened, which would be quite tedious. Instead, you can use a reverse proxy like ngrok to securely expose the runtime endpoints of Curity to access OAuth.tools .

Thankfully, it’s easy to set this up with the Curity Identity Server using the configuration script.