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

​
issuer_url
string
Required
The base URL of the Open ID provider that serves an OpenID Provider Configuration Document at /.well-known/openid-configuration.
​
auth_id
string
Unique authentication identifier for this provider.
​
client_id
string
Supports CEL
Your OpenID Connect app’s client ID.
​
client_secret
string
Supports CEL
Your OpenID Connect app’s client secret.
​
scopes
array of strings
A list of additional scopes to request when users authenticate with the identity provider.
​
authz_url_params
map of string to string
A map of additional URL parameters to apply to the authorization endpoint URL.
​
max_session_duration
duration
Defines the maximum lifetime of a session regardless of activity.
​
idle_session_duration
duration
Defines the period of inactivity after which a user’s session is automatically ended, requiring re-authentication.
​
userinfo_refresh_interval
duration
How often should ngrok refresh data about the authenticated user from the identity provider.
​
allow_cors_preflight
boolean
Allow CORS preflight requests to bypass authentication checks. Enable if the endpoint needs to be accessible via CORS.

​
Special Paths

Upstream applications behind endpoints with this module enabled do not receive any requests to paths beginning with /auth/. Your application may redirect clients to the following paths to invoke different behaviors.

​
/ngrok/login

Redirect users to this path to explicitly begin an authentication flow. After authentication, users will be redirected to /. If the IdP supports it, ngrok will attempt to instruct the IdP to force re-authentication which will force users to re-enter their credentials with the IdP even if they were already logged in. |

​
/ngrok/logout

Logs the user out by clearing their session cookie. Redirect users to this path to log them out.

Note: 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/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, we recommend using 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.

​
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.
​
actions.ngrok.oidc.error.code
string
Code for an error that occurred during the invocation of an action.
​
actions.ngrok.oidc.error.message
string
Message for an error that occurred during the invocation of an action.
​
actions.ngrok.oidc.identity.id
string
Unique identifier for the ngrok Identity entity
​
actions.ngrok.oidc.identity.email
string
Email address of the authorized user from the provider.
​
actions.ngrok.oidc.identity.name
string
Name for the authorized user from the provider.
​
actions.ngrok.oidc.identity.provider_user_id
string
Identifier for the authorized user from the provider.
​
actions.ngrok.oidc.identity.current_session_id
string
The current Identity session identifier for this request.
​
actions.ngrok.oidc.identity_token
string
Identifier for the authorized user from the provider.
​
actions.ngrok.oidc.identity.current_session_id
string
The current Identity session identifier for this request.
​
actions.ngrok.oidc.identity_token
string
The identity token from the provider for the current user.
​
actions.ngrok.oidc.access_token
string
The access token from the provider.
​
actions.ngrok.oidc.refresh_token
string
The refresh token from the provider.
​
actions.ngrok.oidc.expires_at
string
Timestamp when the current session will expire.
​
actions.ngrok.oidc.session_timed_out
boolean
Returns true when the session timed out.
​
actions.ngrok.oidc.session_max_duration_reached
boolean
Returns true when the current session reached the max duration.
​
actions.ngrok.oidc.userinfo_refreshed
boolean
Returns true when ngrok updates the user information on the identity.