Skip to main content
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 shows you how to configure Okta as the primary Identity Provider (IdP) for ngrok endpoints using single sign-on (SSO). By integrating Okta SSO with ngrok, you can:
  • Restrict access to ngrok endpoints only to users authenticated via Okta
  • Use Okta security policies, multi-factor authentication (MFA) authenticators (Okta Verify, FastPass, FIDO2), and ThreatInsights to control access to ngrok endpoints
  • Use Okta’s dashboard to facilitate access to ngrok apps

​
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 SAML.
1

Configure Okta

In the Okta Admin Console, create a SAML 2.0 app integration for ngrok with the App Integration Wizard. For the full steps, see Okta’s guide to creating SAML app integrations.As you configure the app:
  • Enter temporary values such as https://temporary for the Single sign-on URL and the Audience URI (SP Entity ID), and set Name ID format to EmailAddress. You replace the temporary values with ngrok’s values in a later step.
  • After you finish the wizard, open the app’s Sign On tab and download the IdP metadata XML from the active SHA-2 certificate’s View IdP metadata action. You use it in the ngrok policy below.
Okta restricts access to the app through assignments, and new apps start with none. On the app’s Assignments tab, assign the users and groups who should reach ngrok, and make sure your own account is assigned so you can test the integration.
2

Configure ngrok

The SAML Traffic Policy action is in early access. Request access to configure SAML via Traffic Policy.
Once you have early access, create a policy.yaml file with the following content, replacing YOUR_IDP_METADATA_XML with the IdP metadata XML from Okta:
The SAML action generates your ngrok service provider (SP) Entity ID and Assertion Consumer Service (ACS) URL from your endpoint URL. See the SAML action documentation for how to retrieve these values.Start an endpoint with this policy, replacing 3000 with your local web app port and YOUR_DOMAIN with your ngrok domain:
Copy the URL next to Forwarding. You use it to test the integration.
3

Update the Okta app settings

  • In Okta, open your ngrok app and go to the General tab.
  • In SAML Settings, click Edit, then replace the temporary values with the generated ngrok values:
    • Set Single sign-on URL to your ngrok ACS URL.
    • Set Audience URI (SP Entity ID) to your ngrok SP Entity ID.
  • Save the changes.
4

Test the integration

  • In your browser, launch an incognito window.
  • Access your ngrok endpoint (for example, https://okta-sso-test.ngrok.app or a copied URL).
  • When prompted, log in with your Okta credentials.
  • After you log in, you see your web app.