> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Entra ID Integration Overview

> Specification: PF-63 Status: ✅ Complete Date: 2026-01-28

**Specification:** PF-63\
**Status:** ✅ Complete\
**Date:** 2026-01-28

***

## What Is This?

PF-63 implements a complete Microsoft Entra ID/Office 365 integration that automates:

* **User Provisioning:** Office 365 users created automatically when employees are created
* **License Assignment:** Automatic license assignment based on organization configuration
* **Account Lifecycle:** Disable/delete accounts when employees are terminated
* **Email Integration:** Use provisioned accounts for email sending
* **Teams Integration:** Automatic Teams channel membership based on department
* **SharePoint Integration:** Automatic SharePoint group membership based on department
* **Calendar Sync:** Leave requests synced to Outlook calendars
* **Directory Sync:** Employee data changes synced to Entra ID

***

## Current Status

### ✅ All Phases Complete (2026-01-28)

* [x] **Phase 0: Setup & Research** - Azure app registration, admin consent, documentation
* [x] **Phase 1: Database Schema & Core Provisioning** - Org config, employee tracking, Graph API client
* [x] **Phase 2: Enhanced Email Integration** - Domain validation, email generation, sending
* [x] **Phase 3: Teams, SharePoint, Calendar, Directory Sync** - All M365 integrations
* [x] **Phase 4: UI Configuration Components** - Settings pages and employee status displays
* [x] **Phase 5: Testing, Integration & Finalization** - Leave calendar sync, RLS tests, documentation

### Edge Functions Deployed

| Function                      | Purpose                                      |
| ----------------------------- | -------------------------------------------- |
| `entra-provision-user`        | Create Entra ID user with license assignment |
| `entra-disable-user`          | Disable/delete terminated employee accounts  |
| `entra-register-app`          | Programmatic Azure app registration          |
| `entra-oauth`                 | OAuth callback handler for admin consent     |
| `entra-teams-membership`      | Teams channel membership management          |
| `entra-sharepoint-membership` | SharePoint group membership management       |
| `entra-calendar-sync`         | Leave request calendar event sync            |
| `entra-sync-directory`        | Employee data sync to Entra ID               |

***

## Key Features

### 1. Automated Setup

* **App Registration:** Created automatically via Microsoft Graph API
* **Admin Consent:** One-time URL visit (with option for programmatic grant)
* **Helper Scripts:** Azure CLI setup assistant for org admins

### 2. User Provisioning

* **Automatic:** Office 365 users created when employees are created
* **Secure:** Strong password generation, force change on first sign-in
* **Licenses:** Auto-assigned based on organization configuration
* **Status:** Full visibility into provisioning status and errors

### 3. Account Lifecycle

* **Disable:** Accounts disabled when employees are terminated
* **Delete:** Accounts deleted after grace period (configurable)
* **Restore:** Accounts can be restored if employee is rehired within grace period

### 4. Email Integration

* **Domain Validation:** Validates email domain matches organization
* **Auto-Generate:** Creates email addresses from employee names
* **Send Email:** Uses provisioned accounts for email sending

### 5. Future Enhancements

* **Teams:** Automatic Teams membership assignment
* **SharePoint:** SharePoint group assignment
* **Calendar:** Calendar sync for leave requests
* **Directory Sync:** Bidirectional sync of employee data changes

***

## Implementation Phases

### Phase 1: Core Provisioning (Weeks 1-2)

* Database schema migration
* Automated Azure app registration
* Admin consent flow with tooltips
* Automatic user provisioning on employee creation
* License assignment
* Account lifecycle management

### Phase 2: Enhanced Email (Week 3)

* Email domain validation
* Auto-generate email addresses
* Use provisioned accounts for email sending

### Phase 3: Additional Integrations (Week 4+)

* Teams membership automation
* SharePoint group assignment
* Calendar sync (leave requests)
* Directory sync (employee data changes)

***

## Documentation Structure

### Setup & Configuration

* **[Setup Guide](./ENTRA_ID_SETUP.md)** - Complete setup instructions
* **Gap Analysis** (archived; superseded by PF-63 implementation — see `docs/archive/integrations/ENTRA_ID_GAP_ANALYSIS.md`)
* **[Research Findings](./ENTRA_ID_RESEARCH_FINDINGS.md)** - Programmatic app registration research

### Implementation

* **Specification:** `specs/pf/specs/PF-63-entra-id-integration.md`
* **Implementation Plan:** `specs/pf/plans/PF-63-entra-id-integration-PLAN.md`
* **Tasks:** `specs/pf/tasks/PF-63-TASKS.md`

### Scripts & Tools

* `scripts/entra/create-app-registration.sh` - Automated setup (Linux/macOS)
* `scripts/entra/create-app-registration.ps1` - Automated setup (Windows)
* `scripts/entra/store-entra-secrets.sh` - Secret storage (Linux/macOS)
* `scripts/entra/store-entra-secrets.ps1` - Secret storage (Windows)
* `scripts/entra/README.md` - Scripts documentation

***

## Configuration Summary

| Component              | Value                                                                        | Status       |
| ---------------------- | ---------------------------------------------------------------------------- | ------------ |
| **App ID (Client ID)** | `e02d8a52-e3e3-4569-a884-b7352619ec01`                                       | ✅ Active     |
| **Tenant ID**          | `894b815c-98a1-4651-b498-ce5122f9bfe6`                                       | ✅ Verified   |
| **Client Secret**      | Stored in Supabase secrets                                                   | ✅ Secure     |
| **Redirect URI**       | `https://zkgxozahyczcnzpwhbbf.supabase.co/functions/v1/entra-oauth/callback` | ✅ Configured |
| **Admin Consent**      | Granted (2026-01-28)                                                         | ✅ Complete   |
| **Project**            | Production (`zkgxozahyczcnzpwhbbf`)                                          | ✅ Linked     |

***

## UI Components

### Settings Page

Access the Entra ID settings at `/settings/integrations/entra`. The page includes:

* **General Tab:** Enable/disable integration, provisioning settings, grace period
* **Teams Tab:** Department-to-channel mappings, bulk sync
* **SharePoint Tab:** Department-to-group mappings
* **Calendar Tab:** Leave request sync configuration
* **Directory Sync Tab:** Field selection, sync logs, manual sync trigger

### Employee Detail Page

When Entra is enabled and an employee is provisioned, the employee detail page shows a **Microsoft 365** tab with:

* Office 365 account status and provisioning details
* Teams channel memberships
* SharePoint group memberships
* Directory sync status

***

## Security Considerations

1. **Client Secret:** Stored securely in Supabase secrets, never committed to git
2. **Expiration:** Plan rotation before 2028-01-28
3. **Production:** Uses per-organization Vault storage
4. **Permissions:** Application permissions require admin consent
5. **RLS:** All database tables enforce tenant isolation
6. **PHI Protection:** No PHI is sent to Microsoft Graph API

***

## Deferred Enhancements

* Role-based license assignment (assign different licenses based on employee role)
* Programmatic admin consent (requires Azure AD P1/P2 license)
* Certificate-based authentication (requires Azure Key Vault integration)
* Bidirectional directory sync (currently one-way: Encore Health OS → Entra)

***

**Last Updated:** 2026-01-28\
**Status:** ✅ Complete