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.
- 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.
Configure ngrok
The SAML Traffic Policy action isn’t generally available yet.
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: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,
wwwfor 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.
Update the ngrok configuration with the IdP metadata
- Update the
idp_metadatavalue in yourpolicy.yamlwith the Federation Metadata XML downloaded from Microsoft Entra ID, replacing the placeholder value you set earlier.
Test the integration
This step assumes you have an app running locally (for example, on
localhost:3000) with the ngrok client installed.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.