Skip to main content

Azure Active Directory SSO (SAML)

TL;DR

To have ngrok enforce Single Sign-On using SAML with Azure Active Directory (Azure AD):

  1. Create an ngrok Edge
  2. Create an Azure AD 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 Azure AD as an Identity Provider for your ngrok Edge. By integrating Azure AD with ngrok, you can:

  • Restrict access to ngrok tunnels to only users who authenticated via Azure AD
  • Configure Azure AD and ngrok to enforce user and group authorization
  • Use Azure AD's dashboard to facilitate access to ngrok applications

Requirements​

To configure ngrok tunnels with Azure AD, 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 Azure AD 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 Azure Active Directory 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
    <EntityDescriptor xmlns="urn:oasis:names:tc:SAML:2.0:metadata"></EntityDescriptor>

    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 Azure AD with these values later

Step 2: Create an Azure AD application​

  1. Go to your Azure AD 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 Azure AD

    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 (Azure AD 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