> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wednesdayai.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Identity OIDC

# 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

```bash theme={"dark"}
wednesdayai plugins enable identity-oidc
```

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

## Configuration

```json5 theme={"dark"}
{
  plugins: {
    entries: {
      "identity-oidc": {
        enabled: true,
        config: {
          publicBaseUrl: "https://assistant.example.com",
          // webClientUrl: "https://assistant.example.com/v2/client/", // default
          // cookieSecret: "${IDENTITY_OIDC_COOKIE_SECRET}", // required for multi-replica
          // inviteTtlDays: 7, // default
          // nativeRedirects: ["wednesdayai://auth"], // native app landings, see "Native apps"
          providers: [
            {
              id: "google",
              type: "oidc",
              issuer: "https://accounts.google.com",
              clientId: "${GOOGLE_CLIENT_ID}",
              clientSecret: "${GOOGLE_CLIENT_SECRET}",
            },
            {
              id: "entra",
              label: "Microsoft",
              type: "oidc",
              issuer: "https://login.microsoftonline.com/<tenantId>/v2.0",
              clientId: "${ENTRA_CLIENT_ID}",
              clientSecret: "${ENTRA_CLIENT_SECRET}",
              trustEmailClaim: true, // Entra emits no email_verified; single-tenant issuers only
            },
            {
              id: "github",
              type: "github",
              clientId: "${GITHUB_CLIENT_ID}",
              clientSecret: "${GITHUB_CLIENT_SECRET}",
            },
          ],
        },
      },
    },
  },
}
```

* `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](#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](#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](#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

| Provider | `type` | `issuer` | Notes |
| - | - | - | - |
| Google | `oidc` | `https://accounts.google.com` | default scopes `openid email profile` |
| Microsoft Entra, single tenant | `oidc` | `https://login.microsoftonline.com/<tenantId>/v2.0` | set `trustEmailClaim: true` |
| GitHub | `github` | none | default scopes `read:user user:email` |

* **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:

```
identity-oidc: provider <id> issuer must use https (plain http is only trusted for loopback hosts 127.0.0.1, ::1, localhost): <issuer>
```

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:

```bash theme={"dark"}
wednesdayai oidc invite Alice --provider google --email alice@example.com
wednesdayai oidc uninvite Alice --provider google
wednesdayai oidc invites           # or --json
```

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.)

```bash theme={"dark"}
wednesdayai oidc invite Alice --provider google --email alice@example.com --enrollment-profile wednesdayai-glass-node
wednesdayai oidc grant Alice --enrollment-profile wednesdayai-glass-node
wednesdayai oidc revoke Alice --enrollment-profile wednesdayai-glass-node
```

* 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](https://docs.wednesdayai.dev/next/admin/gateway/identity#what-logout-does).

## 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:

   | Parameter | Value |
   | - | - |
   | `redirect` | one `nativeRedirects` entry, character for character |
   | `profile` | `wednesdayai-mobile`, `wednesdayai-desktop` or `wednesdayai-glass-node` (deprecated alias); default `user-client` |
   | `code_challenge` | the S256 challenge (43 base64url characters) |
   | `code_challenge_method` | `S256` |

   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](https://docs.wednesdayai.dev/next/admin/gateway/protocol.md#client-identity)).

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.

### iOS universal links

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](https://developer.apple.com/documentation/xcode/supporting-associated-domains).

## Operator runbook

### Require app sign-in

```bash theme={"dark"}
wednesdayai config set plugins.entries.identity-oidc.config.appSignIn '"required"'
# restart the gateway
```

* 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:

```bash theme={"dark"}
wednesdayai config set plugins.entries.identity-oidc.config.appSignIn '"optional"'
# restart the gateway
```

Set it back to `"required"` once the IdP answers again.

### Force re-sign-in for app devices

```bash theme={"dark"}
wednesdayai config set plugins.entries.identity-oidc.config.appSessionMaxAgeDays 30
# restart the gateway
```

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:

```bash theme={"dark"}
wednesdayai devices list --json   # app devices whose entry has no "identity" are the stale ones
wednesdayai devices remove <deviceId>
```

`devices remove` revokes the record, closes its live sockets and unlinks it (#2307).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.