Skip to main content

Identity OIDC plugin

identity-oidc is a bundled, disabled-by-default extension that turns browser sign-in into an identity proof. A person signs in with Google, Microsoft Entra (single tenant) or GitHub; if the sign-in matches an invite or is already linked, the extension links the sign-in to that person, mints a web-client device bootstrap and lands the browser in the web client, paired as its own device. Identity values minted by sign-in look like oauth:<providerId>:<32 hex>, where the hex is the first 32 characters of sha256("<issuer>|<subject>"). The pair (iss, sub) is the only stable subject a provider gives you: email addresses and usernames can change and are never used as the key.

Enable the plugin

Restart the gateway afterwards. Once enabled, the sign-in routes live under <publicBaseUrl>/plugins/identity-oidc/....

Configuration

  • publicBaseUrl (required): the external origin people use to reach the gateway. It must use https (plain http is only trusted on loopback hosts — 127.0.0.1, ::1, localhost — for local development) and be a bare origin with no path, query or fragment. Sign-in callbacks run at <publicBaseUrl>/plugins/identity-oidc/<providerId>/callback, so register exactly that redirect URI with each provider.
  • webClientUrl: where sign-in lands. Defaults to <publicBaseUrl>/v2/client/. Must be an absolute https URL (loopback plain http is allowed) without a fragment, without control characters and in ASCII (percent-encode anything else, because the URL is sent verbatim in the Location header): the sign-in handler appends its own #setup=/#oauthError= fragments.
  • cookieSecret: at least 32 characters (checked after trimming). The flow state (provider, state, PKCE verifier, nonce) lives in a sealed cookie, never in server memory, so any replica can serve the callback. Set one shared value when more than one gateway replica serves the routes; otherwise a secret is generated under <state dir>/identity-oidc/. Supports ${ENV_VAR} secret references.
  • inviteTtlDays: how long invites stay valid. Default 7.
  • nativeRedirects: the exact-match allowlist of native app landing targets (see Native apps). Default none. Each entry is a universal/app link (https://…), an app scheme (wednesdayai://auth) or a loopback address (http://127.0.0.1:<port>/… or http://[::1]:<port>/…). Entries with a fragment, control characters, non-ASCII characters (percent-encode them), plain http on any other host, or a javascript:, data:, file:, blob: or vbscript: scheme are refused when the config loads.
  • appleAppIds: Apple App IDs (<TEAMID>.<bundle id>, e.g. ABCDE12345.com.example.glass) that may open the https entries of nativeRedirects as universal links. Default none. When set, an https nativeRedirects path on the publicBaseUrl origin may not contain * (Apple reads it as a wildcard). See iOS universal links.
  • appSignIn: "optional" (default) or "required". "required" makes the WednesdayAI app (wednesdayai-mobile, wednesdayai-desktop) show sign-in as its only entry: setup codes for the app profiles are refused at device.bootstrap.issue, wednesdayai qr --client … and at connect for an app device without a person (app_sign_in_required). Sign-in itself, other profiles (user-client, Even G2, Mentra) and gateways without this plugin are unchanged. See Operator runbook.
  • appSessionMaxAgeDays: optional positive integer. When set, an app device paired more than this many days ago is refused at connect with app_sign_in_expired until the app signs in again. Unset (default) means no forced re-auth. The check runs only at gateway connect, so an offline phone keeps working locally.
  • providers (at least one): see below. id is [a-z0-9][a-z0-9-]{0,31}; duplicate ids log an error and the later duplicates are skipped. label overrides the displayed name. clientSecret accepts ${ENV_VAR} secret references. type: "oidc" requires an issuer and, when scopes are set, they must include openid (otherwise no id token and no email claim arrives). type: "github" accepts no issuer — its endpoints are pinned; GitHub Enterprise is out of scope.

Provider presets

  • Entra emits no email_verified claim, so invites would never match without trustEmailClaim: true. That flag trusts the email claim as verified and is only safe for a single-tenant issuer, where your tenant already decides who holds an address.
  • GitHub is plain OAuth2 with pinned endpoints (no discovery document, no id token). The subject is the numeric user id and verified emails come from /user/emails, which needs the user:email scope (or the GitHub App Email permission): without it, already-linked sign-ins still work, only the invite match is skipped, and the gateway logs a warning naming the missing user:email scope.
  • Custom OIDC providers work with any standards-compliant issuer: set type: "oidc", the issuer URL, clientId and clientSecret, and optionally scopes (which must include openid).

Issuer security

Issuers must use https. A plain-http: issuer is accepted only on loopback hosts (127.0.0.1, ::1, localhost) for local development and test issuers; anything else is refused when the config loads:
Over cleartext, an attacker on the network path could serve a forged JWKS and mint id tokens for any linked subject. Discovery is per provider and lazy: a failed discovery is remembered for 30 seconds and the next sign-in start after that window retries (so a transient issuer outage does not turn every start into a full discovery round trip), and each discovery attempt is cut off after 10 seconds so a hanging discovery endpoint cannot stall sign-in.

Invites

Sign-in only binds a person when the operator invited that person first, or the sign-in is already linked. An invite matches a provider-verified email (the id token’s email_verified: true, or GitHub’s verified email list) against the invited address, exactly once:
Add --enrollment-profile wednesdayai-glass-node (repeatable) to an invite to also let that person enroll WednesdayAI Glass when the invite is claimed. People who are already linked get or lose a profile with grant/revoke. (The flag is not --profile: that is the global CLI option that selects a named config profile.)
  • The person must already exist: Unknown identity "Alic". Add it first: wednesdayai identity add Alic.
  • The provider must be configured: Unknown provider "<id>". Configured providers: google, github.
  • The email must contain exactly one @.
  • Inviting again for the same person+provider, or for an address that another person already holds at that provider (correcting a typo), replaces the pending invite; the CLI prints what it replaced.
  • Invites expire after inviteTtlDays (default 7 days) because mailboxes get reassigned. From the first sign-in on, the immutable (iss, sub) subject is the key, and the email no longer matters.
  • The invite is claimed and removed under one store lock, so two concurrent callbacks carrying the same verified email cannot both bind. If linking then fails with a transient error, the original invite is put back so the claim does not burn or renew it; when the invited person no longer exists, the claim stands and the sign-in is refused (link_failed).
An uninvited, unlinked sign-in is refused and the browser lands on #oauthError=not_invited in the web client: Your account isn't registered with this assistant. Ask the administrator to invite you. The other failure reasons the web client renders are oauth_state_invalid (Sign-in expired or was started in another browser. Try again.), link_failed (Your sign-in is already linked to someone else. Ask the administrator.) and the generic oauth_failed (Sign-in failed. Try again.). Callback state is single use: a replayed callback (back button, duplicate tab) is refused as oauth_state_invalid before the token exchange, so the provider’s single-use code is never presented twice.

What sign-in does afterwards

On success the extension links the sign-in to the person and calls the identity runtime to mint a user-client device bootstrap, then redirects to <webClientUrl>#setup=<token>. The browser pairs as its own device exactly as it does with a scanned setup code. That token is a bearer code: it pairs whichever browser redeems it. A device’s person never changes (#2307): a setup code for someone other than the device’s current owner is refused at connect (bootstrap_device_owned) rather than moving the link. A #setup= link that arrives at a browser which is already paired is therefore never redeemed silently; the web client asks for explicit confirmation first and only on confirm logs the current device out, which deregisters it, and then pairs a brand-new device for the token’s person. See Identities.

Native apps

A native app (WednesdayAI Glass) signs in through the same provider flow but lands on an app link instead of the web client, and receives a setup code only it can redeem.
  1. The app makes a fresh PKCE pair (RFC 7636): a random 43–128 character verifier and challenge = base64url(sha256(verifier)).
  2. It opens, in the system browser session, <publicBaseUrl>/plugins/identity-oidc/<providerId>/start with these query parameters: A redirect not on the allowlist, an unknown profile, an app profile without a redirect, a redirect without code_challenge, or any challenge that is not S256 is refused with HTTP 400 before the sign-in starts. The desktop app uses an RFC 8252 loopback redirect (http://127.0.0.1:<port>/…) on the same allowlist.
  3. After sign-in the browser lands on <redirect>#setup=<token>, or <redirect>#oauthError=<reason>. The app connects with the client id matching its profile (wednesdayai-mobile, wednesdayai-desktop or the deprecated wednesdayai-glass-node), auth.bootstrapToken = <token> and auth.bootstrapCodeVerifier = <verifier>; without the verifier the gateway refuses the code with bootstrap_code_verifier_invalid (see Gateway protocol).
Before sign-in the app reads GET /plugins/identity-oidc/providers, which returns the provider list, the resolved appSignIn value and, when set, appSessionMaxAgeDays (in days). Without the plugin, with no usable provider, or while the plugin is disabled the route is absent and the app falls back to the setup-code/QR path exactly as before. The app profiles are minted only for a person the operator granted one (oidc invite … --enrollment-profile, or oidc grant; the three app names are one grant — holding any one of them enrolls with any of them). Anyone else gets #oauthError=profile_not_granted on the app link; the flow never falls back to a different credential. oidc revoke stops future enrollments only: an already paired device keeps its pairing until you remove it. wednesdayai-glass-node is the deprecated alias for the same app credential (ADR 2242 D4): prefer wednesdayai-mobile/wednesdayai-desktop in new grants and invites. Use the platform’s browser session, never an embedded WebView: iOS ASWebAuthenticationSession, Android Custom Tabs with verified App Links, and on desktop a loopback listener on http://127.0.0.1:<port>. Google blocks sign-in inside embedded WebViews with 403 disallowed_useragent, and RFC 8252 requires the external user agent for native apps. To return to an iOS app through https instead of an app scheme:
  1. Add https://<publicBaseUrl host>/plugins/identity-oidc/native-return to nativeRedirects (keep the app scheme as the fallback for older iOS versions).
  2. Set appleAppIds to the app’s <TEAMID>.<bundle id>.
The gateway then serves /.well-known/apple-app-site-association (unauthenticated, JSON). It lists the configured app IDs under applinks and webcredentials, and claims the paths of every https nativeRedirects entry on the publicBaseUrl origin. Entries on other hosts are skipped: Apple only associates paths with the host that serves the file. Without appleAppIds the file is not served. /plugins/identity-oidc/native-return itself answers GET with a short “Return to the app” page, for when the browser opens the link instead of the app. The setup code is in the URL fragment, so it never reaches the gateway. Apple’s CDN fetches the association file from the public internet. A gateway reachable only inside a private network (for example over Tailscale Serve) cannot pass that check; use developer-mode associated domains (applinks:<host>?mode=developer) for development-signed builds, which the device fetches directly, or publish the gateway host. See Apple’s Supporting associated domains.

Operator runbook

Require app sign-in

  • Requires at least one configured providers entry: with an empty provider list, or while the plugin is disabled, the app keeps the setup-code/QR path (there is no sign-in to force).
  • From then on the app shows sign-in as its only entry; device.bootstrap.issue and wednesdayai qr --client wednesdayai-mobile|wednesdayai-desktop|wednesdayai-glass-node are refused with app_sign_in_required. User-client, Even G2 and Mentra setup codes are unchanged.
  • Already-paired app devices whose record has no person (QR-paired before identity existed) are refused at connect with app_sign_in_required; the app shows sign-in and re-pairs as a new device. Prune the stale records afterwards (below).

Roll back while the IdP is down

required mode can lock out people’s apps when the identity provider is unreachable (sign-in is the only entry and it cannot complete). The gateway itself is not affected — device tokens keep working — so operators keep the CLI and Control UI:
Set it back to "required" once the IdP answers again.

Force re-sign-in for app devices

At connect, an app device paired more than 30 days ago is refused with app_sign_in_expired and the app shows sign-in again. Unset the key (or remove it) to stop forcing re-auth. The check runs only at gateway connect, so an offline phone keeps working locally until it next reaches the gateway.

Remove owner-less QR-paired app devices

App devices that re-paired through sign-in leave their old owner-less QR records behind. Those records have no identity, so supersede-based pruning (devices prune --superseded) never selects them — supersede matching requires the same person and client id. Find and remove them explicitly:
devices remove revokes the record, closes its live sockets and unlinks it (#2307).