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 shows you how to configure Auth0 as the primary Identity Provider for ngrok tunnels using single sign-on (SSO). By integrating Auth0 SSO with ngrok, you can:
  • Restrict access to ngrok tunnels only to users authenticated via Auth0
  • Use Auth0 security policies and MFA authenticators
  • Use Auth0’s Dashboard to facilitate access to ngrok apps
The ngrok integration with Auth0 supports SP-Initiated SSO. In this mode, users access ngrok endpoints and are redirected to Auth0 for authentication.

​
What you’ll need

  • An Auth0 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 Auth0

​
Add the ngrok app in Auth0

  • Access the Auth0 Dashboard and sign in using your Auth0 account.
  • On the left menu, click Applications, click Applications, and then click Create Application.
  • On the Create application popup, enter ngrok oidc in the name field, click the Single Page Web Applications tile, and then click Create.
  • On the ngrok oidc page, click the Settings tab and make note of the Domain, Client ID, and Client Secret values.
  • Enter https://idp.ngrok.com/oauth2/callback in the Allowed Callback URLs field, and enter the URL provided by the ngrok agent to expose your application to the internet in the Application Login URI field (for example, https://myexample.ngrok.app).
  • Click Save Changes.

​
Grant access to Auth0 users

Auth0 allows administrators to restrict access to SSO apps—such as ngrok—via user group assignments. By default, apps created in Auth0 have no group assignments; in other words, nobody can use Auth0 SSO to access ngrok until you assign a group to the app. To assign Auth0 groups to the ngrok app:
  • On the Auth0 Dashboard, click User Management on the left menu, click Users, and then click Create User.
  • Enter an email address in the Email field, provide a Password, and then click Create.

​
2. Configure ngrok

ngrok can work with Auth0 SSO in two ways:
  • From the ngrok CLI (using the --oidc parameter)
  • From the ngrok dashboard

​
Option 1: ngrok CLI

This step assumes you have an app running locally (for example, at localhost:3000) with the ngrok client installed.
  • Launch a terminal.
  • Enter the following command to launch an ngrok tunnel with Auth0 SSO: 
    ngrok http 3000 --oidc=AUTH0_OAUTH_URL \
--oidc-client-id=Auth0_CLIENT_ID \
--oidc-client-secret=Auth0_CLIENT_SECRET \
    Replace the following with values:
    • Auth0_OAUTH_URL: The domain value you copied from Auth0, in the form of a URL (for example, https://dev-abcd1234.us.auth0.com/).
    • Auth0_CLIENT_ID: The client ID you copied from Auth0.
    • Auth0_CLIENT_SECRET: The client secret you copied from Auth0.
    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://auth0-sso-test.ngrok.app).
  • Continue to Test the integration.

​
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 Auth0: 
on_http_request:
  - actions:
      - type: openid-connect
        config:
          issuer_url: 'https://dev-abcd1234.us.auth0.com/'
          client_id: 'YOUR_AUTH0_CLIENT_ID'
          client_secret: 'YOUR_AUTH0_CLIENT_SECRET'
          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://auth0-sso-test.ngrok.app).

​
3. Test the integration

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