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.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, the Glass profile without aredirect, aredirectwithoutcode_challenge, or any challenge that is not S256 is refused with HTTP 400 before the sign-in starts. -
After sign-in the browser lands on
<redirect>#setup=<token>, or<redirect>#oauthError=<reason>. The app connects withclient.id = "wednesdayai-glass-node",auth.bootstrapToken = <token>andauth.bootstrapCodeVerifier = <verifier>; without the verifier the gateway refuses the code withbootstrap_code_verifier_invalid(see Gateway protocol).
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.