ping-mee-self-service-platform/_bmad-output/prds/prd-ping-mee-self-service-platform-2026-10-15/prd.md

title, status, created, updated

title	status	created	updated
PRD: ping-mee Self-Service Portal	final	2026-10-15	2026-10-15

PRD: ping-mee Self-Service Portal

Working title — confirm.

0. Document Purpose

This PRD defines the ping-mee Self-Service Portal for the homelab owner, who is also the builder, and for the downstream workflows (UX, architecture, epics and stories). It builds on the product brief in _bmad-output/briefs/brief-ping-mee-self-service-platform-2026-10-15/. Vocabulary is anchored in the Glossary (§3). Features are grouped in §4 with globally numbered requirements nested under them. Inferred points are tagged [ASSUMPTION] inline and indexed in §10. Look and behavior are specified in _bmad-output/ux-designs/ux-ping-mee-self-service-platform-2026-10-15/ (DESIGN.md, EXPERIENCE.md), which this PRD does not duplicate. Technical choices live in addendum.md, not here.

1. Vision

Every User of the ping-mee homelab can manage their own account in one clean place: change their password, correct their name and contact details, and set a profile picture. The Admin has one channel to tell everyone about planned downtime and changes.

Today every such change, however small, goes through the admin. No existing tool covers these four things together in an Active Directory homelab. The portal is built around the real setup (Active Directory, authentik, the existing picture pipeline), runs as one Docker container behind the existing reverse proxy, and is reachable from the internet. Nothing in it is tied to ping-mee: everything is configurable, so it can be deployed elsewhere later. The homelab is oversized for its ten users, and the portal is built to a standard that matches.

2. Target User

2.1 Jobs To Be Done

• As a User, I want to change my own password, details and picture without asking anyone, so that I stay in control of my account.
• As a User, I want to hear about planned downtime before it happens, so that I am not surprised when a service is gone.
• As the Admin, I want users to handle their own changes, so that I stop doing manual password and profile work.
• As the Admin and Publisher, I want one place to announce changes, so that nobody has to be told twice.
• As the Admin, I want the portal to be safe on the internet, so that exposing it does not put the Active Directory at risk.

2.2 Non-Users (v1)

• Anyone without an Active Directory account in the configured OU.
• Users with an expired or "must change" password. They contact the Admin, who resets the password in Active Directory; they then sign in and change it themselves.
• Anonymous visitors. The portal shows them nothing except the sign-in redirect.

2.3 Key User Journeys

Drafted from the brief and the discovery conversation. Personas are illustrative. [ASSUMPTION: confirm or replace.]

• UJ-1. Lena changes her password before it leaks.

  • Persona + context: Lena, a friend who uses Jellyfin, reuses a password and wants a fresh one.
  • Entry state: not signed in; opens the portal address from a bookmark.
  • Path: signs in through authentik; opens "Password"; enters her current password and the new one twice; submits.
  • Climax: the portal confirms the change and signs her out of other sessions.
  • Resolution: a "password changed" e-mail arrives; she uses the new password everywhere.
  • Edge case: the new password breaks the domain's complexity rule; the portal shows the rule in plain language and nothing changes.

• UJ-2. Tom sets a profile picture from his iPhone.

  • Persona + context: Tom, family, has a HEIC photo and wants it as his avatar.
  • Entry state: signed in, on "Profile".
  • Path: chooses the photo; crops it square in the browser; saves.
  • Climax: the page shows his current picture with a "pending" mark and the note that it updates within about two hours.
  • Resolution: once the sync has run, the mark disappears and the new picture shows.
  • Edge case: the file is 14 MB; the portal rejects it before upload and says why.

• UJ-3. Ebbe announces a maintenance window.

  • Persona + context: Ebbe, the homelab owner, in the Publisher group, plans a server move.
  • Entry state: signed in, on "Announcements".
  • Path: writes a title and Markdown text; sets severity to warning, the downtime window and an expiry; schedules the announcement for the next morning.
  • Climax: at the scheduled time the announcement appears on the page and opted-in users receive the e-mail.
  • Resolution: after the move, Ebbe withdraws the announcement.
  • Edge case: he corrects the end time later; he edits the text and chooses "notify users again".

• UJ-4. Marie sees an e-mail change she did not make.

  • Persona + context: Marie finds an e-mail at her old address saying her address was changed.
  • Entry state: she is not signed in; she reads the message on her phone.
  • Path: opens the undo link within 24 hours.
  • Climax: the old address is restored and all her sessions end.
  • Resolution: she is told to change her password; the Admin gets a notification.

3. Glossary

Used verbatim throughout this PRD and by downstream workflows.

• User — a person with an Active Directory account in the configured OU who signs in to the portal.
• Publisher — a User who is a member of the configured Publisher group and may create Announcements.
• Admin — a User who is a member of the configured Admin group. The Admin group is separate from the Publisher group.
• Portal — the web application this PRD specifies.
• Service Account — the Active Directory account the Portal uses for LDAPS writes. Its rights are limited to the configured OU and a fixed list of attributes.
• Profile Field — one of: first name (givenName), last name (sn), display name (displayName), e-mail (mail), telephone number (telephoneNumber), mobile number (mobile).
• Session — a User's signed-in period in the Portal. It lasts up to 1 hour of inactivity.
• Picture Source File — the file <username>.jpg that the Portal writes to the configured source path of the Share.
• Share — the file share where the Picture Source File is written; the Sync Task reads from it.
• Sync Task — the existing scheduled PowerShell task that turns Picture Source Files into the Active Directory picture attributes. It is not part of the Portal.
• Pending — a Picture Source File has been written but the Sync Task has not processed it yet.
• Announcement — a message from a Publisher with a title, a formatted body (edited in a rich-text editor, stored as Markdown), a Severity, and an optional Downtime Window, expiry and publish time.
• Opt-in / Opt-out — a User's choice to receive or not receive Announcement e-mails. New Users are opted in.
• Audit Entry — a record of who did what, when, and from which IP address.
• Audit Log — the collection of all Audit Entries, readable by Admins.
• Draft — an Announcement that is saved but not published; only Publishers see it.
• Withdrawn — an Announcement that was published and then taken down; Users no longer see it.
• Severity — the level of an Announcement: information, warning or outage. Every Announcement has one; the default is information.
• Downtime Window — the optional start and end time of a planned downtime stated in an Announcement.
• Password Policy — the password rules Active Directory enforces for a User (minimum length, complexity, history), read by the Portal and shown on the password page.
• Preference — a choice stored on the User's device, not on the server: theme (light, dark, system), language, and the German form of address (formal or informal).
• Undo Link — a single-use link, valid for 24 hours, sent to the old address after an e-mail change, that reverts the change.

4. Features

4.1 Sign-in and Sessions

Description: A User signs in through authentik using OIDC. The Portal maps the OIDC identity to the Active Directory account and decides the User's roles from group membership. Realizes UJ-1.

Functional Requirements:

FR-1: Sign in with OIDC

A User can sign in by being redirected to the configured OIDC provider and returning to the Portal. Realizes UJ-1.

Consequences (testable):

• The Portal matches the OIDC preferred_username claim to sAMAccountName in the configured OU.
• A sign-in for a name not found in the OU is refused with a generic message.
• A User whose Active Directory account is disabled or locked cannot start a Session, and an existing Session of such a User ends at its next request.
• An unauthenticated request to any Portal page redirects to sign-in.

Out of Scope:

• Signing in with a local password or directly against LDAPS.

FR-2: Resolve roles

The Portal determines whether a User is a Publisher or an Admin by checking membership of the configured Publisher group and Admin group in Active Directory.

Consequences (testable):

• A User in neither group sees no Announcement editor and no admin pages.
• Direct requests to Publisher or Admin pages by a User without the role return an authorization error.
• Group names come from configuration only.

FR-3: Session lifetime and sign-out

A Session ends after 1 hour of inactivity or when the User signs out. The inactivity time is an Admin-changeable setting. [ASSUMPTION: 1 hour default; whether it also has an absolute maximum is open, see Q-4.]

Consequences (testable):

• Requests after expiry redirect to sign-in.
• Sign-out ends the Session on the server, not only in the browser.

FR-4: Throttle sensitive requests

The Portal limits repeated requests to password change (FR-5), e-mail change (FR-10), the confirmation and Undo Link pages (FR-10, FR-11), and picture upload (FR-12), per User and per IP address, before any call to Active Directory. Sign-in itself is throttled by the OIDC provider, not by the Portal.

Consequences (testable):

• Each covered endpoint has its own configured limit and pause. [ASSUMPTION: defaults are chosen at design time.]
• Once a limit is reached, further requests to that endpoint are refused with a "try again later" message, without contacting Active Directory or the SMTP server.
• Throttled requests are recorded as Audit Entries (FR-28).
• Limits are configurable.
• Failed current-password checks follow the stricter per-User rule in FR-6.

4.2 Password Change

Description: A User changes their own password by entering the current and the new password. The Portal verifies the current password and applies the new one over LDAPS. Active Directory's own complexity, history and age rules apply. Users with expired passwords are not served; they contact the Admin. Realizes UJ-1.

Functional Requirements:

FR-5: Change password

A User can change their password by entering the current password and the new password twice. Realizes UJ-1.

Consequences (testable):

• Before the User types, the page lists the User's Password Policy as read from Active Directory (including a fine-grained policy that applies to the User).
• The current password is verified over LDAPS before the change is applied.
• When Active Directory rejects the new password, the Portal shows the reason in plain language.
• No password is written to logs, the audit log or error output.

FR-6: Limit failed password attempts

The Portal counts failed current-password checks per User and refuses further attempts after a configured limit, with a configured pause. [ASSUMPTION: default 5 failures, then a 15-minute pause.]

Consequences (testable):

• The limit applies before the bind to Active Directory, so it protects the account from lockout by the Portal.
• The limit and pause are configurable.

FR-7: After a password change

After a successful change the Portal ends the User's other Sessions and sends a "password changed" e-mail to the User's address.

Consequences (testable):

• All other Sessions of that User are invalid immediately.
• The e-mail names the time of the change and does not contain the password.

4.3 Profile Data

Description: A User edits their Profile Fields. Every value is validated and escaped before it reaches Active Directory. An e-mail change is a sensitive action: it needs the current password, a confirmation from the new address, and a notice with an Undo Link to the old address. Realizes UJ-4.

Functional Requirements:

FR-8: View and edit Profile Fields

A User can view and edit first name, last name, display name, telephone number and mobile number. The username is shown and cannot be edited.

Consequences (testable):

• Saved values appear in Active Directory under the matching attributes.
• A User can only read and write their own Profile Fields.
• The display name is free text. [ASSUMPTION: no further rules.]

FR-9: Validate and escape input

The Portal validates length, characters and format of each Profile Field and escapes values for LDAP.

Consequences (testable):

• LDAP filter and DN injection strings do not alter queries or write to other objects.
• Invalid input is rejected with a message naming the field.
• Phone number format is checked. [ASSUMPTION: international format with digits, spaces, +, - and brackets.]

FR-10: Change e-mail with confirmation

A User can change their e-mail by entering the current password and the new address. The change applies only after the User opens a confirmation link sent to the new address. Realizes UJ-4.

Consequences (testable):

• The current password is verified before the confirmation e-mail is sent, and counts against the failed-attempt limit in FR-6.
• The confirmation link is single-use and expires after 1 hour. [ASSUMPTION]
• Opening the link shows a page that names the pending change and applies it only after the User clicks a confirm button (POST). A plain GET of the link changes nothing, so mail scanners cannot confirm it.
• Until confirmed, mail in Active Directory is unchanged.

FR-11: Notify the old address and offer undo

When an e-mail change is applied, the Portal sends a notice to the old address that includes an Undo Link valid for 24 hours. Realizes UJ-4.

Consequences (testable):

• Opening the Undo Link shows a page that names the change and restores the old address in Active Directory only after the User clicks a confirm button (POST). A plain GET of the link changes nothing, so mail scanners cannot trigger an undo.
• Undo also ends all Sessions of that User, tells the User to change their password, and notifies the Admin.
• The Undo Link works once and expires after 24 hours.

4.4 Profile Picture

Description: A User uploads a picture, crops it in the browser, and the Portal writes a square JPEG named <username>.jpg to the Share. The Sync Task, which stays unchanged, makes the 96px and 448px versions and writes the Active Directory attributes within about two hours. The Portal shows the current picture from Active Directory with a Pending mark until the Sync Task has processed the new file. Realizes UJ-2.

Functional Requirements:

FR-12: Upload and convert a picture

A User can upload a JPEG, PNG, HEIC or WebP file of up to 10 MB. The Portal re-encodes it as a square JPEG of at least 448 px [ASSUMPTION: 512×512] and writes it as the Picture Source File. Realizes UJ-2.

Consequences (testable):

• The file is named <username>.jpg regardless of the uploaded name, replacing any earlier file.
• Other formats, including SVG, and files over 10 MB are rejected before upload with a clear message.
• Metadata is removed from the output.
• The original upload is not stored or served.

FR-13: Crop and edit in the browser

A User can crop the picture to a square and adjust it before saving. [ASSUMPTION: crop, zoom and rotate; no filters.]

Consequences (testable):

• The Portal re-validates and re-encodes the result on the server, whatever the browser sends.

FR-14: Show current picture and Pending status

The Portal shows the User's current picture read from the Active Directory picture attribute and marks it Pending after an upload. Realizes UJ-2.

Consequences (testable):

• The Pending mark clears when the MD5 of the written Picture Source File equals the content of <username>.md5 in the configured processed path.
• The User sees the note that updates take about two hours.
• If Pending lasts longer than a configured time, the Portal says it is taking longer than expected. [ASSUMPTION]

FR-15: Remove the picture

A User can remove their picture, which deletes the Picture Source File so the Sync Task falls back to the default image.

Consequences (testable):

• The Portal shows Pending until the Sync Task has restored the default.

4.5 Announcements

Description: A Publisher writes Announcements in a rich-text editor that shows the finished result (bold, italic, heading, list, link); the text is stored as Markdown. Users read them on a page after signing in, and opted-in Users receive them by e-mail. Realizes UJ-3.

Functional Requirements:

FR-16: Create, save as draft and publish

A Publisher can write an Announcement with a title and body, save it as a draft, and publish it. Realizes UJ-3.

Consequences (testable):

• Only Publishers can create, edit, withdraw or publish.
• The body is edited in a rich-text editor with a toolbar for bold, italic, heading, list and link; the Publisher never sees Markdown syntax.
• The body is stored as Markdown and sanitized every time it is shown: HTML and script content never executes.

FR-17: Severity and optional fields

Every Announcement has a Severity (information, warning or outage); the default is information and it cannot be left empty. A Publisher can add a Downtime Window, an expiry and a publish time.

Consequences (testable):

• An expired Announcement no longer appears in the active list.
• An Announcement with a future publish time appears and is e-mailed at that time only.
• Severity decides the colour, icon and wording of the banner (FR-19).

FR-18: Edit, withdraw and notify again

A Publisher can edit or withdraw an Announcement. Editing never sends e-mail on its own; the Publisher can choose "notify users again".

Consequences (testable):

• A withdrawn Announcement disappears from the Users' page.
• "Notify again" sends one new e-mail to opted-in Users.

FR-19: Announcement page and banner

A signed-in User can read current and past Announcements on a page, newest first. Active Announcements show a banner on the home page.

Consequences (testable):

• Signed-out visitors cannot read any Announcement.
• The banner shows severity.

FR-20: Send Announcement e-mail

When an Announcement is published, every opted-in User receives it by e-mail through the configured SMTP server.

Consequences (testable):

• Recipients are all Users in the configured OU with a valid mail value in Active Directory, whether or not they have ever signed in, except those who are opted out.
• A User with no valid mail value is skipped, and the skip is recorded so the Admin can see who was not reached.
• Before publishing, the Publisher sees how many Users will receive the e-mail and how many are left out because they opted out or have no address.
• Users who are opted out receive nothing, regardless of severity.
• Sending failures are recorded and visible to the Admin. [ASSUMPTION]

FR-21: Opt in and out

A User can opt in or out of Announcement e-mails at any time. Every User is opted in by default, including Users who have never signed in; the Portal stores only explicit opt-outs. Opting out shows a notice that they will receive no downtime notifications and can opt back in on the Portal.

4.6 Admin UI

Description: An Admin manages how the Portal looks and behaves, and reads the audit log. Admins cannot edit other Users' data; the Admin UI manages only the Portal.

Functional Requirements:

FR-22: Accent colour and backgrounds

An Admin can choose the portal-wide accent colour and upload background images. The default accent is the Fluent blue and the default look follows the Microsoft 365 admin center. [ASSUMPTION: verify the default blue against the Fluent web components at build.]

Consequences (testable):

• When the Admin enters a colour, the Portal shows its contrast for the light and the dark theme and a warning if it is below WCAG AA (4.5:1); the Admin can still save it.
• Uploaded images are re-encoded and limited in size.
• Backgrounds are shown only to signed-in Users. Anonymous visitors see nothing but the sign-in redirect (§2.2).

FR-23: Runtime settings

An Admin can change cosmetic and behaviour settings: portal name, session inactivity time, failed-attempt limit and pause, audit retention.

Consequences (testable):

• Settings that identify a system or contain a secret (Active Directory, LDAPS, Service Account, SMTP, OIDC, paths, group names) are not changeable here.

FR-24: Audit log viewer

An Admin can read the audit log.

Consequences (testable):

• The log is not visible to non-Admins.
• Entries older than the configured retention (default 12 months) are removed automatically.

FR-25: Admin access control

Only members of the Admin group can open Admin UI pages.

4.7 Platform and Operations

Description: The Portal runs as one Docker container on a Linux host behind a reverse proxy that terminates TLS. All connection settings and secrets come from environment variables.

Functional Requirements:

FR-26: Configuration through environment variables

All system-specific values come from documented environment variables with safe defaults.

Consequences (testable):

• Nothing in the image names ping-mee, a domain, an OU, a group, an IP address or a path.
• Secrets never appear in logs or in the Admin UI.

FR-27: Docker delivery

The Portal is delivered as a Docker image that runs with the Share mounted and persists its data in a mounted volume. It exposes a health check.

FR-28: Record audit entries

The Portal records an Audit Entry for password changes, Profile Field changes, e-mail change requests, confirmations and undos, picture uploads and removals, Announcement actions, settings changes, and failed and throttled sign-in and password attempts. Each entry holds who, what, when and the IP address.

Consequences (testable):

• No password, token or picture content appears in an entry.

FR-29: Interface language

The interface is available in German and English. The language is chosen from the browser's language and the User can switch it (see FR-31). German has a formal and an informal form of address; the Admin sets the portal-wide default (formal).

4.8 Dashboard, Preferences and Status

Description: The landing page shows what matters now, each User sets how the portal looks and speaks on their own device, and the Admin sees on one page whether the background work is healthy. See the UX documents for layout and wording. Realizes UJ-1, UJ-3.

Functional Requirements:

FR-30: Dashboard

After signing in, a User lands on a dashboard that shows all active Announcements as banners and an account card with picture (with its Pending status), name, username, e-mail, telephone number and the date the password was last changed.

Consequences (testable):

• Active Announcements appear newest first with their Severity.
• The password date comes from Active Directory.
• The card links to the profile page.

FR-31: Per-device Preferences

A User can set theme (light, dark or system), language and, in German, the form of address (formal or informal) from a menu opened from their picture in the upper right. The choices are stored on the device.

Consequences (testable):

• The default theme is the system theme and the default language comes from the browser.
• The form-of-address choice is shown only when the language is German.
• The choices take effect immediately and are not stored on the server.
• E-mails use the portal-wide default form of address, because the device choice cannot reach them. [ASSUMPTION]

FR-32: Status page

An Admin can see on one page the age of the last successful database backup, the e-mails that failed to send with their reason, and the last run and result of each background job.

Consequences (testable):

• A backup older than a configured age (default 26 hours) is marked as a problem.
• An e-mail that failed after the configured number of attempts stays listed until it is resolved.
• No other alert (e-mail or otherwise) is sent. [Decision: the Admin watches this page.]

5. Non-Goals (Explicit)

• Not an Active Directory admin console: Admins cannot edit other Users' data or reset passwords here.
• No forgotten-password reset and no expired-password flow. The Admin handles both by hand.
• No editing of cn or name, and so no object renames.
• No multi-domain support.
• No replacement of the PowerShell scripts or the Sync Task.
• No public announcement page or status page.
• No SVG uploads.
• Not a general identity provider: sign-in stays with authentik.

6. MVP Scope

6.1 In Scope

• Everything in §4, shipped together. [Decision: the Admin chose not to phase the first release; sequencing is left to epics and stories.]

6.2 Out of Scope for MVP

• Everything in §5.

7. Success Metrics

Primary

• SM-1: Number of known-password changes done by the Admin by hand per month — target 0 after rollout. Validates FR-5.
• SM-2: Share of profile and picture changes made by Users themselves — target: all of them. Validates FR-8, FR-12.
• SM-3: Share of planned downtimes announced through the Portal — target 100%. Validates FR-16, FR-20.

Secondary

• SM-4: Time from Publish to e-mail delivery for opted-in Users. Validates FR-20.
• SM-5: Share of Pending pictures cleared within the expected time. Validates FR-14.

Counter-metrics (do not optimize)

• SM-C1: Number of Announcements or e-mails sent. More is not better; this counterbalances SM-3.
• SM-C2: Session length. Do not lengthen Sessions for convenience at the cost of safety. Counterbalances SM-2.
• SM-C3: Failed-attempt limits. Do not relax them to reduce support messages. Counterbalances SM-1.

8. Cross-Cutting Requirements

8.1 Security (system-wide)

• Injection (LDAP, SQL, script) does not work against any input.
• A stolen or hijacked Session does not give lasting access: sensitive actions require the current password, and sensitive changes notify the old contact.
• A User can never read or write another User's data.
• The Service Account has the minimum rights: only the configured OU and the listed attributes.
• Uploaded files are re-encoded; the original is never served; decoding runs with limits against decompression bombs.
• Cookies are secure, CSRF protection and security headers are enabled.

8.2 Privacy

• Personal data (names, e-mail, phone, picture, audit entries) is processed only for the functions above. Audit retention is 12 months by default and configurable.
• Data of Users removed from Active Directory is removed from the Portal. [ASSUMPTION: see Q-6.]

8.3 Reliability and Operations

• Failures of the Share, SMTP or Active Directory are reported to the User in plain language and recorded in the audit log or logs.
• The Portal depends on authentik being available for sign-in. [ASSUMPTION: accepted.]

8.4 Accessibility and Look

• The interface follows the Microsoft 365 admin center look (see the UX documents) and meets WCAG 2.1 AA. [ASSUMPTION]

9. Open Questions

• Q-1. Resolved in architecture (AD-10): if the Share is unreachable during an upload, the User sees an error and nothing changes.
• Q-2. Partly resolved (AD-11): failed e-mails are retried with backoff and a rate limit and stay listed for the Admin. Still open: the exact retry count and the IONOS sending limits.
• Q-4. Resolved in architecture (AD-6): the absolute session limit is 4 hours, on top of 1 hour of inactivity; both are settings.
• Q-5. Resolved in architecture (AD-14): SQLite in WAL mode on a volume, with consistent backup files written to a backup folder that the Admin's host copy job copies. Still open: how a restore is tested.
• Q-6. Resolved in architecture (AD-12): a nightly reconciliation removes data of Users no longer in the OU; audit entries stay until retention ends.
• Q-7. Resolved in architecture (AD-10): for a removed picture, Pending clears when the processed MD5 differs from the previous one.
• Q-8. Resolved in architecture (AD-15): stored in UTC, shown in the configured zone (default Europe/Berlin), zone named in e-mails.
• Q-9. Accepted limitation (AD-10): the Sync Task writes <username>.md5 before it sets the Active Directory attributes, so a failed attribute write can clear Pending early. The "taking longer than expected" message and the Admin's checks are the safety net.

10. Assumptions Index

• §4.1 FR-3 — 1 hour default with an Admin-changeable value.
• §4.1 FR-4 — default limits per endpoint are chosen at design time.
• §4.2 FR-6 — default 5 failures, 15-minute pause.
• §4.3 FR-8, FR-9, FR-10 — display name has no rules; phone format; 1-hour single-use confirmation link.
• §4.4 FR-12, FR-13, FR-14 — 512×512 output; crop, zoom and rotate only; "taking longer than expected" threshold.
• §4.5 FR-20 — sending failures visible to the Admin.
• §4.6 FR-22 — default accent is the Fluent blue; verify at build.
• §4.8 FR-31 — e-mails use the portal-wide form of address.
• §4.7 FR-29 — resolved: German and English.
• §8.2–8.4 — user data removal, authentik availability, WCAG 2.1 AA.
• §2.3 — journeys and personas are illustrative.