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

​
What you’ll need

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

​
1. Configure Descope

​
Add the ngrok app in Descope

  • Open the Descope Console.
  • On the left menu, click Applications, and then click + Application in the top right corner.
  • In the popup window, enter ngrok in the Name field, make sure that OIDC is selected under Authentication protocol, and then click Create.
  • On the ngrok application page, make a note of the Issuer URL.
  • Optional: If you wish to change the Auth Hosting URL to use a different flow for ngrok SSO, you can change that on this page, and click Save.

​
Create a client secret in Descope

  • Go to Access Keys in the Descope Console.
  • Click + Access Key in the top right corner.
  • In the popup window, enter ngrok in the Name field, change the Expiration time to whatever you prefer, and then click Generate Key.
  • Once the Access Key has been created, make a note of it for later.

​
2. Configure ngrok

ngrok can use Descope 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 Descope SSO: 
    ngrok http 3000 --oidc=DESCOPE_ISSUER_URL \
--oidc-client-id=DESCOPE_CLIENT_ID \
--oidc-client-secret=DESCOPE_CLIENT_SECRET \
    Replace the following with values:
    • DESCOPE_ISSUER_URL: This is your Issuer URL that you copied from the Applications page earlier.
    • DESCOPE_CLIENT_ID: This is your Descope Project ID, which can be found under Project Settings in the Descope Console.
    • DESCOPE_CLIENT_SECRET: This is the Descope Access Key that you created from earlier.
    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://descope-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 Descope: 
on_http_request:
  - actions:
      - type: openid-connect
        config:
          issuer_url: 'YOUR_DESCOPE_ISSUER_URL'
          client_id: 'YOUR_DESCOPE_PROJECT_ID'
          client_secret: 'YOUR_DESCOPE_ACCESS_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://descope-sso-test.ngrok.app).

​
3. Test the integration

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