Curity mobile setup with ngrok

Mobile Setup with ngrok

On this page

The Exposing Curity via ngrok article showed how to expose a local instance of the Curity Identity Server to the internet, then connect to it using OAuth Tools. In this article we will show how ngrok can help to enable a productive developer setup when getting started with mobile OAuth.

Mobile OAuth Setup

Developers usually use a Docker setup when first running the Curity Identity Server, and we will show how to expose its endpoints as internet SSL URLs. This enables any device or simulator to easily connect to the OAuth endpoints over a trusted https connection.


Code Example Scripts

The code examples provided in Mobile Guides can be quickly run in an end-to-end manner via helper scripts in their root folder:

start-idsvr.shDeploys a preconfigured Curity Identity Server to Docker and exposes it via an ngrok URL
stop-idsvr.shFrees Docker resources and stops the ngrok tunnel


Before running the above scripts, ensure that the following components are installed on the development computer:

license.jsonA license file for the Curity Identity Server must be copied into the code example root folder
Docker DesktopDocker will be used to host a preconfigured instance of the Curity Identity Server
ngrokThe ngrok component must be installed on the local PC
jqThe jq tool must be installed on the local PC, since it is used by the above scripts

Ngrok account

In order to mitigate abuse, ngrok requires you to sign up for a free account. To start using ngrok locally, follow these steps.

  1. Install the ngrok agent using the package manager for your operating system, e.g., by running brew install ngrok on macOS. See the ngrok downloads page for full details.
  2. Generate an authtoken for your account.
  3. Create a configuration file ~/ngrok2/ngrok.yml, with basic contents:
authtoken: xxx
console_ui: false
region: eu
proto: http
addr: 8443

You can then start ngrok with the following command to forward traffic to port 8443 on your local machine:

ngrok start curity

If you have a paid plan you can define a static domain instead of being assigned a random one on every run:

proto: http
addr: 8443

Free Community Edition

Curity Identity Server has a free community edition and you can get a license file from the developer portal by signing up with your GitHub account.

Deploy the Curity Identity Server

After cloning the mobile code example you want to run, execute its start-idsvr script:


The script will create an ngrok URL using the following commands and then provide this as an input argument to the Curity Identity Server:

ngrok http 8443 -log=stdout &
sleep 5
export RUNTIME_BASE_URL=$(curl -s http://localhost:4040/api/tunnels | jq -r '.tunnels[] | select(.proto == "https") | .public_url')

The result will be that the Curity Identity Server runs at a base URL such as This can then also be applied to the code example configuration to provide a full working setup.

Run the Mobile App

The code example can then be run by opening its folder in Xcode or Android Studio, then pointing it to a device or emulator to build and run the code. Each mobile code example article will provide details on the specific configuration and any user login details.

Alternative Docker URLs

If required you can avoid using ngrok and provide your own URL for the local Curity Identity Server, by editing the script and setting USE_NGROK=false. The below script configuration references the local Docker container using the Android value for the host computer:


An equivalent connection for iOS would instead use the local computer's IP address.


Note that both of these configurations result in the Docker container using HTTP URLs when getting started, to avoid initial SSL trust problems.

Final URLs

Eventually of course you will complete mobile OAuth flows in your own apps and use real internet hosting for the Curity Identity Server, where OAuth endpoints use SSL certificates from a trusted issuer.


The ngrok tool can be useful when first working with mobile OAuth solutions and managing connectivity from a development computer. Curity mobile code examples can be run in this manner to provide a productive initial setup.