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

​
What you’ll need

  • A JumpCloud 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 JumpCloud

  • Access the JumpCloud Console and sign in using your JumpCloud administrator account.
  • On the left menu, click SSO, click Get Started or + Add New Application, and then click Custom SAML App.
  • On the New Application popup, enter ngrok saml in the Display Label field.
  • Click the SSO tab, enter https://ngrok-jumpcloud in the IdP Entity ID field, enter temporary values (such as https://temporary) in both the SP Entity ID and the ACS URL fields, and then click Activate.

​
2. Download the IdP metadata

  • On the SSO page of the JumpCloud Console, click your Custom SAML App, click the SSO tab, click Export 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 JumpCloud: 
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

Retrieve your SP metadata XML generated by the SAML action for your endpoint URL (see SAML action documentation). In the metadata XML, confirm the SP Entity ID and ACS URL values; you upload this XML in the next step when linking JumpCloud with ngrok.
  • Access the JumpCloud Console, click SSO, click your Custom SAML App, click the SSO tab, click Upload Metadata, and then open the XML metadata file you downloaded from ngrok (see Obtain the SP metadata).
  • 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 JumpCloud authentication.

​
Grant access to JumpCloud users

JumpCloud allows administrators to restrict access to SSO apps—such as ngrok—via user group assignments. By default, apps created in JumpCloud have no group assignments; in other words, nobody can use JumpCloud SSO to access ngrok until you assign a group to the app. To assign JumpCloud groups to the ngrok app:
  • On the left menu of the JumpCloud Console, click SSO and click the ngrok custom SAML app you created.
  • On the app popup, click the User Groups tab, click the checkbox of the All Users group, and then click Save. Make sure to add JumpCloud users to this group when you create or manage users that need access to the ngrok app.

​
Test the integration

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