ahmido bc846d7c5c 051-entra-group-directory-cache (#57 )

Summary

Adds a tenant-scoped Entra Groups “Directory Cache” to enable DB-only group name resolution across the app (no render-time Graph calls), plus sync runs + observability.

What’s included
• Entra Groups cache
• New entra_groups storage (tenant-scoped) for group metadata (no memberships).
• Retention semantics: groups become stale / retained per spec (no hard delete on first miss).
• Group Sync Runs
• New “Group Sync Runs” UI (list + detail) with tenant isolation (403 on cross-tenant access).
• Manual “Sync Groups” action: creates/reuses a run, dispatches job, DB notification with “View run” link.
• Scheduled dispatcher command wired in console.php.
• DB-only label resolution (US3)
• Shared EntraGroupLabelResolver with safe fallback Unresolved (…last8) and UUID guarding.
• Refactors to prefer cached names (no typeahead / no live Graph) in:
• Tenant RBAC group selects
• Policy version assignments widget
• Restore results + restore wizard group mapping labels

Safety / Guardrails
• No render-time Graph calls: fail-hard guard test verifies UI paths don’t call GraphClientInterface during page render.
• Tenant isolation & authorization: policies + scoped queries enforced (cross-tenant access returns 403, not 404).
• Data minimization: only group metadata is cached (no membership/owners).

Tests / Verification
• Added/updated tests under tests/Feature/DirectoryGroups and tests/Unit/DirectoryGroups:
• Start sync → run record + job dispatch + upserts
• Retention purge semantics
• Scheduled dispatch wiring
• Render-time Graph guard
• UI/resource access isolation
• Ran:
• ./vendor/bin/pint --dirty
• ./vendor/bin/sail artisan test tests/Feature/DirectoryGroups
• ./vendor/bin/sail artisan test tests/Unit/DirectoryGroups

Notes / Follow-ups
• UI polish remains (picker/lookup UX, consistent progress widget/toasts across modules, navigation grouping).
• pr-gate checklist still has non-blocking open items (mostly UX/ops polish); requirements gate is green.

Co-authored-by: Ahmed Darrazi <ahmeddarrazi@adsmac.local>
Reviewed-on: #57

2026-01-11 23:24:12 +00:00

1.8 KiB

Raw Blame History

Quickstart: Entra Group Directory Cache (Groups v1)

Goal

Populate a tenant-scoped cache of Entra ID groups (metadata only) via background sync runs, enabling safe UI rendering without live directory calls.

Prerequisites

Graph integration configured (client credentials / app-only)
Database migrated (feature migrations applied)
Queue worker running for jobs (required for sync)
Scheduler/cron running for periodic sync (optional, if enabled)

Local (Sail) quick commands

Bring containers up: ./vendor/bin/sail up -d
Run migrations: ./vendor/bin/sail artisan migrate
Run the queue worker (separate terminal): ./vendor/bin/sail artisan queue:work
Run the scheduler loop (separate terminal, optional): ./vendor/bin/sail artisan schedule:work

Operator workflow (manual)

Switch into a tenant workspace.
Go to Directory → Group Sync Runs.
Click Sync Groups (creates/reuses a run and dispatches a background job).
Open the run and wait for status to complete.
Go to Directory → Groups and confirm list/search/detail are populated from the cache.

Notes

Search is cached-only and typically requires at least 2 characters.
If the cache is empty, the Groups list will be empty until a sync completes.

Scheduled sync

Ensure the scheduler is running (cron or schedule:work).
Verify Directory → Group Sync Runs shows runs with empty Initiator (scheduled).
The dispatcher command is tenantpilot:directory-groups:dispatch (configured to run every minute).

Verification

UI pages that show group IDs render using cached data only.
Unresolved IDs show a clear fallback.
Groups not seen for >90 days are eventually purged.

Suggested validation checks

./vendor/bin/sail artisan migrate:status | grep entra_group
./vendor/bin/sail artisan schedule:list | grep directory-groups

1.8 KiB Raw Blame History