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.
  • 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, the Glass 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.
  3. After sign-in the browser lands on <redirect>#setup=<token>, or <redirect>#oauthError=<reason>. The app connects with client.id = "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).
The Glass profile is only minted for a person the operator granted it (oidc invite … --enrollment-profile, or oidc grant). 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. 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.