OIDC resource server: scheme, configuration and Protected Resource Metadata (1/7)

[KrzysztofPajak]

Type: feature

Issue

GrandNode can only authenticate Web API calls with its own JWT (API users with a shared secret). Integrations, applications and MCP-class clients increasingly expect OAuth 2.1: tokens issued by the organisation's identity provider, audience-bound to the resource, discoverable through Protected Resource Metadata (RFC 9728). There was no way to accept such tokens or to let a plugin protect its own endpoints with them.

This is the first of a stack of PRs (each targets the previous one; review in order):

1. OIDC resource server: scheme, configuration, metadata (this PR)
2. Token to customer mapping and work-context resolver
3. Web API accepts provider tokens next to the existing JWT
4. Guide and test environment (Keycloak, Zitadel)
5. Browser sign-in: core (resolver login mode, /register external mode)
6. Browser sign-in: Authentication.OpenIdConnect plugin
7. Browser sign-in: guide

Solution

GrandNode becomes an OAuth 2.1 resource server only (it never issues tokens), configured in the appsettings section OidcResourceServer, without provider-specific code:

• Oidc JwtBearer authentication scheme: JWKS signature, issuer, lifetime, and audience = canonical resource URI (RFC 8707) built from the store URL, never from the Host header.
• Protected resources come from configuration (Resources) and from plugins (IOidcProtectedResourceProvider) through one registry; each has a path prefix, audiences, supported and required scopes, authorized parties and an optional admin-panel requirement.
• RFC 9728 metadata at /.well-known/oauth-protected-resource[/{path}]; 401/403 answers carry WWW-Authenticate with resource_metadata, error and scope, plus a ProblemDetails body.
• The configuration is validated at startup; when the feature is disabled the scheme still exists with an empty configuration, so nothing fails open or crashes.

Breaking changes

None. The feature is off unless OidcResourceServer:Enabled is true.

Testing

1. dotnet test src/Tests/Grand.Web.Common.Tests - all pass.
2. With the feature off, run the app: nothing changes, /.well-known/oauth-protected-resource returns 404.
3. End-to-end steps with Keycloak and Zitadel are in the guide added in PR 4 (docs/oidc-resource-server.md, sections 6, 7 and 10).

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[KrzysztofPajak]

Review of the OIDC resource server. The ones I'd address before merge: store resolution for the audience check (OidcCanonicalUri), guest-customer creation on the anonymous metadata endpoints, and the RFC 9728 metadata URL shape. The rest are robustness and nits.

[KrzysztofPajak]

Review fixes:

• Defects fixed: the audience store now comes from the host, never the store cookie (db6434f). Metadata URLs follow RFC 9728 §3.1 and are matched on the resource URI path (f51fb29). A resource without a URI gets 404 and a warning instead of "resource": null (c611acd). Metadata fetches no longer create guest customers (7f1a4a8).
• Robustness: an unreachable IdP now gives 503 and an Error log instead of invalid_token (30741b7), and a negative clock skew is clamped (1101972). Nits and code-quality findings: c0d3952, ea2c20e, 5af62c3, e084407.
• Not changed, with reasons: the generic catch that isolates plugin providers, and the stage-1 fail-closed account conditions, which OIDC resource server: token to customer mapping (2/7) #892 replaces.
• The fixes are merged up through OIDC resource server: token to customer mapping (2/7) #892-Docs: browser sign-in with OpenID Connect (7/7) #897 without rewriting history. docs/oidc-resource-server.md is updated in Docs: OIDC resource server guide, Keycloak and Zitadel test environment (4/7) #894 (6c10d52).
• Still open: in OIDC resource server: token to customer mapping (2/7) #892 the work-context store can still follow the cookie while the OIDC customer is resolved from the host's store; noted above.