TenantAtlas/specs/051-entra-group-directory-cache/quickstart.md

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)
• Queue worker running for jobs
• Scheduler/cron running for periodic sync (if enabled)

Operator workflow (manual)

1. Switch into a tenant workspace.
2. Start “Sync Groups”.
3. Check the run status until it completes.
4. Browse “Directory → Groups” and confirm search + detail work.

Scheduled sync

• Enable scheduled sync for tenants/environment.
• Verify runs appear without manual initiation.

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.