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
<publicBaseUrl>/plugins/identity-oidc/....
Configuration
publicBaseUrl(required): the external origin people use to reach the gateway. It must usehttps(plainhttpis 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 absolutehttpsURL (loopback plainhttpis allowed) without a fragment, without control characters and in ASCII (percent-encode anything else, because the URL is sent verbatim in theLocationheader): 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. Default7.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>/…orhttp://[::1]:<port>/…). Entries with a fragment, control characters, non-ASCII characters (percent-encode them), plainhttpon any other host, or ajavascript:,data:,file:,blob:orvbscript:scheme are refused when the config loads.appleAppIds: Apple App IDs (<TEAMID>.<bundle id>, e.g.ABCDE12345.com.example.glass) that may open thehttpsentries ofnativeRedirectsas universal links. Default none. When set, anhttpsnativeRedirectspath on thepublicBaseUrlorigin 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 atdevice.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 withapp_sign_in_expireduntil 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.idis[a-z0-9][a-z0-9-]{0,31}; duplicate ids log an error and the later duplicates are skipped.labeloverrides the displayed name.clientSecretaccepts${ENV_VAR}secret references.type: "oidc"requires anissuerand, whenscopesare set, they must includeopenid(otherwise no id token and no email claim arrives).type: "github"accepts noissuer— its endpoints are pinned; GitHub Enterprise is out of scope.
Provider presets
- Entra emits no
email_verifiedclaim, so invites would never match withouttrustEmailClaim: true. That flag trusts theemailclaim 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 theuser:emailscope (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 missinguser:emailscope. - Custom OIDC providers work with any standards-compliant issuer: set
type: "oidc", theissuerURL,clientIdandclientSecret, and optionallyscopes(which must includeopenid).
Issuer security
Issuers must usehttps. 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:
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’semail_verified: true, or
GitHub’s verified email list) against the invited address, exactly once:
--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).
#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.-
The app makes a fresh PKCE pair (RFC 7636): a random 43–128 character
verifierandchallenge = base64url(sha256(verifier)). -
It opens, in the system browser session,
<publicBaseUrl>/plugins/identity-oidc/<providerId>/startwith these query parameters:Aredirectnot on the allowlist, an unknownprofile, an app profile without aredirect, aredirectwithoutcode_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. -
After sign-in the browser lands on
<redirect>#setup=<token>, or<redirect>#oauthError=<reason>. The app connects with the client id matching itsprofile(wednesdayai-mobile,wednesdayai-desktopor the deprecatedwednesdayai-glass-node),auth.bootstrapToken = <token>andauth.bootstrapCodeVerifier = <verifier>; without the verifier the gateway refuses the code withbootstrap_code_verifier_invalid(see Gateway protocol).
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.
iOS universal links
To return to an iOS app throughhttps instead of an app scheme:
- Add
https://<publicBaseUrl host>/plugins/identity-oidc/native-returntonativeRedirects(keep the app scheme as the fallback for older iOS versions). - Set
appleAppIdsto the app’s<TEAMID>.<bundle id>.
/.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
providersentry: 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.issueandwednesdayai qr --client wednesdayai-mobile|wednesdayai-desktop|wednesdayai-glass-nodeare refused withapp_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:
"required" once the IdP answers again.
Force re-sign-in for app devices
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).