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 miniOrange as the primary Identity Provider (IdP) for ngrok endpoints using single sign-on (SSO). By integrating miniOrange SSO with ngrok, you can:
  • Restrict access to ngrok endpoints only to users authenticated via miniOrange
  • Use miniOrange security policies and multi-factor authentication (MFA) authenticators
  • Use miniOrange’s Dashboard to facilitate access to ngrok apps

​
What you’ll need

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

​
1. Configure miniOrange

In the miniOrange admin console, add a custom SAML application for ngrok. For the full steps, see miniOrange’s guide to adding a SAML app. As you configure the app:
  • Enter temporary values such as https://temporary in both the SP Entity ID or Issuer and ACS URL fields. You replace them with ngrok’s values in a later step.
  • Download the miniOrange IdP metadata XML. You use it in the ngrok policy below.

​
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 miniOrange:
The SAML action generates your ngrok service provider (SP) Entity ID and Assertion Consumer Service (ACS) URL from your endpoint URL. See the SAML action documentation for how to retrieve these values.
This step assumes you have an app running locally (for example, on localhost:3000) with the ngrok agent installed.
Start an endpoint with this policy, replacing 3000 with your local web app port and YOUR_DOMAIN with your ngrok domain:
Copy the URL next to Forwarding. You use it to test miniOrange authentication.
  • In the miniOrange admin console, open your ngrok SAML app and click Edit.
  • Replace the temporary values with the SP Entity ID and ACS URL that the SAML action generated.
  • Save the app.
To sign in, use a miniOrange account that is assigned to the app. Create a test user in miniOrange if you need one.

​
4. Test the integration

  • In your browser, launch an incognito window.
  • Access your ngrok endpoint using the copied URL (for example, https://miniorange-sso-test.ngrok.app).
  • When prompted, log in with your miniOrange credentials.
  • After you log in, you see your web app.