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 miniOrange as the primary Identity Provider for ngrok tunnels using single sign-on (SSO). By integrating miniOrange SSO with ngrok, you can:
  • Restrict access to ngrok tunnels only to users authenticated via miniOrange
  • Use miniOrange security policies and 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

  • Access miniOrange and sign in using your miniOrange administrator account.
  • On the Dashboard page, click Apps on the left menu, click Add Application, click the SAML/WS-Fed tile, and then click the Custom SAML App tile.
  • On the Add App page, enter ngrok SAML in the Custom Application Name field.
  • Click the SSO tab, enter temporary values (such as https://temporary) in both the SP Entity ID or Issuer and the ACS URL fields, and then click Save.

​
2. Download the IdP metadata

  • On the View Apps page, click Select in the ngrok app line, and then click Metadata.
  • On the View IDP Metadata page, click Show Metadata Details, click Download Metadata, and then save the XML file on your desktop.

​
3. 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: 
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.

​
4. Obtain the SP metadata

The SAML action generates your ngrok SP Entity ID and ACS URL based on your endpoint URL. Once you have developer preview access, refer to the SAML action documentation for how to retrieve these values.
  • On the miniOrange Dashboard, click Apps on the left menu, click Select in the ngrok SAML app line, and then click Edit.
  • On the Edit Application page, enter the SP Entity ID and ACS URL from the SAML action documentation (see Obtain the SP metadata) into the corresponding fields.
  • On the Edit Application page, click Save.

​
6. 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 miniOrange authentication.

​
Grant access to miniOrange users

miniOrange allows its users to access SAML-integrated apps. To create a user, follow the instructions below:
  • On the left menu of the miniOrange Dashboard, click Users and then click User List.
  • On the Users page, click Add User, enter values for the Email, Username, First Name, Last Name, and Password fields, and then click Create User.

​
Test the integration

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