QDG Identity: purpose, architecture and decisions

Document version: 1.0.2. Updated 6 September 2026. Owner: Robert.

QDG Identity establishes Auth0 as QDG's shared identity platform. The first integration is QDG Knowledge Base MCP. It enables an approved person to sign in from an MCP client, receive access specific to that service, and have permitted actions attributed to a stable QDG identity.

The new OAuth credentials are independent of existing QDBAuth credentials. Day one does not change QDBAuth websites, their users or their tokens. After KB MCP is tested and working, other QDG services will migrate individually, with their own application registrations, resource identifiers, permissions and acceptance tests.

Current state and first outcome

Identity 0.2.0 and the KB MCP 1.2.0 integration are implemented. Automated source, security and isolated database tests provide evidence of their behaviour. Robert's Auth0 browser login, all ten tools through the Codex engine, current-policy denial and restoration, renewal beyond the original access-token lifetime, and all ten tools through a fresh desktop-attached connection have passed against the bounded synthetic pilot.

Robert is the first pilot user and Codex desktop is the first supported-client target. The bounded local pilot uses the actual MCP transport and synthetic in-memory data. It does not connect to the production KB database. The production Auth0 API and native Codex client registrations are saved with separate service-specific permissions and bounded renewal. This registration does not deploy OAuth to Odin or retire an existing KB token.

The first Odin Prepare run verified the release package, current host evidence and the complete 32-package offline installation while leaving the running KB service unchanged. Candidate generation first exposed a wrapper path defect, which was corrected. The targeted repair then produced private snapshots but stopped because the existing IIS route did not meet one of the candidate generator's exact baseline requirements. A read-only compatibility inspection is prepared to report every IIS and service mismatch together before another repair. Production deployment remains an acceptance gate.

Do not infer production readiness from a configured Auth0 dashboard, a passing test suite or a healthy server process.

How a normal request works

1. The MCP client discovers the service's authentication requirements.
2. The person signs in on Auth0's hosted login page.
3. The client obtains an access token for the exact KB MCP resource through the reviewed authorization-code and PKCE flow.
4. The client sends that token in the Authorization header of its MCP request.
5. The MCP service verifies the token signature and claims locally, using Auth0's public signing keys.
6. The service checks the person's current approved permissions and the permission required by the tool.
7. A permitted operation reaches the KB. A permitted write also creates a stable-identity audit record in the same database transaction.

Auth0 hosts authentication. QDG still needs verification and authorization code inside each protected service. The repository contains that shared code and QDG's non-secret configuration definitions; it does not host Auth0 or store passwords and client secrets.

Why the repository is wider than MCP

Auth0 belongs to the QDG identity platform rather than one application. Centralising the standards, configuration definitions, shared verification components and operating documentation avoids rebuilding the same controls for every future service.

Application-specific integration stays with the application. Identity contains the reusable verifier; KB MCP maps its own tools to read/write permissions and performs its own database audit. A future website or API does not acquire access merely because it uses the same Auth0 tenant.

Why tokens are specific to a service

The planned production KB resource/audience is https://qdb.qdatasite.com/mcp/qdg-kb. The local pilot has its own loopback resource and credentials; completing that pilot does not activate production. A token for another service is rejected. The service also checks the approved OAuth client and current user policy. Successful login alone is not permission to use every QDG application.

The initial permissions are qdg-kb:read and qdg-kb:write. Tool-level checks prevent a read-only client from writing. The token's requested permissions form a ceiling: wider local user rights do not expand a narrowly scoped token.

A future service receives a separate resource and service permissions. There is no tenant-wide default audience used to make incompatible clients appear to work.

Why current permissions are checked locally

A signed access token can remain cryptographically valid until expiry even after an upstream account change. The protected local entitlement policy is reread at request and tool boundaries so an authorised local removal blocks an existing token.

This initial policy is deliberately explicit and small. It maps the trusted issuer and subject to a permanent QDG actor, a display label and approved permissions. Operators control the file and its permissions. Managed role/organisation features can replace the policy provider later after equivalent behaviour has been tested; they must not remove the current-denial control.

Why PKCE and bounded renewal

The pilot is a public native client with an exact callback and an authorization-code flow using PKCE. It does not embed a client secret in a desktop application. PKCE binds the authorization-code exchange to the client instance that initiated it.

The development pilot uses short access tokens and rotating refresh tokens with an absolute 24-hour maximum and one-hour idle limit. This permits testing normal renewal while limiting persistence. The production registration uses the same bounded renewal settings. Production login, MFA policy and operating evidence remain separate acceptance decisions.

Outage behaviour

Normal access-token lifetime is limited to ten minutes and signing keys are cached for five minutes. During an Auth0 outage, an existing request can be accepted only while both the token and the available cached key remain acceptable under the configured limits. A restart loses the in-memory key cache. Refresh still requires Auth0; a long refresh-token lifetime does not guarantee access throughout an outage.

The new emergency capability is separate and disabled by default. It permits one currently approved Robert identity to read for at most one hour after deliberate incident activation. It requires protected activation, current permissions and working durable audit storage. It does not permit writes, automatically extend token/key validity or revive retired tokens. Its actual client and host procedure must be rehearsed.

Audit and recovery choices

A KB write and its identity audit commit together. A missing audit INSERT permission must prevent the content write from being committed. Isolated real MySQL tests exercise this behaviour; production schema and grants still need checking.

Deployment stages a verified offline release before stopping only the KB MCP service. Exact configuration and permissions are backed up and rechecked for drift. Semantic canaries verify authentication behaviour after restart. Recovery preserves current access denials. If a failed first cutover has no verified OAuth-capable rollback, the service stays stopped rather than silently reopening old authentication.

Next acceptance gates

Run and review the prepared read-only Odin compatibility inspection. Correct the candidate transformation against the verified IIS and service findings, then complete Preflight and the separately reviewed Deploy execution. Production acceptance must prove the Auth0 login, exact issuer/audience/client/subject contract, all KB operations, durable database audit, current-policy removal, renewal, restart, ingress encryption/logging and recovery. Retire only the old KB MCP credentials at the accepted cutover.

See the User Guide and How to Use pages for user and operator responsibilities. Current engineering references are the local pilot guide, shared package contract, Odin preparation review and outage runbook. These describe the development implementation and evidence; the production Odin deployment is still pending.

A detailed integration guide for additional QDG services will be completed after the first working deployment is verified. How to Use records its completion checklist and Robert's acceptance responsibility.

Source: Identity project, KB MCP integration.