microsoft / microsoft/simplechat
Add manager-aware review workflows for feedback and safety violations
- Dominant language
- Python
- Stars
- 152
- Forks
- 116
- Avg merge
- 7h 7m
- Merged PRs (30d)
- 122
Description
## Summary
Enrich user profiles, feedback records, and safety violation records with the signed-in user's direct manager from Microsoft Entra ID through Microsoft Graph. Add a manager review workflow with in-app notifications, user/manager discussion, manager recommendations, continued admin oversight, admin-only archive/delete controls, and a complete audit history.
## User Value
Admins need organizational context when reviewing feedback and safety events, while managers need a controlled way to review events involving their direct reports, communicate with the user, and recommend dismissal or further action. A durable activity history is required so every decision and interaction can be audited.
## Current State
- Browser login stores Entra ID token claims in the session; Teams SSO supplements them with Microsoft Graph `/me` data.
- Manager information is not present in the current session contract and is not persisted in the `user_settings` profile document.
- Persisted user profiles currently synchronize email, display name, and profile image.
- The configured delegated Graph scopes include `User.Read`, `User.ReadBasic.All`, `People.Read.All`, and `Group.Read.All`, but none grants access to the manager relationship.
- Feedback and safety violations already have separate admin review pages, backend routes, exports, and role checks.
- Existing notifications are in-app and user-scoped. The initial manager workflow should reuse this system.
- Existing feedback and safety updates do not provide the item-level, append-only audit timeline required by this workflow.
## Proposed Behavior
### Manager profile enrichment
- During normal browser login and Teams SSO, call Microsoft Graph `GET /me/manager` after token acquisition.
- Store a normalized direct-manager snapshot in the user's persisted profile, including the manager's Entra object ID, display name, email or UPN, lookup timestamp, and source.
- Refresh manager information on subsequent successful logins so organizational changes are reflected.
- Treat a missing manager, guest/personal account, Graph `404`, consent failure, or transient Graph failure as a non-blocking login condition. Record safe diagnostics and preserve the last known manager with freshness metadata where appropriate.
- Do not trust client-supplied manager identity for authorization.
### Feedback and safety context
- Add the user's manager information to newly created feedback and safety violation records as an event-time snapshot so later manager changes do not rewrite historical context.
- Show manager name and contact information in the admin feedback and safety review experiences and exports.
- Define legacy behavior explicitly: use persisted profile data where it is safe to do so, and label records for which event-time manager information was not captured rather than silently presenting current data as historical fact.
### Manager review workflow
- Allow an authorized admin to send an in-app notification assigning or informing the recorded direct manager about a feedback item or safety violation.
- Provide managers with a review queue limited to items assigned to them or involving their verified direct reports.
- Allow the subject user, assigned manager, and authorized admins to participate in an item-level discussion according to documented access rules.
- Allow the manager to record a structured recommendation such as dismiss, no action, take action, or escalate, with required rationale where appropriate.
- Keep final administrative status/action controls with the existing FeedbackAdmin or SafetyViolationAdmin roles. A manager recommendation must not directly suspend, block, delete, or otherwise administer a user.
- Allow admins to reassign or close manager review when the reporting relationship changes, while retaining the original event-time manager and assignment history.
### Archive, delete, and audit
- Add admin-only archive/unarchive actions for feedback and safety violations; archived records are excluded from default queues and remain searchable/filterable by authorized admins.
- Add admin-only deletion with explicit confirmation and a required reason.
- Define deletion and retention semantics so deleted sensitive content is removed as intended while a minimal immutable tombstone remains sufficient to audit who deleted which record, when, and why.
- Maintain an append-only activity timeline per feedback item and safety violation covering creation, manager capture/refresh, assignment/reassignment, notifications, views/acknowledgements where available, user/manager/admin comments, recommendations, status/action changes, archive/unarchive, and deletion.
- Record actor ID, actor role, timestamp, action, and structured before/after metadata without duplicating secrets or unnecessary sensitive content.
## Security and Authorization Requirements
- Resolve manager identity server-side from Microsoft Graph and persisted trusted data.
- Enforce object-level authorization on every read and mutation: users can access only their own records, managers only verified assigned/direct-report records, feedback admins only feedback workflows, and safety violation admins only safety workflows unless another existing role explicitly grants access.
- Archive and delete endpoints must be admin-only and covered by negative authorization tests.
- Prevent manager changes from granting access to unrelated historical records without an explicit, audited reassignment.
- Preserve current route Swagger security decorators, CSRF protections, frontend settings sanitization, and safe logging requirements.
## Microsoft Graph Permissions
- Add delegated `User.Read.All` (`a154be20-db9c-4678-8ab7-66f6cc099a59`) and request tenant admin consent. Microsoft Graph documents this as the least-privileged delegated permission for `GET /me/manager` and it permits reading users' managers.
- Update deployment automation and setup/upgrade documentation for existing installations, including the required re-consent step.
- The initial in-app notification design does not require `Mail.Send`, `TeamsActivity.Send`, or another Graph messaging permission.
- If background lookup without a signed-in user or external email/Teams delivery is added later, evaluate it separately and document the additional permission and consent impact before implementation.
## Acceptance Criteria
- [ ] Browser login and Teams SSO retrieve the signed-in user's direct manager from Microsoft Graph without making login fail when manager data is unavailable.
- [ ] `User.Read.All` delegated permission and tenant admin consent are configured in supported deployment paths and documented for new and existing installations.
- [ ] User profiles persist a normalized manager snapshot with freshness/source metadata and refresh it on login.
- [ ] New feedback and safety violation records preserve event-time manager context.
- [ ] Admin feedback and safety pages, details, filters/search as appropriate, and exports display manager context without exposing unrelated profile data.
- [ ] An admin can notify/assign the manager through an in-app notification for both feedback and safety workflows.
- [ ] Managers have a least-privilege review queue and can discuss the item and submit a structured recommendation with rationale.
- [ ] The subject user can participate in the authorized discussion, and admins retain full oversight and final workflow control.
- [ ] Manager recommendations cannot directly execute privileged safety actions or administrative deletion.
- [ ] Only the relevant authorized admin roles can archive, unarchive, or delete feedback and safety records.
- [ ] Archived records are omitted from default queues but remain available to authorized admins.
- [ ] Delete requires confirmation and a reason, removes content according to documented retention rules, and leaves only the minimal audit tombstone.
- [ ] Every workflow interaction and state transition appears in an append-only item activity timeline with actor, role, timestamp, action, and safe structured change details.
- [ ] Legacy records and users with no manager are handled explicitly and do not produce misleading historical manager attribution.
- [ ] Functional/API tests cover Graph success, no-manager `404`, consent/error fallback, manager refresh, direct-report isolation, cross-manager denial, user/admin access, recommendations, notification delivery, archive/unarchive/delete, audit history, and both feedback and safety workflows.
- [ ] UI tests cover manager context, notification/review flows, discussion/recommendation states, archive filters, delete confirmation, and accessible status/error handling.
- [ ] Feature documentation, Graph permission/setup documentation, release notes, and application version are updated.
## Implementation Context
Likely extension points include:
- `application/single_app/route_frontend_authentication.py`
- `application/single_app/functions_settings.py`
- `application/single_app/config.py`
- `deployers/Initialize-EntraApplication.ps1`
- `application/single_app/route_backend_feedback.py`
- `application/single_app/route_backend_safety.py`
- `application/single_app/functions_notifications.py`
- `application/single_app/functions_activity_logging.py`
- feedback/safety admin templates and JavaScript
- profile/manager review routes and UI
- functional route, authorization, workflow, and UI tests
Microsoft Graph reference: https://learn.microsoft.com/graph/api/user-list-manager?view=graph-rest-1.0
Contributor guide
Assessment
This issue has not been assessed yet.