QDG Identity: purpose, architecture and decisions

Document version: 1.0.0. 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. The actual Codex desktop browser-login journey and production deployment remain acceptance gates.

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. Development Auth0 API/client configuration exists; the eligible login connection, first end-user sign-in and issued-token proof still need completion.

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 KB resource/audience is https://qdb.qdatasite.com/mcp/qdg-kb. 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. Production refresh and MFA settings remain a separate explicit decision after measuring the actual client behaviour.

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

Complete Robert's actual login, read/write, permission-denial, renewal, restart and removal tests. Collect and review the sanitised Odin readiness report. Resolve the host, database, permissions, ingress encryption/logging and recovery prerequisites, then rehearse the exact release. Retire only the old KB MCP credentials at its accepted cutover.

See the User Guide and How to Use pages for user and operator responsibilities. A detailed integration guide for additional QDG services will be completed after the first working deployment is verified.

Source: Identity project, KB MCP integration.