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 Descope as the primary Identity Provider for 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 edges and tunnels and are redirected to Descope for authentication.

​
What you’ll need

  • A Descope project with administrative rights and an Enterprise license to be able to create SAML applications.
  • An ngrok Pay-as-you-go account with an authtoken or admin access to configure endpoints with SAML.

​
1. Fetch IdP metadata

​
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 SAML is selected under Authentication protocol, and then click Create.
  • On the ngrok application page, click the download button next to Descope Metadata (XML) to download the Metadata file that you’ll need later on. Make sure to leave this page open.
  • 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.

​
2. Configure ngrok

The SAML Traffic Policy action is currently in developer preview. Request access to configure SAML via Traffic Policy.
Once you have developer preview access, create a policy.yaml file with the following content, replacing YOUR_IDP_METADATA_XML with the IdP metadata XML from Descope: 
on_http_request:
  - actions:
      - type: saml
        config:
          idp_metadata: 'YOUR_IDP_METADATA_XML'
The SAML action generates your ngrok SP Entity ID and ACS URL based on your endpoint URL. Refer to the SAML action documentation for how to retrieve these values to complete your IdP configuration.

​
3. Configure Descope

  • Back in the Descope Console, under your ngrok application, select Enter the connection details manually under Service Provider (SP).
  • Enter the following values in the input fields and save the configuration. Replace the following with the values from the SAML action developer preview docs (see SAML action documentation):
    • NGROK_ACS_URL: The ACS URL generated by the ngrok SAML action for your endpoint.
    • NGROK_ENTITY_ID_URL: The SP Entity ID generated by the ngrok SAML action for your endpoint.

​
4. Start a tunnel

This step assumes you have an app running locally (for example, on localhost:3000) with the ngrok client installed.
Run the following command, replacing 3000 with your local web app port and YOUR_DOMAIN with your ngrok domain: 
ngrok http 3000 --traffic-policy-file policy.yaml --url YOUR_DOMAIN
Copy the URL next to Forwarding. You use this URL to test the Descope authentication.

​
5. Test the integration

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