Ebbe BaßandClaude Sonnet 5.5
24de5878ed
Includes the BMAD install config, the initiative ticket tree, the portal context-resources scripts, and the .gitignore change that tracks BMAD files (generated _bmad/render/ is ignored). Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Sk72AxLwQnYttF6VFSxQLt
46 lines
4.2 KiB
Markdown
46 lines
4.2 KiB
Markdown
# Addendum: Technical Context for Downstream Documents
|
||
|
||
Carries the detail that does not belong in `prd.md`. The brief's addendum (`_bmad-output/briefs/.../addendum.md`) holds the original context; this file adds what the PRD discovery produced.
|
||
|
||
## Existing picture pipeline (the three PowerShell scripts stay unchanged)
|
||
- `AD-ProfilePicture-Sync.ps1` (DC, scheduled task): for every user in the target OU reads `<sam>.jpg` from the source path, else a default image. It writes `<sam>_96.jpg` and `<sam>_448.jpg` to the processed path, writes `<sam>.md5` (MD5 of the source file) there, and sets `thumbnailPhoto`, `jpegPhoto` and `photo` from the 96px copy (limit 100 KB). It never compares the MD5, so every run reprocesses every user.
|
||
- `Set-LocalAccountPicture.ps1` (logon): builds Windows account-picture sizes from `thumbnailPhoto`; large sizes use the 448px copy from the share.
|
||
- `Set-AccountPictureRegistry-System.ps1` (startup): applies registry entries from manifests.
|
||
- The original scripts are in `context-resources/` (untracked in git). Verified against them: the MD5 file is written at line 114 and the AD attributes at line 117, so a failed AD write still leaves a matching MD5 file.
|
||
|
||
## Portal and the pipeline: contract
|
||
- Portal writes: `<source path>/<username>.jpg`, square JPEG, at least 448 px (assumed 512×512).
|
||
- Portal reads: `<processed path>/<username>.md5` to detect that the Sync Task has processed the file (the hash is the MD5 of the Portal's file). This ties the Portal to the unchanged script.
|
||
- The hash in `<username>.md5` is an uppercase hex MD5 written with a trailing newline (`Get-FileHash` plus `Set-Content`). Compare case-insensitively and trim whitespace.
|
||
- The sync script covers `OU=Organisation`, which includes the Portal's writable OU. File names use `sAMAccountName`.
|
||
- Portal reads: `thumbnailPhoto` from Active Directory to show the current picture.
|
||
- Both paths are configuration.
|
||
|
||
## Active Directory
|
||
- Writable OU: configurable; example in the homelab: `OU=Clients,OU=Organisation,DC=ping-mee,DC=local`.
|
||
- Attributes written: `givenName`, `sn`, `displayName`, `mail`, `telephoneNumber`, `mobile`, and the password via LDAPS.
|
||
- The Service Account needs delegated rights for exactly those attributes and password change on that OU. Password writes need LDAPS.
|
||
- Read rights also needed: `pwdLastSet`, account enabled and locked state, group membership, `thumbnailPhoto`, and the Password Policy shown on the password page (domain `minPwdLength`, `pwdProperties`, `pwdHistoryLength`, and the user's `msDS-ResultantPSO` for a fine-grained policy). [Attribute names to verify in the test OU.]
|
||
- Expired and "must change" passwords: AD refuses the bind (LDAP error 49, data 532 or 773). The Portal does not handle these. The Admin resets the password in AD.
|
||
- authentik's LDAP source offers its own password writeback to AD (needs `ldaps://` and delegated rights). Not used; the Portal changes passwords itself. Source: authentik Active Directory and LDAP source docs.
|
||
|
||
## Identity and roles
|
||
- OIDC via authentik, but kept generic so another provider works.
|
||
- `preferred_username` equals `sAMAccountName` (confirmed identical in the homelab).
|
||
- Roles: the Portal checks Publisher and Admin group membership in Active Directory.
|
||
|
||
## Security notes
|
||
- Throttling happens in front of every bind, to avoid lockouts by attackers.
|
||
- E-mail change chain risk (hijacked session, e-mail change, reset via e-mail) mitigated by: current password required, confirmation to the new address, notice and 24-hour Undo Link to the old address, undo ends sessions and notifies the Admin.
|
||
- Picture handling: HEIC, WebP, PNG and JPEG only; SVG rejected because it can carry scripts and external references. Decode with size and pixel limits; strip metadata; never serve originals.
|
||
- Markdown in Announcements is rendered with sanitization.
|
||
- Secrets only in Docker environment variables.
|
||
|
||
## Candidate technical choices (not decided)
|
||
- Embedded database (for example SQLite) in a mounted volume is enough for ten users; a server database could be a later option.
|
||
- A server-side image library with HEIC support is required.
|
||
- SMB access from a Linux container: a mounted share is the simplest.
|
||
|
||
## Design
|
||
- Office 365 (Fluent) look, not OWA 2010 or Aero. Themes and backgrounds are Admin-managed.
|