Build an OAuth 2.1 authorization server (OpenIddict) so MCP clients can authenticate

[mforce]

Note

Picking this up? Start here.

The design is finished and merged. Do not redesign it. Read
docs/plans/788-mcp-oauth/
first, all five files, in order. It records what was decided, what was rejected and why, and four
claims that were checked against source. Several conclusions are counter-intuitive and came from
verification rather than reasoning. Re-deriving them from scratch will cost a day and may reach the
wrong answer, as it did twice during the design.

Build in this order: #794 (prerequisite) → #795 → #796 → #797 → #798 → #799. #800 can run in
parallel after #795.

The slice that matters is #796. It produces nothing visible, and an error there is silent and
security-relevant. Adversarial review found two of its requirements after the design looked
complete: stale role claims, and revocation not being a property of the token format. Read its
comments, not just its body.

Three traps, all documented, all easy to hit:

1. Adding the 4 OpenIddict tables turns TenantBypassDiscoveryTests.DiscoveredSurface_Floor red.
   That is correct behaviour, because it asserts exact set equality. Add the entities with a stated
   reason. Do not relax it to a subset check, which would quietly disable a tenancy guard.
2. Roles are not read live. Nothing reloads them from the database. Freshness comes from
   revocation. An OAuth token with stale role claims keeps a demoted user's authority.
3. Reference tokens do not give instant revocation by themselves. OpenIddict does not check
   authorization-grant status by default.

---

Important

Amended. This issue's question is answered. The body below stays as written, for history. It
poses a question and leans toward the cheaper options. The decision went the other way, to build an
OAuth 2.1 authorization server with OpenIddict. See the decision comment
for what was chosen, what was designed and rejected (a full Personal Access Token flow), the verified
integration cost, and the one guard test that will break. This issue is now the OAuth implementation.

---

Slices: engine first, screens after

Dependencies set the order. Risky plumbing lands first, where it is cheapest to fix. Slices 1-3 are
invisible to users, by design. The sizes total four L and two M.

Wave 1, foundation. Nothing else starts until this lands.

• OAuth slice 1: stand up OpenIddict — tables, migration, token issuance #795 · L stands up OpenIddict: tables, migration, schema docs, token issuance.
  Its prerequisite is Data Protection has no persisted key ring, so Identity's token providers break across restarts and replicas #794 (Data Protection key ring).

Wave 2. These two can run in parallel, and both need #795.

• OAuth slice 2: fail-closed checks on the OAuth path (disabled, suspended, must-change-password, flock scope, rate limit) #796 · L adds fail-closed checks on the OAuth path for disabled user, suspended farm,
  must-change-password, flock scoping, rate limits and revocation. This slice carries the
  security work, and it produces nothing visible, so it is the most likely slice to be under-scoped.
• OAuth slice 3: dynamic client registration with rate limiting and unapproved-app expiry #797 · M adds dynamic client registration. Clients self-register, a rate limit applies, and
  unapproved apps expire.

Wave 3, the screens.

• OAuth slice 4: consent screen, with step-up and return-URL validation #798 · L builds the consent screen: an SPA route, step-up, all-or-nothing consent, plus the
  open-redirect guard on the hop from login to consent. Needs OAuth slice 1: stand up OpenIddict — tables, migration, token issuance #795, OAuth slice 3: dynamic client registration with rate limiting and unapproved-app expiry #797.
• OAuth slice 5: connected-apps screens — user's own, and the Owner's farm-wide view #799 · L builds the connected-apps screens: the user's own apps on the Account page, and the
  Owner's farm-wide view. Needs OAuth slice 1: stand up OpenIddict — tables, migration, token issuance #795, OAuth slice 4: consent screen, with step-up and return-URL validation #798.

In parallel with waves 2-3.

• OAuth slice 6: audit provenance — record which application acted, alongside the human #800 · M adds audit provenance, with first-class columns that record which application acted.
  Needs OAuth slice 1: stand up OpenIddict — tables, migration, token issuance #795 only.

The MCP SDK's discovery metadata (McpAuthenticationHandler) and scope enforcement on the MCP tools are not part of this issue. They live in epic #789, because they belong to MCP rather than to the OAuth server.

#770's design work raised this issue (see docs/plans/770-mcp-server/01-design.md, "Open questions and risks"). This open question decides whether MCP support is usable in the real world, as distinct from whether it is correct.

The mismatch

#770's design authenticates an MCP session with an ordinary Cluckwork access token. It is the same bearer the SPA carries, from POST /api/v1/auth/login with a farm code. That is the smallest correct first step. It reuses the whole existing pipeline (tenant resolution, credential epoch #364, authorization, must-change-password) with no MCP-specific identity and no new config key.

It works. It may not be usable:

• Cluckwork's access token is short-lived by design, and it rotates through a refresh token in an HttpOnly cookie. The cookie exists to keep the refresh token out of reach of JavaScript in a browser.
• An MCP client is not a browser. It has no cookie jar semantics to rely on, and the MCP ecosystem expects OAuth 2.1 with discovery. A client calls the server, the server points it at an authorization server, and the client obtains and refreshes its own token.
• So a user configuring a Cluckwork MCP server would paste a bearer that stops working shortly afterwards, with no in-protocol way to renew it.

Options, roughly in increasing cost

1. Ship phase 1 as-is, documented as requiring a caller that can inject a fresh bearer (a script, a gateway, a developer testing). This is honest, cheap, and possibly fine for the first slice, but it is not "point your assistant at your farm".
2. Add the SDK's McpAuthenticationHandler and serve protected-resource metadata at /.well-known/oauth-protected-resource/.... The SDK has first-class support for this (ModelContextProtocol.AspNetCore.Authentication). This tells a client where to authenticate. By itself, it does not make Cluckwork an authorization server.
3. Issue a longer-lived, MCP-scoped credential, in effect an API token with its own lifetime, revocation and audit rules. This is a product decision with real security exposure, and it interacts with Credential epoch: per-request revocation check, deployed inert ahead of the user-admin mutations #364's credential-epoch revocation. That mechanism is what currently makes revocation immediate.
4. Become an OAuth 2.1 authorization server for MCP clients. This is the largest option, and probably not phase 1.

Why this needs a decision before the tool work, not after

The design deliberately keeps this choice from invalidating it. The identity bridge reads the ClaimsPrincipal the pipeline produces, regardless of how that principal was authenticated. So the choice does not affect the tools or the guards.

But the phasing depends on the answer. If option 1 is acceptable for a first slice, MCP support can ship and be exercised. If it is not, then whatever closes this gap is a prerequisite for MCP being worth shipping at all. That work should be sized alongside MCP rather than discovered afterwards.

Not claimed

This issue claims no security defect. Option 1 is not insecure. A short-lived bearer over an authenticated endpoint is exactly what the SPA does. The problem is ergonomics and reach. The risk is finishing the tool work and finding that nobody can practically connect.

[mforce]

This is a prerequisite for #789 (EPIC: MCP server support), not a follow-up. The epic records it as a blocker.

Here is the reason again, because the ordering is easy to get backwards. This does not change the design. The identity bridge reads whatever ClaimsPrincipal the middleware pipeline produces, regardless of how the caller authenticated. So the answer does not affect the tools, the guards or the idempotency work.

It decides whether anyone can practically connect, and therefore whether the tool work is worth starting. This ordering avoids one failure: building slices 1-8 of the epic, then discovering that a real MCP client drops its token a few minutes in.

The cheapest acceptable answer may be option 1 in the body above, which ships phase 1 documented as requiring a caller that can inject a fresh bearer. That is a legitimate decision. It needs to be a decision, though, rather than something found out afterwards.

[mforce]

Decision: build an OAuth 2.1 authorization server with OpenIddict

This issue asked a question and listed four options. The decision is option 4 (become an OAuth authorization server), not the cheaper options the body leans toward. This comment records what was decided and why, so the body above reads as history rather than as live guidance.

Why not the cheaper options

The body's option 1 ("ship documented as requiring a caller that can inject a fresh bearer") and a Personal Access Token flow both had detailed designs before they were set aside. The PAT design reached a full decision tree: self-service on the Account page, scopes, a cw_pat_ prefix with checksum, Owner visibility, and revocation semantics matching GitHub's. It was workable.

It lost for one reason. A PAT is a workaround for MCP clients that cannot do OAuth, and MCP expects OAuth because OAuth is the better answer for delegated, revocable, scoped access to someone else's data. Choosing the workaround means handing a long-lived credential to a robot and hoping nobody loses it.

Research that changed the decision (all verified, not recalled):

• OpenIddict 7.7.0 is Apache-2.0, with net10.0 confirmed on NuGet. It is actively maintained and has corporate sponsors. It has no licence cost and no commercial restriction. It is a full OAuth 2.1 server, with authorization code with PKCE, client credentials, device flow, and discovery metadata.
• Microsoft states that ASP.NET Core has no built-in PAT support. Its documentation describes the Identity API's bearer tokens as "not intended to be a full-featured identity service provider or token server". They are a session pattern built from a short-lived access token and a refresh token, with no named tokens, no per-token scopes and no independent revocation. A PAT would have been entirely hand-rolled.
• Duende IdentityServer was priced and rejected. It costs $5,750/yr at minimum and up to $24,900, which is disproportionate here.

The accepted risk is that OpenIddict has one primary maintainer. Apache-2.0 makes forking possible, and the alternative, hand-rolling OAuth, is materially riskier than depending on the ecosystem's standard implementation.

The design

Mechanism	OpenIddict, OAuth 2.1, alongside the existing login
Scope	Third-party clients only. The SPA's hand-rolled login is untouched. #793 covers revisiting that
Client registration	Dynamic self-registration (what the MCP spec recommends), rate-limited, unapproved apps expire
Who may connect	Any user, for their own data. A Worker's assistant gets a Worker's view
Approval	Requires step-up, which means re-entering the current password, reusing #308's grant
Scopes	Two: read farm data, record daily entries. This matches the 7 tools in phase 1
Token format	Reference tokens, not JWTs, so disconnecting takes effect on the next call. This matches #364's existing guarantee that revocation is immediate. Self-contained tokens would have contradicted it
Lifetime	Indefinite until revoked
Visibility	Users manage their own connections. An Owner sees and can revoke any on the farm
Audit	AuditEvents gains first-class columns recording which app acted alongside the human actor
Discovery	The MCP SDK's McpAuthenticationHandler serves protected-resource metadata

Checks that must still run on an OAuth-authenticated request

An OAuth token bypasses CredentialEpochMiddleware's JWT path, so the design names these checks explicitly: user disabled, farm suspended, must-change-password, flock scoping, and rate limits. Each needs wiring. None is inherited for free.

Verified integration cost

• 4 new EF tables (Applications, Authorizations, Scopes, Tokens) in one new migration, which is compatible with the feat(eggs): make cracked and dirty eggs sellable stock via condition grades (#396) #407 freeze. The freeze forbids touching InitialCreate but not adding migrations.
• The same PR must regenerate docs/schema/, or CI's staleness check fails (chore(schema): generate PostgreSQL schema documentation #417).
• Exactly one guard test breaks, and it is the right one. TenantBypassDiscoveryTests.DiscoveredSurface_Floor asserts exact set equality over filter-free entities, so the 4 new tables turn it red until someone adds them deliberately with a reason. The rest of the tenancy stack, meaning the AccountId must be a non-nullable Guid: the write guard and the #562 token walk are both fail-open for any other shape #673 model walk, TenantStampInterceptor and the Add discovery guard for flock-scoped EF query filters #613 flock walk, skips entities with no AccountId structurally. So the boot is not affected.
• The new NuGet package means updating Directory.Packages.props and regenerating the lock files in the same commit (chore: adopt Central Package Management so a version bump is one file, not eight #684/CI: dependency-vulnerability and SAST gates #146).

Honest cost note

This is roughly double the PAT option. The decision accepted that cost.

This issue gets a new title to reflect that it is now the OAuth implementation, not an open question.

[mforce]

Consent screen: decided

This is the only screen a human sees in the whole flow, and the only moment anyone makes a security decision. Everything else happens without a person, including self-registration, token issuance and refresh.

	Decision
Granularity	All-or-nothing. Allow or Cancel, with no per-permission checkboxes
Not signed in	Redirect to login, then back to consent
Already approved	Skip silently if the app asks for nothing new. Show again if it asks for MORE
Location	A route in the existing SPA (/connect or similar)
Approval	Requires re-entering the current password, reusing #308's step-up grant

What the screen must say

Beyond the app name and permissions, it has to say "acting as you" explicitly, meaning the assistant can never do more than the signed-in user can. A farmer's mental model of "an AI has access to my farm" is likely scarier than the reality, where a Worker's assistant sees a Worker's view. With that sentence, the screen asks for informed consent. Without it, the screen is a dialog people dismiss.

It should also name where to undo it, so users can find revocation at the moment they grant access, rather than only when they go looking.

Why all-or-nothing

With two scopes the choice means almost nothing, and partial grants fail badly. An assistant denied write access half-works, and neither it nor the user explains why. Revisit this if the scope list ever grows past a handful.

Why skip re-approval

Prompting on every reconnect trains people to click through a dialog that usually says the same thing, and that is how consent screens stop working. Re-prompting only on a widened scope request keeps the prompt meaningful.

Why the SPA rather than a server-rendered page

The app ships three locales. A hand-rolled server-rendered consent page would need its own i18n, its own styling, and its own accessibility work. That duplicates what the SPA already has, on the one screen where clarity matters most. The SPA route also keeps the user visibly inside Cluckwork, which matters for a screen about trust.

---

Security note: the redirect back to consent is an open-redirect hazard

Choosing "send to login, then back to consent" opens a classic hole. It must be closed deliberately, not assumed closed.

The app must validate the return URL against an allow-list of internal paths. If the app takes it from a query parameter and follows it without checking, an attacker can send someone a link that logs them into Cluckwork and then sends them on to a site that looks like Cluckwork and asks for their password. The user's whole experience is "I clicked a Cluckwork link, I logged into Cluckwork, then Cluckwork asked me something". They never see the redirect.

This is separate from OAuth's own redirect_uri validation, which OpenIddict handles against the registered client. The hazard here is the hop from login to consent inside the app, which OpenIddict knows nothing about.

This needs a guard, and the guard's red mutation is easy to state. Point the return parameter at an absolute external URL and assert that the app refuses it rather than follows it. It is also worth asserting that it refuses protocol-relative URLs (//evil.example), which look relative and are not. That variant most often slips through a naive check.

Whoever builds this should also know that this repo's service worker has caused this kind of problem before. #778 records it swallowing server-issued redirects, so ?farm= never reaches the login form. The hop from login to consent is a redirect through the same path, so test it against a built SPA with the service worker active, not only in dev.

[mforce]

Library evaluation: what was considered and ruled out

This comment records the whole comparison so nobody re-researches it. Every entry was verified against the live sources, not recalled.

Package	Alive?	Licence	.NET 10	Verdict
OpenIddict 7.7.0	Yes. Sponsored, 6 open issues, 0 open PRs	Apache-2.0	Confirmed on NuGet	Chosen. Full OAuth 2.1 server: auth code with PKCE, client credentials, device flow, discovery metadata
Duende IdentityServer	Yes, commercial	Source-available, paid in production	Not independently verified	Rejected on price. It costs $5,750/yr (Lite, 2 client IDs) to $24,900/yr, which is disproportionate for a farm app
Fido2.NET	Yes, a .NET Foundation project, 34 open issues	MIT	.NET 8+	Keep in mind for #320. Still recommended alongside Identity 10's passkeys for attestation validation, which the in-box implementation does not do. Microsoft built a plugin interface for exactly this
Otp.NET	Stable, low churn	MIT	Not confirmed	Not needed. Identity 10 ships AuthenticatorTokenProvider in-box
QRCoder	Yes. The maintainer changed to Shane32 in 2025 (the repo redirects from codebude/QRCoder)	MIT, zero dependencies	net5.0+ claimed, net10 not named	Only if we render TOTP enrolment QR codes ourselves
AspNetCore.Authentication.ApiKey	Alive, slow cadence	MIT	No .NET 10 release visible	Skip. It saves ~100 lines, and every dependency adds exposure to security advisories under #146

Why OpenIddict rather than hand-rolling

Microsoft's own documentation settles this. It describes the Identity API's bearer tokens, verbatim, as "not intended to be a full-featured identity service provider or token server". They are a session pattern built from a short-lived access token and a refresh token, for clients that cannot hold cookies. They have no named tokens, no per-token scopes and no independent revocation. ASP.NET Core Identity has no built-in PAT or OAuth server, so the realistic options were OpenIddict or writing an OAuth server by hand. Writing it by hand is far riskier than depending on the ecosystem's standard implementation.

Accepted risk, stated plainly

OpenIddict has one primary maintainer (Kévin Chalet), with corporate sponsors funding the work. That is a real bus-factor risk on a security-critical dependency. Apache-2.0 makes a fork legally possible, though forking an OAuth server is not a small undertaking. The risk is accepted deliberately, because the alternative is hand-rolling OAuth, which carries more risk, not less.

What ASP.NET Core 10 gives for free

This list was verified against the restored ref-pack assemblies at Microsoft.AspNetCore.App.Ref/10.0.12. Everything in it is already on this repo's compile graph with zero new package references, because Identity is part of the in-box shared framework for net10.0 and both projects carry FrameworkReference Microsoft.AspNetCore.App.

• TOTP: AuthenticatorTokenProvider<TUser>, GenerateNewAuthenticatorKey, VerifyTwoFactorTokenAsync, GenerateNewTwoFactorRecoveryCodesAsync
• Passkeys: IUserPasskeyStore<TUser>, UserPasskeyInfo, IdentityPasskeyOptions, IPasskeyHandler<TUser>. However, passkeys are a primary factor by design, and their entry points are on SignInManager, which this repo does not register (AddIdentityCore without AddSignInManager)
• Microsoft.AspNetCore.Authentication.BearerToken and MapIdentityApi<TUser>() are present but unmounted, and the quote above shows they are unsuitable here

#320 has the detail on both factors. The Data Protection prerequisite that surfaced during this evaluation is now #794, a latent defect independent of this work.

The rejected PAT design, kept for reference

A full Personal Access Token design was worked through before OAuth was chosen. If OAuth ever proves too heavy, these conclusions can be reused without rediscovery:

• Self-service on the Account page (where change-password lives), not the Owner-only Users admin screen
• An opaque 256-bit random value, with only its SHA-256 hash stored and the raw value never persisted. This mirrors the existing RefreshToken shape
• A cw_pat_ prefix and a CRC32/Base62 checksum, following GitHub's convention. Secret scanners can find the tokens, and the checksum rejects typos with no database lookup
• Not revoked by a password or role change. Because roles are read live, a demoted user's credential narrows automatically. GitHub behaves the same way, and states the principle: "A token cannot grant additional access capabilities to a user"
• Revoked by explicit revocation, expiry, user disable, and account suspension
• Mandatory expiry with a user-chosen, capped lifetime, and no "never" option
• Owner gets farm-wide visibility and revocation

[mforce]

Slice sizing

These sizes follow how this repo already uses size: on epic #719. L is a feature slice crossing domain, API and frontend (#725, #727). M is a bounded change (#729, #769). S is a focused fix (#776, #782).

Slice	Size	Why
#795 stand up OpenIddict	L	A new dependency and lock files, UseOpenIddict() on the DbContext, a migration with 4 tables, regenerated docs/schema/, a guard-test update, plus the authorization controller OpenIddict requires (it is a framework, not a turnkey server)
#796 fail-closed checks	L	Five distinct checks, each needing its own guard with a stated red mutation. The second authentication scheme this repo has ever had. The role-freshness decision. Verifying that revocation takes effect. The largest and riskiest of the six
#797 client registration	M	One endpoint, a rate limiter on the shared counter, an expiry sweep. It is bounded, and the metadata-document question needs a decision rather than a build
#798 consent screen	L	An SPA route, step-up integration, the return-URL security guard, three locales, screenshots, plus GLOSSARY.md and Help. Comparable to #727's approval flow
#799 connected-apps screens	L	Two distinct screens (the user's own, and the Owner's farm-wide view), revoke endpoints, last-used tracking, i18n, screenshots, docs. #726 is L for one screen with history, and this is two
#800 audit provenance	M	Two columns, a migration, regenerated schema docs, and display in the existing audit UI with filtering. The change is additive, but AuditEvents is the table this repo is most careful about (#508, #505)

The total is four L and two M. That is a substantial epic, consistent with the design's own note that this is roughly double the rejected Personal Access Token option.

The same pass sized related issues: #794 M (prerequisite), #792 S (decision only), #787 M (blocks #789's write slice).

#793 is deliberately left unsized. It records the conditions for revisiting a possible future login migration. It is not scheduled work, and sizing it would imply it is ready to pick up.