Skip to main content

Okta SSO (SAML)

TL;DR

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

  1. Configure Okta SSO
  2. Configure ngrok
  3. Test access to ngrok with Okta SSO

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

  • Restrict access to ngrok tunnels only to users authenticated via Okta
  • Use Okta security policies, MFA authenticators — including Okta Verify, FastPass, and FIDO2 — and ThreatInsights to control access to ngrok tunnels.
  • Use Okta's Dashboard to facilitate access to ngrok apps.

Requirements​

To configure ngrok tunnels with Okta, you must have:

  • an Okta 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 Okta SSO, you will need to:

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

Step 1: Configure Okta​

Add the ngrok App in Okta​

  1. Access your Okta Dashboard as an administrator and then click Admin.
  2. Click Application > Applications .
  3. Click Create App Integration,
  4. Select SAML 2.0, and then click Next.
  5. Enter the Application label — this is the app name that will be displayed in the okta dashboard for end users — and click Next.
  6. Enter in temporary values for "Single sign on URL" and "Audience URI" and select "EmailAddress" for "Name ID format" and then click "Next".
    1. Single sign-on URL: https://temporary
    2. Audience URI (SP Entity ID): https://temporary
    3. Name ID format: Email
  7. Select I’m an Okta customer adding an internal app and click Finish.
  8. Click Done.
  9. Under the Sign On tab of the ngrok application, copy the Client ID and Client Secret. These values will be used at ngrok to complete the configuration.

Download the IdP metadata​

  1. Navigate to the Sign On Tab on the new app and click on Actions under the Active SHA-2 certificate and select View IdP metadata. The metadata will open in a new tab. view xml metadata
  2. In the new tab, Select Save As from the File menu to save your metadata.xml file for uploading into ngrok in a later step. download xml

Grant access to Okta people and groups​

Okta allows administrators to restrict access to SSO apps — such as ngrok — via assignments. By default, apps created in Okta have no assignments — in other words, nobody can use Okta SSO to access ngrok until you assign them to the app. To assign Okta users and groups to the ngrok app:

  1. Navigate to the Assignments Tab.
  2. Use the Assign button to associate groups and users with the ngrok app. To test the SSO with ngrok, make sure you're assigned to the app.

Step 2: Configure ngrok​

ngrok Edge​

To configure an edge with Okta:

  1. Go to dashboard.ngrok.com.

  2. Click Universal Gateway > Edges

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

    • Click New Edge
    • Click HTTPS Edge
    • Click the pencil icon next to "no description". Enter Edge with Okta SSO as the edge name and click Save.

  4. On the edge settings, click SAML.

  5. Click Begin setup and click on Upload XML beside IdP Metadata under Identity Provider and select your metadata file saved from the steps above:

    Okta config in ngrok

  6. Click Save at the top.

  7. After you save, the SP Metadata will appear. Copy these values into the Okta where temporary values were placed above: Update Okta with SP values

  8. Save the changes in Okta.

  9. Launch a tunnel connected to your Okta edge:

Note

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

  1. Click Start a tunnel.

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

    tunnel config

  3. Launch a tunnel:

    • Launch a terminal
    • Paste the command. Replace http://localhost:80 with your local web app addess (i.e., http://localhost:3000)
    • hit Enter. an ngrok tunnel associated to your edge configuration is launched.

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

    tunnel confirmed

  5. In the test edge, copy the endpoint URL. (you will use this url to test the Okta Authentication) tunnel url

Step 3: Test the integration​

  1. In your browser, launch an incognito window.
  2. Access your ngrok tunnel (i.e., https://okta-sso-test.ngrok.io or using a copied URL).
  3. You should be prompted to log in with your Okta credentials.
  4. After login, you should be able to see your web app.