Exposing Curity Using ngrok

Exposing Curity Using ngrok

On this page

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.

Ngrok doesn't allow anonymous users to serve HTTP traffic in order to mitigate abuse. However, ngrok can still be used with a free account.

  1. Sign-up for a free account.
  2. Download the ngrok agent. You can download the agent directly from the Dashboard available after account sign-up or follow the instructions on the ngrok downloads page.
  3. Connect your account. To authenticate your agent, add your authtoken.

Ngrok installation and configuration

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

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 must be configured that are outlined below. These changes can either be done manually or through a provided script.

  1. Set the correct base URL - This will be the URL ngrok exposes. With a paid ngrok plan this can use a static host name. With a free plan this will be dynamically generated when the ngrok tunnel is started. Ex: https://9c4b3258d9b3.ngrok.io. Set this URL as the Base URL in the Admin UI under System -> General.
  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 configuration changes needed. You can download the ngrok script from GitHub. You'll also find a link to it on the about page of OAuth.tools.

The ngrok script handles all the configuration aspects needed to make the Curity Identity Server work with ngrok. A couple of things to note in order to run the script:

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


Note that running the script locally on a system will not work if Curity is running in docker.

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://demo-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, manually or using the configuration script.