Skip to main content
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.

Microsoft Entra ID SSO (SAML)

TL;DR

To have ngrok enforce Single Sign-On using SAML with Microsoft Entra ID:

  1. Create an ngrok Edge
  2. Create a Microsoft Entra ID application
  3. Update the ngrok Edge with the IdP metadata
  4. Test your integration
  5. Bonus: configure ngrok to enforce authorization based on Azure groups

This article details how to configure Microsoft Entra ID as an Identity Provider for your ngrok Edge. 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

Requirements​

To configure ngrok tunnels with Microsoft Entra ID, you must have:

  • an ngrok Enterprise Account with an authtoken or admin access to configure edges with SAML
  • a Microsoft Azure account with access to an Microsoft Entra ID tenant

Step 1: Create an ngrok Edge​

  1. Go to the ngrok dashboard

  2. Click Universal Gateway > Edges

  3. Create an Edge:

    1. Click New Edge
    2. Click HTTPS Edge
    3. Click the Pencil Icon next to "no description". Enter Edge With Microsoft Entra ID SSO as the Edge name and click Save

  4. Configure the SAML module for this Edge:

    1. On the Routes section, click SAML
    2. Click Begin setup
    3. In the Identity Provider section, copy the following XML as a placeholder into the input box
    Loading…

    img/1-3.png

    1. Click Save

    2. Note that ngrok has now generated values for the fields in the Service Provider section. You will need to configure Microsoft Entra ID with these values later

Step 2: Create an Microsoft Entra ID application​

  1. Go to your Microsoft Entra ID tenant in Azure

  2. Create an enterprise application

    1. Starting from the sidebar, in the Manage section, click Enterprise Applications > New application
    2. Give your application a name (eg www for a website client). Click Create

    img/2-2.png

  3. To assign users/groups for this application, in the Getting Started section, click 1. Assign users and groups > Add user/group

  4. Set up single sign on with SAML

    1. In the Getting Started section, click on the box titled 2. Set up single sign on > SAML
    2. Configure SAML. In the Basic SAML Configuration box click Edit

    img/2-4.png

    1. Add Identifier (Entity ID) and Reply URL (Assertion Consumer Service URL) values using the previously the ngrok generated Entity ID and ACS URL

    img/2-4b.png

    1. Click Save
    2. Download the Metadata XML. In the SAML Certificates box > Token signing certificate section > click Download for the Federation Metadata XML

    img/2-4c.png

Step 3: Update the ngrok Edge with the IdP metadata​

  1. Back in the ngrok dashboard for your Edge's SAML configuration, upload the XML file generated by Microsoft Entra ID

    img/3-1.png

  2. Click Save

Step 4: Test the integration​

Note

For this step, we assume you have an app running locally (i.e. on localhost:3000) with the ngrok client installed.

  1. Launch a tunnel connected to your configured Edge

  2. On your Edge's page, in the Routes section, click Start a tunnel

    img/4-1.png

  3. Copy the tunnel command

    img/4-1b.png

  4. Launch a terminal and paste the command, replacing http://localhost:80 with your local web app address (e.g., http://localhost:3000)

  5. Hit Enter to launch the tunnel

  6. Confirm that the tunnel is connected to your edge

    1. Return to the ngrok dashboard
    2. Close the Start a tunnel and the Tunnel group drawers
    3. Refresh the Edge page
    4. In the Routes section > Traffic section you will see the message You have 1 tunnel online. Start additional tunnels to begin load balancing.

    img/4-2.png

  7. Copy the ngrok url on the Endpoints section

  8. Access your Edge application

    1. In your browser, launch an incognito window
    2. Access your ngrok tunnel via your copied URL
    3. You should be prompted to log in with your Microsoft credentials
    4. After login, you should be able to see the application

Bonus: Configure ngrok to enforce authorization based on Azure groups​

  1. In Azure, configure the SAML response to include group claims. In the Attributes & Claims box click Edit

    img/5-1.png

  2. Click Add a group claim > Advanced options > Customize the name of the group claim

  3. Set the name of the group claim to groups. This specific value is required for ngrok

    img/5-3.png

  4. Click Save

  5. Go to your group page and copy the object Id (Microsoft Entra ID returns group object Ids in the group claim)

    img/5-5.png

  6. Configure ngrok to enforce group authorization. In ngrok on your Edge's page, in the Authorization section, update the groups input with your Azure group object Id (NOT group name) values

    img/5-6.png

  7. Access your Edge application

    1. In your browser, launch an incognito window
    2. Access your ngrok tunnel via your copied URL
    3. You should be prompted to log in with your Microsoft credentials
    4. Only users assigned to the authorized groups will have access to the application