Frontegg SSO (SAML)

TL;DR

To secure access to ngrok with Frontegg Single Sign-On using SAML:

1. Download the IDP metadata
2. Configure ngrok
3. Configure Frontegg
4. Update Frontegg Login Method
5. Test access to ngrok with Frontegg SSO

This article details how to configure Frontegg as the primary Identity Provider for ngrok endpoints. By integrating Frontegg SSO with ngrok, you can:

• Restrict access to ngrok endpoints only to users authenticated via Frontegg
• Use Frontegg security policies and MFA authenticators.
• Use Frontegg's Dashboard to facilitate access to ngrok apps.

Requirements

To configure ngrok tunnels with Frontegg, you must have:

• A Frontegg account with administrative rights to create apps
• An ngrok Enterprise Account with an authtoken or admin access to configure edges with SAML.

Configuration Steps

To integrate ngrok with Frontegg SSO, you will need to:

1. Configure Frontegg with the ngrok app
2. Configure ngrok with the SSO settings provided by Frontegg

Step 1: Download the IDP metadata

1. Access the Frontegg Portal and sign in using your Frontegg administrator account.

2. On the left menu, click your environment under Environments and then click Env settings.

3. On the General Settings page, copy both the Client ID and API Key values.

4. Open a terminal window and run the following command to get an access token:

   curl --request POST \
     --url https://api.frontegg.com/auth/vendor/ \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{"clientId": "CLIENT_ID","secret": "API_KEY"}'

   Note: Replace the following with values:

   • CLIENT_ID: The client ID value you copied before.
   • API_KEY: The API key value you copied before.

5. Copy the value of the token attribute from the response.

6. In the same terminal window, run the following command to download the metadata XML file from Frontegg:

   curl --location --request POST 'https://api.frontegg.com/oauth/resources/configurations/saml/v1/https%3A%2F%2Ftemporary' \
   --header 'frontegg-vendor-host: YOUR_FRONTEGG_HOST_URL' \
   --header 'Authorization: Bearer TOKEN' \
   --header 'Content-Type: application/json' \
   --data-raw '{
      "acsUrl": "https://temporary",
      "entityId": "https://temporary"
   }'

   Note: Replace the following with values copied on previous steps:

   • YOUR_FRONTEGG_HOST_URL: The value of the Domain name from the Env settings > Domains tab.
   • TOKEN: The token you copied before.

7. Copy the response and save it as the idp_metadata.xml file locally on your desktop. Note: The response starts with <EntityDescriptor and ends with </EntityDescriptor>. Anything different may be an error.

Step 2: Configure ngrok

To configure an edge with Frontegg:

1. Access the ngrok Dashboard and sign in using your ngrok account.

2. On the left menu, click Cloud Edge and then click Edges.

3. If you don't have an edge already set to add Frontegg SSO, create a test edge:

   • Click + New Edge.
   • Click Create HTTPS Edge.
   • Click the pencil icon next to "no description", enter Frontegg SSO SAML as the edge name, and click Save.

4. On the edge settings menu, click SAML.

5. On the SAML page, click Begin setup, click Upload XML, and then open the XML metadata file you downloaded from Frontegg (See Download the IdP metadata).

6. Click Save at the top.

7. Copy both the Entity ID and the ACS URL values for later use.

Step 3: Configure Frontegg

1. In the same terminal window in which you ran the previous commands, run the following command to create a SAML configuration related to your ngrok SAML edge:

   curl --location --request POST 'https://api.frontegg.com/oauth/resources/configurations/saml/v1/URL-ENCODED-NGROK-ENTITY-ID' \
   --header 'frontegg-vendor-host: YOUR_FRONTEGG_HOST_URL' \
   --header 'Authorization: Bearer TOKEN' \
   --header 'Content-Type: application/json' \
   --data-raw '{
      "acsUrl": "NGROK_ACS_URL",
      "entityId": "NGROK_ENTITY_ID_URL"
   }'

   Note: Replace the following with the values copied on previous steps:

   • URL_ENCODED_NGROK_ENTITY_ID: URL-Encoded value of the ngrok Entity ID* copied from the edge SAML configuration.
   • YOUR_FRONTEGG_HOST_URL: The value of the Domain name from the Env settings > Domains tab.
   • TOKEN: The Frontegg token you copied before.
   • NGROK_ACS_URL: The value of the ngrok Entity ID copied from the edge SAML configuration.
   • NGROK_ENTITY_ID_URL: The value of the ngrok ACS URL copied from the edge SAML configuration.

Step 4: Update Frontegg Login Method

1. Access the Frontegg Portal and sign in using your Frontegg administrator account.

2. On the left menu, click your environment under Environments, click Authentication, and then click Login method.

3. On the Select your login method page, make sure Hosted login is selected, and click Add new twice.

4. In the first empty field, enter the endpoint URL from your ngrok edge (i.e., https://123456789.ngrok.app/). In the second field, enter the ACS URL from your Edge SAML configuration.

5. Click Save.

Step 5: Start a Tunnel

1. Access the ngrok edges page, click your edge, and then click Start a tunnel.

Note

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

1. Click the copy icon next to the tunnel command.

2. Launch a tunnel:

   • Launch a terminal.
   • Paste the command but replace http://localhost:80 with your localhost app address (i.e., http://localhost:3000).
   • Click Enter and an ngrok tunnel associated with your edge configuration will launch.

3. To confirm that the tunnel is connected to your edge:

   • Return to the ngrok dashboard
   • Close the Start a tunnel and the Tunnel group tabs
   • Refresh the test edge page. Under traffic, You will see the message You have 1 tunnel online. Start additional tunnels to begin load balancing.

4. In the test edge, copy the endpoint URL. (you use this URL to test the Frontegg Authentication)

Grant access to Frontegg users

Create a Frontegg user:

1. On the left menu of the Frontegg Portal, click your environment, click Backoffice, click Accounts, and then click Add New.

2. On the Add new account popup, enter a name for the account, ngrok.com in the Domain field, and then click Save.

3. On the left menu, click Backoffice, click Users, and then click Add New.

4. On the Add new user popup, enter a name and email, select the account you have created, and then click Save. Note: by default value to assign the Admin role to the user

Test the integration

1. In your browser, launch an incognito window.

2. Access your ngrok tunnel (i.e., https://frontegg-sso-test.ngrok.app. Use the copied endpoint URL).

3. You should be prompted to log in with your Frontegg credentials.

4. After logging in, you should be able to see your web app.