> ## 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.

# Secure Your Endpoints with Microsoft Entra ID SSO (SAML)

> Make visitors sign in with Microsoft Entra ID before they can reach your ngrok endpoints, using a SAML app and a Traffic Policy.

> [!NOTE]
>
> 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

> [!NOTE]
>
> The [SAML Traffic Policy action](https://ngrok.com/docs/gateway/traffic-policy/actions/saml.md) 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:

```yaml theme={"theme":{"light":"css-variables","dark":"css-variables"}}
on_http_request:
  - actions:
      - type: saml
        config:
          auth_id: entra-saml
          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](https://ngrok.com/docs/gateway/traffic-policy/actions/saml.md) for how to retrieve these values to complete your IdP configuration.

Launch an ngrok tunnel with this policy:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
ngrok http 3000 --traffic-policy-file policy.yaml --url YOUR_DOMAIN
```

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

> [!NOTE]
>
> 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.