Skip to main content

Documentation Index

Fetch the complete documentation index at: https://ngrok.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

This guide refers to using SSO to authenticate access to your endpoints. You cannot use these instructions to set up SSO for logging into your ngrok account in the dashboard.
This guide walks you through configuring Frontegg as the primary Identity Provider (IDP) for ngrok endpoints using single sign-on (SSO). By integrating Frontegg SSO with ngrok, you can:
  • Restrict access to ngrok endpoints only to users authenticated via Frontegg
  • Use Frontegg security policies and MFA authenticators
  • Use Frontegg’s Dashboard to facilitate access to ngrok apps
The ngrok integration with Frontegg supports SP-Initiated SSO. In this mode, users access ngrok endpoints and are redirected to Frontegg for authentication.

​
What you’ll need

  • A Frontegg account with administrative rights to create apps.
  • An ngrok Pay-as-you-go account with an authtoken or admin access to configure endpoints with OpenID Connect.

​
1. Configure Frontegg

​
Add the ngrok app in Frontegg

  • Access the Frontegg Portal and sign in using your Frontegg administrator account.
  • On the left menu, click the environment you want to integrate with ngrok. In this example, click the Development environment.
  • On the left menu, click Authentication, click Login method, enter the URL https://idp.ngrok.com/oauth2/callback under the Hosted login field, and then click Save.
  • On the left menu, click Env settings, and copy the value of both the Client ID and the API key fields.
  • Click the Domains tab, and copy the value of the Domain name.

​
Grant access to Frontegg users

Create a Frontegg user:
  • On the left menu of the Frontegg Portal, click your environment, click Backoffice, click Accounts, and then click Add New.
  • On the Add new account popup, enter a name for the account, ngrok.com in the Domain field, and then click Save.
  • On the left menu, click Backoffice, click Users, and then click Add New.
  • On the Add new user popup, enter a name, email, select the account you have created, and then click Save. By default, the user is assigned the Admin role.

​
2. Configure ngrok

ngrok can use Frontegg SSO in two ways:
  • From the ngrok CLI (using the --oidc parameter)
  • From the ngrok dashboard

​
Option 1: ngrok CLI

This tutorial assumes you have an app running locally (for example, on localhost:3000) with the ngrok client installed.
  • Launch a terminal.
  • Enter the following command to launch an ngrok tunnel with Frontegg SSO: 
    ngrok http 3000 --oidc=FRONTEGG_OAUTH_URL \
--oidc-client-id=FRONTEGG_CLIENT_ID \
--oidc-client-secret=FRONTEGG_CLIENT_SECRET \
    Replace the following with the values:
    • FRONTEGG_OAUTH_URL: Your Frontegg Domain name URL (for example, https://app-123456.frontegg.com).
    • FRONTEGG_CLIENT_ID: The client ID you copied from Frontegg.
    • FRONTEGG_CLIENT_SECRET: The API key you copied from Frontegg.
    Alternatively, add the --url YOUR_DOMAIN argument to get your custom URL, replacing YOUR_DOMAIN with your URL of preference.
  • Copy the URL available next to Forwarding (for example, https://frontegg-sso-test.ngrok.app).
  • Skip to Step 3.

​
Option 2: Traffic Policy

This tutorial assumes you have an app running locally (for example, on localhost:3000) with the ngrok client installed.
Create a policy.yaml file with the following content, replacing the placeholder values with those copied from Frontegg: 
on_http_request:
  - actions:
      - type: openid-connect
        config:
          issuer_url: 'https://app-123456.frontegg.com'
          client_id: 'YOUR_FRONTEGG_CLIENT_ID'
          client_secret: 'YOUR_FRONTEGG_API_KEY'
          scopes:
            - openid
            - profile
            - email
Launch an ngrok tunnel with this policy: 
ngrok http 3000 --traffic-policy-file policy.yaml --url YOUR_DOMAIN
Copy the URL next to Forwarding (for example, https://frontegg-sso-test.ngrok.app).

​
3. Test the integration

  • In your browser, launch an incognito window.
  • Access your ngrok tunnel (for example, https://frontegg-sso-test.ngrok.app or using the copied endpoint URL).
  • You should be prompted to log in with your Frontegg credentials.
  • After logging in, you should be able to see your web app.