OpenID Connect (OIDC)

Overview

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_urlstringRequired

  The base URL of the Open ID provider that serves an OpenID Provider Configuration Document at /.well-known/openid-configuration.

• auth_idstring

  Unique authentication identifier for this provider.

• client_idstring

  Your OpenID Connect app's client ID.

• client_secretstring

  Your OpenID Connect app's client secret.

• scopearray 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_durationduration

  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 CORES preflight requests to bypass authentication checks. Enable if the endpoint needs to be accessible via CORES.

• auth_cookie_domainstring

  Sets the allowed domain for the auth cookie.

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.

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

Pricing

Identity actions are limited to 2,000 requests with actions applied per month. Additional actions are available in ngrok's pay-as-you-go plan.

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 backchannel request to the identity provider; it is transparent to the user and they do not go through a reauthentication 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.

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

JSON

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

The provider value can be replaced with any of the Supported Providers that have an a managed app available.

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.oidc.error.codestring

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

• actions.ngrok.oidc.error.messagestring

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

• actions.ngrok.oidc.identity.idstring

  Unique identifier for the ngrok Identity entity

• actions.ngrok.oidc.identity.emailstring

  Email address of the authorized user from the provider.

• actions.ngrok.oidc.identity.namestring

  Name for the authorized user from the provider.

• actions.ngrok.oidc.identity.provider_user_idstring

  Identifier for the authorized user from the provider.

• actions.ngrok.oidc.identity.current_session_idstring

  The current Identity session identifier for this request.

• actions.ngrok.oidc.identity_tokenstring

  The identity token from the provider for the current user.

• actions.ngrok.oidc.access_tokenstring

  The access token from the provider.

• actions.ngrok.oidc.refresh_tokenstring

  The refresh token from the provider.

• actions.ngrok.oidc.expires_atstring

  Timestamp when the current session will expire.

• actions.ngrok.oidc.session_timed_outboolean

  Returns true when the session timed out.

• actions.ngrok.oidc.session_max_duration_reachedboolean

  Returns true when the current session reached the max duration.

• actions.ngrok.oidc.userinfo_refreshedboolean

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