MCM-34 — Internal Docs Single Sign-On
An SSO gateway (APISIX + Keycloak) sits in front of mcm-docs so only authenticated staff can reach internal engineering documentation.
MCM-34 — Internal Docs Single Sign-On
mcm-docs is RevDau's internal engineering documentation site, currently reachable by anyone with the URL. This initiative puts a single sign-on gateway in front of it, using Keycloak as the identity provider and APISIX as the enforcing gateway, so only authenticated RevDau staff can reach it — the same gateway technology the product itself already runs for its own customer-facing IAM, kept as a separate deployment, so the organization isn't introducing an unfamiliar stack.
Each user story below is a self-contained page with its own acceptance criteria, technical design, and UI changes. This page holds only what's shared across all of them.
Personas
| Persona | Role | Primary concern |
|---|---|---|
| Platform Admin | Sets up and maintains the identity provider and gateway | Centralized, low-maintenance access control that doesn't need touching every time a new internal site is added |
| Engineering Staff | RevDau employees who read internal documentation | Logging in once and browsing freely, without repeated login prompts or broken pages |
System Context
This gateway and identity provider are a new, separate deployment — distinct from the Keycloak/APISIX pair the product itself already runs for customer IAM, and distinct from MCM Nexus's own realm. Mixing staff-tooling access with product/customer authentication is deliberately avoided. Adding another internal site later, beyond mcm-docs, is just another route plus another client on this same gateway — nothing here needs to change for that.
User Stories
| Story | Summary |
|---|---|
| MCM-35 — Dedicated Keycloak Realm for Internal Access | A realm and client dedicated to internal tooling, separate from product/customer identity. |
| MCM-36 — APISIX Gateway Fronting mcm-docs | mcm-docs moves to a private origin only the gateway can reach, with APISIX as the single public entrypoint. |
| MCM-37 — mcm-docs Requires Login | Visiting mcm-docs without a session redirects to login; a valid session browses freely. |
| MCM-38 — Unauthorized Access Fails Closed | No page, asset, invalid, or expired session ever results in a broken page or content leak. |
| MCM-39 — Clean Logout | Logging out ends both the gateway session and the Keycloak SSO session. |
Cross-Cutting Non-Functional Requirements
| ID | Requirement |
|---|---|
| NFR-01 | The gateway is a single point of failure for every site behind it — its own availability must be planned for (redundant nodes, or an explicitly accepted risk, given this is internal-only tooling). |
| NFR-02 | The session check adds at most one token validation per request/session refresh and must not introduce noticeable latency browsing documentation. |
| NFR-03 | Client secrets are stored in a secrets manager or injected at deploy time — never committed to a repo or checked into gateway config files. |
| NFR-04 | Failed authentication attempts and login redirects are visible in the gateway's logs for troubleshooting. |
Out of Scope
- Any internal site beyond mcm-docs — the architecture supports adding one later as a new route/client, but no second site is in scope now.
- Deciding cross-site SSO behavior (would logging into one internal site silently authenticate another) — genuinely open until a second site exists; see Open Questions.
Open Questions
- Target domain: the gated mcm-docs needs a real internal-facing domain, distinct from any public one — not yet decided, treated as a placeholder in these stories until confirmed.
- Session timeout policy: how long a session should last before requiring re-login (shorter is more secure, longer is more convenient) — not yet decided.
- Ongoing ownership: who administers the Keycloak realm/client going forward — a single person, or does it need a runbook for others on the team?
MCM-28 — Manage the Custom Tag Allowed List in Settings
Add, update, and remove a tag's allowed values directly from its Settings tab.
MCM-35 — Dedicated Keycloak Realm for Internal Access
A Keycloak realm and client dedicated to internal tooling access, separate from product and customer identity systems.