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

​
Configuration Reference

The Traffic Policy configuration reference for this action.

​
Supported Phases

on_http_request

​
Type

oauth

​
Configuration Fields

​
provider
string
Required
The name of the OAuth identity provider to be used for authentication.
​
auth_id
string
Unique authentication identifier for this provider. This value will be used for the cookie, redirect, authentication and logout purposes.
To login a user you must use /ngrok/login?auth_id={auth_id}. If you are using path based auth you must include the path to be redirected back to: ?redirect_path=/foo
​
client_id
string
Supports CEL
Your OAuth app’s client ID.
Leave this empty if you want to use ngrok’s managed application.
​
client_secret
string
Supports CEL
Your OAuth app’s client secret.
Leave this empty if you want to use a managed application.
​
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_timeout
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

​
/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.
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 action 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

​
Required Scopes

This is a list of the minimum required scopes for each provider. You can use this when configuring your identity provider. These are not required when using the ngrok managed applications.
ProviderScopes
Amazonprofile
Facebookemail
Githubread:org, read:user
Gitlabemail, openid, profile
Googlehttps://www.googleapis.com/auth/userinfo.email, https://www.googleapis.com/auth/userinfo.profile
LinkedInr_emailaddress, r_liteprofile
MicrosoftUser.Read
Twitchuser:read:email

​
Try it out

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

​
Behavior

​
Callback URL

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

​
Authentication

When an unauthenticated request is made to an OAuth-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:
  • 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 /.
  • Continue processing the rest of the traffic policy actions.

​
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 OAuth configuration of the endpoint either in the agent or through the dashboard.
  • If you update the OAuth configuration of the endpoint.
If a previously authenticated user becomes unauthorized because their identity provider information changed or because the OAuth action configuration changed, they are presented an error and are prompted to try logging in again.

​
Managed Applications

Managed applications allow you to use ngrok’s OAuth action without setting up your own OAuth apps with the identity providers. More practically, this means you can use the OAuth action without configuring a client id and client secret. Managed applications are great for getting started but they have some limitations.

​
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 the API. Whenever a user authenticates or accesses an endpoint with a configured OAuth 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 a google authentication step. 
on_http_request:
  - actions:
      - type: oauth
        config:
          provider: google
The provider value can be replaced with any of the Supported Providers that have an a managed app available.

​
Restricting access to certain users

See here for an example of conditional access based on OAuth result variables.

​
Using a Custom Provider

If you need more control than what a managed provider can offord you then you can bring your own provider.

​
Google Example

​
GitHub Example

on_http_request:
  - actions:
      - type: oauth
        config:
          provider: github
          client_id: '{your app''s oauth client id}'
          client_secret: '{your app''s oauth client secret}'
          scopes:
            - read:user
            - read:org

​
GitLab Example

on_http_request:
  - actions:
      - type: oauth
        config:
          provider: gitlab
          client_id: '{your app''s oauth client id}'
          client_secret: '{your app''s oauth client secret}'
          scopes:
            - openid
            - profile
            - email

​
LinkedIn Example

on_http_request:
  - actions:
      - type: oauth
        config:
          provider: linkedin
          client_id: '{your app''s oauth client id}'
          client_secret: '{your app''s oauth client secret}'
          scopes:
            - r_emailaddress
            - r_liteprofile

​
Microsoft Example

on_http_request:
  - actions:
      - type: oauth
        config:
          provider: microsoft
          client_id: '{your app''s oauth client id}'
          client_secret: '{your app''s oauth client secret}'
          scopes:
            - openid
            - email
            - profile

​
Twitch Example

on_http_request:
  - actions:
      - type: oauth
        config:
          provider: twitch
          client_id: '{your app''s oauth client id}'
          client_secret: '{your app''s oauth client secret}'
          scopes:
            - user:read:email
            - openid

​
Amazon Example

on_http_request:
  - actions:
      - type: oauth
        config:
          provider: amazon
          client_id: '{your app''s oauth client id}'
          client_secret: '{your app''s oauth client secret}'
          scopes:
            - profile

​
Facebook Example

on_http_request:
  - actions:
      - type: oauth
        config:
          provider: facebook
          client_id: '{your app''s oauth client id}'
          client_secret: '{your app''s oauth client secret}'
          scopes:
            - 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.oauth.error.code
string
Code for an error that occurred during the invocation of an action.
​
actions.ngrok.oauth.error.message
string
Message for an error that occurred during the invocation of an action.
​
actions.ngrok.oauth.identity.id
string
Unique identifier for the ngrok Identity entity
​
actions.ngrok.oauth.identity.email
string
Email address of the authorized user from the provider.
​
actions.ngrok.oauth.identity.name
string
Name for the authorized user from the provider.
​
actions.ngrok.oauth.identity.provider_user_id
string
Identifier for the authorized user from the provider.
​
actions.ngrok.oauth.identity.current_provider_session_id
string
The current Identity session identifier for this request.
​
actions.ngrok.oauth.access_token
string
The access token from the provider.
​
actions.ngrok.oauth.refresh_token
string
The refresh token from the provider.
​
actions.ngrok.oauth.expires_at
string
Timestamp when the current session will expire.
​
actions.ngrok.oauth.session_timed_out
boolean
Returns true when the session timed out.
​
actions.ngrok.oauth.session_max_duration_reached
boolean
Returns true when the current session reached the max duration.
​
actions.ngrok.oauth.userinfo_refreshed
boolean
Returns true when ngrok updates the user information on the identity.