OAuth

Overview

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

• providerstringRequired

  The name of the OAuth identity provider to be used for authentication.

• auth_idstring

  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

  To log a user out you must use /ngrok/logout?auth_id={auth_id}

  You additionally can provide a path to redirect the user to on logout: ?redirect_path=/

• client_idstring

  Your OAuth app's client ID.

  Leave this empty if you want to use ngrok’s managed application.

• client_secretstring

  Your OAuth app's client secret.

  Leave this empty if you want to use a managed application.

• scopesarray of strings

  A list of additional scopes to request when users authenticate with the identity provider.

• authz_url_paramsmap of string to string

  A map of additional URL parameters to apply to the authorization endpoint URL.

• max_session_durationduration

  Defines the maximum lifetime of a session regardless of activity.

• idle_session_timeoutduration

  Defines the period of inactivity after which a user's session is automatically ended, requiring re-authentication.

• userinfo_refresh_intervalduration

  How often should ngrok refresh data about the authenticated user from the identity provider.

• allow_cors_preflightboolean

  Allow CORS preflight requests to bypass authentication checks. Enable if the endpoint needs to be accessible via CORS.

  Default: false

• auth_cookie_domainstring

  Sets the allowed domain for the auth cookie.

Special Paths

Path	Description
/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.

Events

When this action is enabled, it populates the following fields in the http_request_complete.v0 event:

Fields
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.

Provider	Provider Identifier	Managed App Available	Integration Guide
Amazon	amazon	no	Documentation
Facebook	facebook	no	Documentation
GitHub	github	yes	Documentation
GitLab	gitlab	yes	Documentation
Google	google	yes	Documentation
LinkedIn	linkedin	yes	Documentation
Microsoft	microsoft	yes	Documentation
Twitch	twitch	yes	Documentation

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.

Provider	Scopes
Amazon	profile
Facebook	email
Github	read:org, read:user
Gitlab	email, openid, profile
Google	https://www.googleapis.com/auth/userinfo.email, https://www.googleapis.com/auth/userinfo.profile
LinkedIn	r_emailaddress, r_liteprofile
Microsoft	User.Read
Twitch	user: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.

• They are only available for some identity providers
• You may not pass custom scopes when using a managed application.
• The upstream headers ngrok-auth-oauth-access-token and ngrok-auth-oauth-refresh-token are not sent to your application.

App Users

ngrok's App Users 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 OAuth action, their App User record is created or updated.

You may also use App Users 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.

Cookie	Description
session	Used to track an authenticated user.
nonce	Used to secure the authentication flow.

Examples

Using a Managed Provider

The following Traffic Policy configuration will provide your app with a google authentication step.

YAML

---
on_http_request:
  - actions:
      - type: oauth
        config:
          provider: google

JSON

{
  "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.

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

YAML

---
on_http_request:
  - actions:
      - type: oauth
        config:
          provider: google
          client_id: "{your app's oauth client id}"
          client_secret: "{your app's oauth client secret}"
          scopes:
            - https://www.googleapis.com/auth/userinfo.profile
            - https://www.googleapis.com/auth/userinfo.email

JSON

{
  "on_http_request": [
    {
      "actions": [
        {
          "type": "oauth",
          "config": {
            "provider": "google",
            "client_id": "{your app's oauth client id}",
            "client_secret": "{your app's oauth client secret}",
            "scopes": [
              "https://www.googleapis.com/auth/userinfo.profile",
              "https://www.googleapis.com/auth/userinfo.email"
            ]
          }
        }
      ]
    }
  ]
}

GitHub Example

YAML

---
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

JSON

{
  "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

YAML

---
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

JSON

{
  "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

YAML

---
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

JSON

{
  "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

YAML

---
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

JSON

{
  "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

YAML

---
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:
            - user:read:email
            - openid

JSON

{
  "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": [
              "user:read:email",
              "openid"
            ]
          }
        }
      ]
    }
  ]
}

Amazon Example

YAML

---
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

JSON

{
  "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

YAML

---
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

JSON

{
  "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.

Action Variables

• actions.ngrok.oauth.error.codestring

  Code for an error that occurred during the invocation of an action.

• actions.ngrok.oauth.error.messagestring

  Message for an error that occurred during the invocation of an action.

• actions.ngrok.oauth.identity.idstring

  Unique identifier for the ngrok Identity entity

• actions.ngrok.oauth.identity.emailstring

  Email address of the authorized user from the provider.

• actions.ngrok.oauth.identity.namestring

  Name for the authorized user from the provider.

• actions.ngrok.oauth.identity.provider_user_idstring

  Identifier for the authorized user from the provider.

• actions.ngrok.oauth.identity.current_session_idstring

  The current Identity session identifier for this request.

• actions.ngrok.oauth.access_tokenstring

  The access token from the provider.

• actions.ngrok.oauth.refresh_tokenstring

  The refresh token from the provider.

• actions.ngrok.oauth.expires_atstring

  Timestamp when the current session will expire.

• actions.ngrok.oauth.session_timed_outboolean

  Returns true when the session timed out.

• actions.ngrok.oauth.session_max_duration_reachedboolean

  Returns true when the current session reached the max duration.

• actions.ngrok.oauth.userinfo_refreshedboolean

  Returns true when ngrok updates the user information on the identity.