Skip to main content
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 (IdP) 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 multi-factor authentication (MFA) authenticators
  • Use the Descope Console to facilitate access to ngrok apps
The ngrok integration with Descope supports service provider-initiated (SP-initiated) SSO. In this mode, users access ngrok endpoints 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. Create a SAML application in Descope

Create a SAML application in Descope and download its IdP metadata by following Descope’s guide, SAML Federated Applications. Name the application ngrok, and download the Descope Metadata (XML) file. You use this metadata in the next step, and you return to the application’s Service Provider (SP) settings in step 3.

​
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:
The SAML action generates your ngrok service provider (SP) Entity ID and Assertion Consumer Service (ACS) URL based on your endpoint URL. Refer to the SAML action documentation for how to retrieve these values to complete your Descope 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. Retrieve both values as described in the SAML action documentation:
    • ACS URL: The ACS URL generated by the ngrok SAML action for your endpoint.
    • Entity ID: The SP Entity ID generated by the ngrok SAML action for your endpoint.

​
4. Start an endpoint

This step assumes you have an app running locally (for example, on localhost:3000) with the ngrok agent installed.
Run the following command, replacing 3000 with your local web app port and YOUR_DOMAIN with your ngrok 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).
  • When prompted, log in with Descope.
  • After you log in, you see your web app.