docs: test-environment runbook and scripts for ticket 1.2

Setup script for the test OU, scoped service account, groups and test users;
an LDAPS check script; and a runbook for the CA file, authentik, Zoraxy and
a test mailbox. Not run against a live directory.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Sk72AxLwQnYttF6VFSxQLt
This commit is contained in:
Ebbe Baß
2026-10-15 15:11:14 +02:00
co-authored by Claude Sonnet 5.5
parent 840bea1cba
commit 003ce6e0c2
5 changed files with 483 additions and 0 deletions
@@ -0,0 +1,3 @@
- source_plan: `_bmad-output/initiative-ping-mee-portal/epic-platform-and-sign-in/story-prepare-the-test-environment-plan.md`
summary: ARCHITECTURE-SPINE AD-2 says the service account's read rights are limited to a list, but Active Directory gives authenticated users broad read by default, so the statement is not enforced by the test-environment setup.
evidence: The setup script grants only write rights and the Change Password right; read access is the default. Either soften AD-2 ("needs no more than this list") or enforce it with deny entries; decide when the architecture is next updated.
@@ -0,0 +1,59 @@
---
title: 'Prepare the test environment'
type: 'chore'
ticket: '2'
created: '2026-10-15'
status: 'built'
baseline_revision: '840bea1cbaac1f32136399677d7ae8ef06ce532c'
route: 'oneshot'
route_source: 'auto'
risk: 'medium'
review: 'quick'
review_source: 'pinned'
lenses_ran: ['quick']
review_loop_iteration: 0
context:
- '{project-root}/_bmad-output/architecture/architecture-ping-mee-self-service-platform-2026-10-15/ARCHITECTURE-SPINE.md'
---
<frozen-after-approval reason="human-owned intent — do not modify unless human renegotiates">
## Intent
**Problem:** Entries 4 and 5 need a test OU with a scoped service account, a dedicated OIDC application in the production authentik, the internal CA bundle, the Zoraxy route and a test mailbox. A person must create these in the production systems; none of it exists yet.
**Approach:** Provide a runbook, a domain-controller script that creates the test OU, service account, groups and test users with only the spine's delegated rights, and a verification script that proves the rights over LDAPS. The person runs them and writes down the values; this entry is done only when they confirm the verification passed.
</frozen-after-approval>
## Implementation Notes
Oneshot route: the output is documents and two PowerShell scripts under `docs/test-environment/`, no application code. The agent cannot reach the homelab from the development machine (it is on a different domain), and creating objects in the production directory is the person's action, so the scripts are not run by the agent. Syntax is checked with the PowerShell parser only.
## Plan Change Log
## Review Triage Log
Pass 1 (quick lens). Counts: high 1, medium 8, low 1, false 1.
| # | Finding | Verdict | Route | Evidence |
|---|---------|---------|-------|----------|
| 1 | The check script can print "All checks passed." when a request throws | high | patch | A .NET exception ends only the statement when `$ErrorActionPreference` is `Continue`; `Report` was never called. Fixed with `Stop`, try/catch around steps 2, 3 and 6. |
| 2 | Generated passwords are lost if a later step fails | medium | patch | Passwords were printed only after delegation; the setup now runs inside try/finally so they always print. |
| 3 | Checks test only one of six allowed attributes | medium | patch | The check now writes and restores all six; the header states what is not covered (create, delete, reset). |
| 4 | Read rights are not limited as AD-2 says | medium | defer | AD gives authenticated users broad read by default; the fix is to soften the spine wording, which is a spec edit. README states the fact. |
| 5 | `-WhatIf` on a rerun reports creating existing objects | medium | patch | Existence checks are read-only and now run in both modes. |
| 6 | Any error counts as "does not exist" | low | patch | `Test-Dn` now catches only the identity-not-found error; direct correction. |
| 7 | CA export may miss the intermediate chain | medium | patch | README now exports the whole chain and checks it with `openssl s_client`. |
| 8 | Redirect URI presented as final | medium | patch | README says the sign-in ticket will use this path and where to edit it. |
| 9 | Step D.1 may mean editing the production LDAP source | medium | patch | README now checks read-only first and stops if the source does not cover the test OU. |
| 10 | Port 8000 exposure not mentioned | medium | patch | README note: bind to 127.0.0.1 or firewall to Zoraxy. |
| 11 | Ticket numbering 1.2 / 1.5 inconsistent | false | rejected | `tickets.py` prints these refs (epic id, entry id). |
## Verification
**Commands:**
- PowerShell parser check on both scripts -- expected: no syntax errors
**Manual checks (if no CLI):**
- The person runs the setup script on the domain controller and the verification script from a machine that can reach it; every check prints PASS.