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.

The OpenID Connect Traffic Policy action restricts access to only authorized users by enforcing OIDC through an identity provider of your choice.

​
Configuration reference

The Traffic Policy configuration reference for this action.

​
Supported phases

on_http_request

​
Type

openid-connect

​
Configuration fields

​
Special paths

​
Logging users in

To start an OIDC authentication flow explicitly—for example, from a “Log in” button or link—redirect users to /ngrok/login. After a successful authentication, ngrok redirects the user to /. If you’ve configured auth_id to identify this provider, include it in the URL: 
/ngrok/login?auth_id=my-provider
If the IdP supports it, ngrok instructs it to force re-authentication—users must re-enter their credentials even if they already have an active IdP session.

​
Logging users out

To end a user’s session—for example, from a “Log out” button or link—redirect users to /ngrok/logout. This clears the ngrok session cookie. If you’ve configured auth_id, include it in the URL to target the correct provider: 
/ngrok/logout?auth_id=my-provider
When using the Google OAuth 2.0/OIDC provider in Chrome with a managed profile, /ngrok/logout only clears the ngrok session cookie; it does not end the Google/IdP session maintained by the browser. Users may be silently re-authenticated on the next request. To fully sign out, sign out of Chrome or Google (or use a non-managed profile or Incognito) in addition to calling /ngrok/logout.

​
Events

When this module is enabled, it populates the following fields in the http_request_complete.v0 event:
  • oauth.app_client_id
  • oauth.decision
  • oauth.user.id
  • oauth.user.name

​
Supported providers

ngrok currently supports the following OAuth providers (see the Integration Guides for more details). In some instances, ngrok has a managed application that allows you to configure OAuth without setting up your own application in your provider. This is useful for testing and development, but when you move into production, use your own custom application in your specific provider.
ProviderProvider IdentifierManaged App AvailableIntegration Guide
AmazonamazonnoDocumentation
FacebookfacebooknoDocumentation
GitHubgithubyesDocumentation
GitLabgitlabyesDocumentation
GooglegoogleyesDocumentation
LinkedInlinkedinyesDocumentation
MicrosoftmicrosoftyesDocumentation
TwitchtwitchyesDocumentation

​
Try it out

Consult the list of supported providers for step-by-step integration guides.

​
Behavior

​
Callback URL

When you create your own OIDC app, you must specify a ‘Callback URL’ or ‘Redirect URL’ to the OIDC provider. When using ngrok’s OIDC action, that Callback URL is always: 
https://idp.ngrok.com/oauth2/callback

​
Authentication

When an unauthenticated request is made to an OIDC-protected endpoint, it returns a redirect response that begins an authentication flow with the configured identity provider. The original URI path is saved so that users can be redirected to it if they successfully authenticate. If the user fails to authenticate with the identity provider, ngrok will display an error describing the failure returned by the identity provider and prompt them to try logging in again. If the user successfully authenticates with the identity provider, ngrok will take the following actions:
  • Check any authorization constraints you’ve defined (like allowed emails or allowed email domains). If the user is not authorized, ngrok renders an error and prompts them to try logging in again.
  • Sets a session cookie to avoid repeating the authentication flow again.
  • Redirects the user to the original URI path they were attempting to access before the authentication flow began. If no such URI path was captured, they are redirected to /.

​
Continuous authorization

When an authenticated user makes a request, ngrok will sometimes refresh a user’s data from the identity provider (email, name, etc) and re-evaluate authorization constraints. This refresh is executed as a back channel request to the identity provider; it is transparent to the user and they do not go through a re-authentication flow. The following circumstances trigger refresh and authorization re-evaluation:
  • On a periodic interval defined by the userinfo_refresh_interval parameter.
  • If you update the OIDC configuration of the endpoint by restarting your agent with a new configuration.
  • If you update the OIDC configuration of the endpoint.
If a previously authenticated user becomes unauthorized because their identity provider information changed or because the OIDC action configuration changed, they are presented an error and are prompted to try logging in again.

​
Traffic Identities

ngrok’s Traffic Identities feature can be used to observe all of the authenticated user activity across your account in the ngrok dashboard or via API. Whenever a user authenticates or accesses an endpoint with a configured OIDC action, their Traffic Identity record is created or updated. You may also use Traffic Identities to remotely log a user out by revoking a session.

​
Cookies

This action sets two cookies in its operation. Cookies values are opaque to the upstream service and must not be modified.
CookieDescription
sessionUsed to track an authenticated user.
nonceUsed to secure the authentication flow.

​
Non-terminating action

This is a Non-terminating action. It does not return a response, and will allow Traffic Policy processing to continue to the next Action in the chain. All Cloud Endpoint Traffic Policies must end with a terminating action. This requirement does not apply to Agent Endpoints.

​
Examples

​
Using a managed provider

The following Traffic Policy configuration will provide your app with an authentication step. 
on_http_request:
  - actions:
      - type: openid-connect
        config:
          issuer_url: '{your issuer url}'
          client_id: '{your app''s oauth client id}'
          client_secret: '{your app''s oauth client secret}'
          scopes:
            - openid
            - profile
            - email

​
Action result variables

The following variables are made available for use in subsequent expressions and CEL interpolations after the action has run. Variable values will only apply to the last action execution, results are not concatenated.