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.

Components

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:

ScriptDescription
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

Prerequisites

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

PrerequisiteDescription
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. Once you log into ngrok and verify your email address, copy the authtoken for your account. You can create additional authtokens in the ngrok Dashboard.
  3. The ngrok agent has commands for installing and editing your local ngrok configuration file. Run ngrok config add-authtoken <AUTHTOKEN> to create a configuration file with your authtoken added.
  4. To edit the config file further, use the command ngrok config edit to open the ngrok configuration or open the ngrok configuration file (~/.ngrok2/ngrok.yml) in your favorite editor. Add the following contents after your authtoken and version:
yaml
12345
console_ui: false
tunnels:
curity:
proto: http
addr: 8443

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

bash
1
ngrok start curity

If you’d like to use a static domain each time, you can add it to the configuration file as well.

yaml
12345
tunnels:
curity:
proto: http
addr: 8443
domain: cute-speedy-deer.ngrok-free.app

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:

bash
1
./start-idsvr.sh

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

bash
123
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 https://baa467f55bc7.eu.ngrok.io. 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:

bash
12
USE_NGROK=false
BASE_URL=http://10.0.2.2:8443

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

bash
12
USE_NGROK=false
BASE_URL=http://192.168.0.4:8443

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.

Conclusion

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.

Join our Newsletter

Get the latest on identity management, API Security and authentication straight to your inbox.

Start Free Trial

Try the Curity Identity Server for Free. Get up and running in 10 minutes.

Start Free Trial