Mobile Setup with ngrok

Mobile Setup with ngrok

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

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:

./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:

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:

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.

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.