Skip to main content

miniOrange SSO (OpenID Connect)

TL;DR

To secure access to ngrok with miniOrange Single Sign-On using OpenID Connect:

  1. Configure miniOrange SSO
  2. Configure ngrok
  3. Test access to ngrok with miniOrange SSO

This article details how to configure miniOrange as the primary Identity Provider for ngrok tunnels. By integrating miniOrange SSO with ngrok, you can:

  • Restrict access to ngrok tunnels only to users authenticated via miniOrange.
  • Use miniOrange security policies and MFA authenticators.
  • Use miniOrange's Dashboard to facilitate access to ngrok apps.

Supported Features​

The ngrok integration with miniOrange supports:

  • SP-Initiated SSO: In this mode, users access ngrok edges and tunnels and are redirected to miniOrange for authentication.

Requirements​

To configure ngrok tunnels with miniOrange, you must have:

  • a miniOrange account with administrative rights to create apps.
  • an ngrok Enterprise Account with an authtoken or admin access to configure edges with OpenID Connect.

Configuration Steps​

To integrate ngrok with miniOrange SSO, you will need to:

  1. Configure miniOrange with the ngrok app.
  2. Configure ngrok with the SSO settings provided by miniOrange.

Step 1: Configure miniOrange​

  1. Access miniOrange, and sign in using your miniOrange administrator account.

  2. On the Dashboard page, click Apps on the left menu, click Add Application, click the OAUTH/OIDC tile, and then click the OAuth2/OpenID Connect tile.

  3. On the Add App page, enter ngrok OIDC in the Client Name field, enter https://idp.ngrok.com/oauth2/callback in the Redirect-URL field, and then click Save. miniOrange configuration

  4. On the View Apps page, click Select in the ngrok OIDC app line, and then click Edit.

  5. On the Edit Application page, make note of the value of the Client ID field, click the Click to reveal client secret link, and then make note of the value of the Client Secret field.

  6. Click Save.

  7. On the View Apps page, click Select in the ngrok app line, and then click OAuth Endpoints.

  8. On the OAuth Endpoints page, make note of the URL of the Discovery Endpoints field.

Step 2: Grant access to miniOrange users​

miniOrange allows its users to access OIDC-integrated apps. To create a user follow the instructions below.

  1. On the left menu of the miniOrange Dashboard, click Users and then click User List.

  2. On the Users page, click the Add User, enter values for the Email, Username, First Name, Last Name, and Password field, and then click Create User.

Step 3: Configure ngrok​

ngrok can leverage miniOrange SSO in two ways:

  • From the ngrok CLI (using the --oidc parameter)
  • From the ngrok dashboard

Option 1: ngrok CLI​

Note: For this tutorial, we assume you have an app running locally (i.e., on localhost:3000) with the ngrok client installed.

  1. Launch a terminal

  2. Enter the following command to launch an ngrok tunnel with miniOrange SSO:

    ngrok http 3000 --oidc=MINIORANGE_OAUTH_URL \
    --oidc-client-id=MINIORANGE_CLIENT_ID \
    --oidc-client-secret=MINIORANGE_CLIENT_SECRET \

    Note: Replace the following with values:

    • MINIORANGE_OAUTH_URL: The Discovery Endpoint URL you copied from miniOrange, without the /.well-known/openid-configuration sufix (i.e. https://login.xecurify.com/moas/discovery/v2.0/abcd1234).
    • MINIORANGE_CLIENT_ID: The client id you copied from miniOrange.
    • MINIORANGE_CLIENT_SECRET: The client secret you copied from miniOrange.

    Alternatively, add the --domain YOUR_DOMAIN argument to get your a custom URL, replacing YOUR_DOMAIN with your URL of preference.

  3. Copy the URL available next to Forwarding (for example, https://miniOrange-sso-test.ngrok.io).

  4. Skip to Step 3

Option 2: ngrok Edge​

To configure an edge with miniOrange:

  1. Access the ngrok Dashboard and sign in using your ngrok account.

  2. On the left menu, click Cloud Edge and then click Edges.

  3. If you don't have an edge already set to add miniOrange SSO, create a test edge:

    • Click + New Edge.
    • Click Create HTTPS Edge.
    • Click the pencil icon next to "no description", enter Edge with miniOrange SSO OIDC as the edge name and click Save.

  4. On the edge settings menu, click OIDC.

  5. Click Begin setup and enter the following values into the fields: miniOrange config in ngrok

    • Issuer URL: The Discovery Endpoint URL you copied from miniOrange, without the /.well-known/openid-configuration sufix (i.e. https://login.xecurify.com/moas/discovery/v2.0/abcd1234efG).
    • Client ID: The client id you copied from miniOrange.
    • Client Secret: The client secret you copied from miniOrange.

  6. Click Save at the top, and then click the left arrow to go back to the Edges page.

Step 4: Start a Tunnel​

  1. Launch a tunnel connected to your miniOrange edge:
Note

For this step, we assume you have an app running locally (i.e. on localhost:3000) with the ngrok client installed.

  1. Click Start a tunnel.

  2. Click the copy icon next to the tunnel command. tunnel config

  3. Launch a tunnel:

    • Launch a terminal.
    • Paste the command but replace http://localhost:80 with your localhost app address (i.e., http://localhost:3000).
    • Click Enter and an ngrok tunnel associated with your edge configuration will launch.

  4. To confirm that the tunnel is connected to your edge:

    • Return to the ngrok dashboard
    • Close the Start a tunnel and the Tunnel group tabs
    • Refresh the test edge page. Under traffic, You will see the message You have 1 tunnel online. Start additional tunnels to begin load balancing. tunnel confirmed

  5. In the test edge, copy the endpoint URL. (You use this URL to test the miniOrange Authentication) tunnel url

Test the integration​

  1. In your browser, launch an incognito window.

  2. Access your ngrok tunnel using the copied endpoint URL (i.e., https://miniorange-sso-test.ngrok.io).

  3. You should be prompted to log in with your miniOrange credentials.

  4. After logging in, you should be able to see your web app.