openid-connect
Makes visitors sign in with any OpenID Connect provider — Okta, Auth0, Microsoft Entra ID, Keycloak and others — before they reach your service.
| Phases | on_http_request |
| Terminating | No — the next action runs after it. |
| Cost | Free |
Example
policy.yaml
on_http_request:
- actions:
- type: openid-connect
config:
issuer_url: https://example.okta.com
client_id: 0oa1b2c3d4
client_secret: your-client-secret
- expressions:
- "!actions.ngrok.oidc.identity.email.endsWith('@example.com')"
actions:
- type: deny
Start an agent endpoint with it: devgate http 8080 --traffic-policy-file policy.yaml, or paste it into a
reserved or cloud endpoint’s Traffic Policy tab in the dashboard.
Configuration
| Field | Type | Description |
|---|---|---|
issuer_url required | string | Your provider’s issuer, the https URL that serves /.well-known/openid-configuration, e.g. https://example.okta.com. |
client_id / client_secret required | string | Your OpenID app. Register https://idp.devgate.run/oauth2/callback as its redirect URI. |
scopes | list of strings | Scopes to ask for; openid is always added. Default: openid, email, profile. |
auth_id | string | Names the session, for several sign-in actions or targeted login/logout. Default: oidc. |
max_session_duration | duration | How long a sign-in lasts, however active the visitor is. Default: 7d. |
idle_session_duration | duration | Sign the visitor out after this long without a request. |
userinfo_refresh_interval | duration | Re-read the visitor’s profile from the provider this often (at least 1m); if the provider no longer accepts the session, the visitor signs in again. |
allow_cors_preflight | boolean | Let CORS preflight requests through without a session. Default: false. |
authz_url_params | map | Extra parameters for the provider’s authorization URL, e.g. prompt or login_hint. |
auth_cookie_domain | string | Share the session cookie across sub-domains of this domain. |
Result variables
After it runs, later rules can read what it decided:
-
actions.ngrok.oidc.identity.email— The visitor’s e-mail address. -
actions.ngrok.oidc.identity.name— Their name. -
actions.ngrok.oidc.identity.provider_user_id— Their id at the provider (the sub claim). -
actions.ngrok.oidc.identity.id— provider-host:id, stable per person and provider. -
actions.ngrok.oidc.identity.current_session_id— An id for this sign-in. -
actions.ngrok.oidc.identity_token / access_token / refresh_token— What the provider issued, when it fits in the cookie. -
actions.ngrok.oidc.expires_at— When the session ends. -
actions.ngrok.oidc.session_timed_out / session_max_duration_reached— Why a visitor had to sign in again. -
actions.ngrok.oidc.user_info_refreshed— Whether the profile was re-read on this request. -
actions.ngrok.oidc.error.code / error.message— What went wrong reaching the provider.
Behaviour
- Visitors without a session are redirected to the provider and come back where they started.
- The ID token is checked: its signature against the provider’s published keys, the issuer, the audience (your client_id), the expiry, and a nonce tied to the browser that started the sign-in.
- An e-mail the provider marks unverified is left out, so a rule allowing @example.com can’t be passed with a made-up address.
- The action only signs people in; deny or allow them in a later rule, as in the example.
- /ngrok/login and /ngrok/logout (or /devgate/login, /devgate/logout) start a sign-in and end the session; add ?auth_id= to pick one of several.
- The provider’s tokens are available to later rules while they fit in the session cookie (about 3.8 KB); very large tokens are left out.
- Sessions are signed cookies on your endpoint’s host; they never reach your service.
Other actions
add-headers remove-headers compress-response basic-auth oauth jwt-validation custom-response deny redirect url-rewrite restrict-ips rate-limit circuit-breaker verify-webhook http-request set-vars log close-connection forward-internal