Skip to main content

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.

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 explains how to configure Okta as the primary Identity Provider for ngrok tunnels using single sign-on (SSO). 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
The ngrok integration with Okta supports SP-Initiated SSO. In this mode, users access ngrok endpoints and are redirected to Okta for authentication.

​
What you’ll need

  • An Okta account with administrative rights to create apps.
  • An ngrok Pay-as-you-go account with an authtoken or admin access to configure endpoints with OpenID Connect.

​
1. Configure Okta

​
Add the ngrok app in Okta

  • Access your Okta Dashboard as an administrator and then click Admin.
  • Click Application > Applications.
  • Click Browse App Catalog.
  • Search for ngrok, and then click Add.
  • Enter the Application label (this is the app name that will be displayed in the Okta dashboard for end users) and click Next.
  • Select OpenID Connect, and then enter the following:
    • Sign-in redirect URI: https://idp.ngrok.com/oauth2/callback
    • Login initiated by: Login initiated by app
  • Click Done.
  • 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.
  • In the ngrok configuration under Scopes, add the following OAuth Scopes: openid,profile,email

​
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:
  • Click Application > Applications.
  • Search for and click the ngrok app.
  • Click Assignments.
  • 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.

​
2. Configure ngrok

ngrok can use Okta SSO in two ways:
  • From the ngrok CLI (using the --oidc parameter)
  • From the ngrok dashboard

​
Option 1: ngrok CLI

This tutorial assumes you have an app running locally (for example, on localhost:3000) with the ngrok client installed.
  • Launch a terminal.
  • Enter the following command to launch an ngrok tunnel with Okta SSO. Replace <okta_url> with your Okta org address (for example, https://acme.okta.com) and the <okta_client_id> and <okta_client_secret> with the respective values copied from the ngrok app registered at Okta. Optionally, add the --url <domain> argument to get your own custom URL, replacing <domain> with your URL of preference: 
    ngrok http 3000 --oidc <okta_url> \
--oidc-client-id <okta_client_id> \
--oidc-client-secret <okta_client_secret> \
--url <domain>
  • Copy the URL available next to Forwarding (for example, https://okta-sso-test.ngrok.app).
  • Skip to Step 3.

​
Option 2: Traffic Policy

This tutorial assumes you have an app running locally (for example, on localhost:3000) with the ngrok client installed.
Create a policy.yaml file with the following content, replacing the placeholder values with those copied from Okta: 
on_http_request:
  - actions:
      - type: openid-connect
        config:
          issuer_url: 'https://acme.oktapreview.com'
          client_id: 'YOUR_OKTA_CLIENT_ID'
          client_secret: 'YOUR_OKTA_CLIENT_SECRET'
          scopes:
            - openid
            - profile
            - email
Launch an ngrok tunnel with this policy: 
ngrok http 3000 --traffic-policy-file policy.yaml --url YOUR_DOMAIN
Copy the URL next to Forwarding (for example, https://okta-sso-test.ngrok.app).

​
3. Test the integration

  • In your browser, launch an incognito window.
  • Access your ngrok tunnel (for example, https://okta-sso-test.ngrok.app or using a copied URL).
  • You should be prompted to log in with your Okta credentials.
  • After logging in, you should be able to see your web app.