Entra ID Integration Setup Guide

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.

​

Quick Start (5 Minutes)

​

Prerequisites

• Azure CLI installed (az --version works)
• Azure account with Global Administrator or Application Administrator role
• Supabase project linked (npx supabase link --project-ref zkgxozahyczcnzpwhbbf)
• Supabase CLI available (via npx supabase)

​

Automated Setup

.\scripts\entra\create-app-registration.ps1

chmod +x scripts/entra/create-app-registration.sh
./scripts/entra/create-app-registration.sh

npm run entra:setup

1. Create app registration
2. Add API permissions
3. Generate client secret (save it when shown!)
4. Store secrets in Supabase
5. Generate admin consent URL
6. Create setup log

​

Manual Setup Steps

​

Step 1: Login to Azure

az login

az account show
az account show --query tenantId --output tsv

​

Step 2: Create App Registration

az ad app create \
  --display-name "Encore Health OS - Entra ID Integration" \
  --sign-in-audience AzureADMyOrg \
  --web-redirect-uris "https://zkgxozahyczcnzpwhbbf.supabase.co/functions/v1/entra-oauth/callback"

​

Step 3: Add API Permissions

APP_ID="<your-app-id>"

az ad app permission add \
  --id $APP_ID \
  --api 00000003-0000-0000-c000-000000000000 \
  --api-permissions df021288-bdef-4463-88db-98f22de89214=Role \
  --api-permissions 1bfefb4e-e0b5-418b-a88f-73c46d2cc8e9=Role

• df021288-bdef-4463-88db-98f22de89214 = User.ReadWrite.All (Application)
• 1bfefb4e-e0b5-418b-a88f-73c46d2cc8e9 = LicenseAssignment.ReadWrite.All (Application)

​

Step 4: Create Client Secret

az ad app credential reset \
  --id $APP_ID \
  --years 2 \
  --display-name "Encore Health OS Integration Secret"

​

Step 5: Store Secrets in Supabase

# Link to production project
npx supabase link --project-ref zkgxozahyczcnzpwhbbf

# Store secrets
npx supabase secrets set ENTRA_TEST_APP_ID=<your-app-id>
npx supabase secrets set ENTRA_TEST_CLIENT_SECRET=<your-client-secret>
npx supabase secrets set ENTRA_TEST_TENANT_ID=<your-tenant-id>

# Verify
npx supabase secrets list

​

Step 6: Grant Admin Consent

TENANT_ID="<your-tenant-id>"
APP_ID="<your-app-id>"
REDIRECT_URI="https://zkgxozahyczcnzpwhbbf.supabase.co/functions/v1/entra-oauth/callback"

# PowerShell
$ENCODED_URI = [System.Uri]::EscapeDataString($REDIRECT_URI)
$ADMIN_CONSENT_URL = "https://login.microsoftonline.com/${TENANT_ID}/adminconsent?client_id=${APP_ID}&redirect_uri=${ENCODED_URI}"
Write-Host $ADMIN_CONSENT_URL

# Bash
ADMIN_CONSENT_URL="https://login.microsoftonline.com/${TENANT_ID}/adminconsent?client_id=${APP_ID}&redirect_uri=$(echo $REDIRECT_URI | jq -sRr @uri)"
echo $ADMIN_CONSENT_URL

​

Current Configuration

​

Verification Checklist

• Azure CLI installed and working
• Logged in to Azure CLI
• App registration created successfully
• API permissions added (User.ReadWrite.All, LicenseAssignment.ReadWrite.All)
• Client secret created and captured
• Secrets stored in Supabase
• Admin consent URL generated
• Callback handler deployed (entra-oauth edge function)
• Public access configured (verify_jwt = false in config.toml)
• Admin consent granted

​

Troubleshooting

​

”Insufficient privileges”

• Solution: Ensure user has Global Administrator or Application Administrator role

​

”App registration not found”

• Solution: Verify APP_ID is correct, check with az ad app list --display-name "Encore Health OS*"

​

”Permission not found”

• Solution: Verify permission IDs are correct, check Microsoft Graph API permission reference

​

”Client secret not shown”

• Solution: Secret is only shown once. If lost, create new secret with az ad app credential reset

​

”Missing authorization header” (401 error)

• Solution: Ensure verify_jwt = false is set in supabase/config.toml for entra-oauth function

​

Security Notes

1. Client Secret: Only shown once during creation - save immediately
2. Storage: For testing, use Supabase secrets. For production, will use per-organization Vault storage
3. Documentation: Never commit client secrets to git
4. Rotation: Client secrets expire in 2 years - plan rotation before expiration

​

Related Documentation

• Gap Analysis: archived at docs/archive/integrations/ENTRA_ID_GAP_ANALYSIS.md (superseded by PF-63 implementation)
• Research Findings: ENTRA_ID_RESEARCH_FINDINGS.md
• Overview: ENTRA_ID_OVERVIEW.md
• 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