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 Microsoft Entra ID as an Identity Provider for your ngrok endpoints using single sign-on (SSO). By integrating Microsoft Entra ID with ngrok, you can:
  • Restrict access to ngrok tunnels to only users who authenticated via Microsoft Entra ID
  • Configure Microsoft Entra ID and ngrok to enforce user and group authorization
  • Use Microsoft Entra ID’s dashboard to facilitate access to ngrok applications

What you’ll need

  • An ngrok Pay-as-you-go account with an authtoken or admin access to configure endpoints with SAML.
  • A Microsoft Azure account with access to a Microsoft Entra ID tenant.
1

Configure ngrok

The SAML Traffic Policy action isn’t generally available yet.
The auth_id value in the following policy names this SAML configuration and must not be empty. Once you have early access, create a policy.yaml file with the following content, replacing YOUR_IDP_METADATA_XML with the IdP metadata XML from Microsoft Entra ID:
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.Launch an ngrok tunnel with this policy:
Copy the URL next to Forwarding. You use this URL to test the integration.
2

Create a Microsoft Entra ID application

  • Go to your Microsoft Entra ID tenant in Azure.
  • Create an enterprise application:
    • Starting from the sidebar, in the Manage section, click Enterprise Applications > New application.
    • Give your application a name (for example, www for a website client). Click Create.
  • To assign users/groups for this application, in the Getting Started section, click 1. Assign users and groups > Add user/group.
  • Set up single sign-on with SAML:
    • In the Getting Started section, click the box titled 2. Set up single sign on > SAML.
    • Configure SAML. In the Basic SAML Configuration box, click Edit.
    • Add Identifier (Entity ID) and Reply URL (Assertion Consumer Service URL) values using the previously generated ngrok Entity ID and ACS URL.
    • Click Save.
    • Download the Metadata XML. In the SAML Certificates box > Token signing certificate section, click Download for the Federation Metadata XML.
3

Update the ngrok configuration with the IdP metadata

  • Update the idp_metadata value in your policy.yaml with the Federation Metadata XML downloaded from Microsoft Entra ID, replacing the placeholder value you set earlier.
4

Test the integration

This step assumes you have an app running locally (for example, on localhost:3000) with the ngrok client installed.
Run: ngrok http 3000 --traffic-policy-file policy.yaml --url YOUR_DOMAIN
  • Access your ngrok tunnel via your forwarding URL.
  • In your browser, launch an incognito window.
  • You should be prompted to log in with your Microsoft credentials.
  • After logging in, you should be able to see the application.

Bonus: Configure ngrok to enforce authorization based on Azure groups

  • In Azure, configure the SAML response to include group claims. In the Attributes & Claims box, click Edit.
  • Click Add a group claim > Advanced options > Customize the name of the group claim.
  • Set the name of the group claim to groups. This specific value is required for ngrok.
  • Click Save.
  • Go to your group page and copy the object ID (Microsoft Entra ID returns group object IDs in the group claim).
  • Configure ngrok to enforce group authorization. In your Traffic Policy, update the SAML action configuration to include your Azure group object ID (NOT group name) values in the authorization settings.
  • Access your application:
    • In your browser, launch an incognito window.
    • Access your ngrok tunnel via your copied URL.
    • You should be prompted to log in with your Microsoft credentials.
    • Only users assigned to the authorized groups have access to the application.