Entra ID Integration Setup Guide

​

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 anuwknikgsijbameytzr)
• 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 OS - Entra ID Integration" \
  --sign-in-audience AzureADMultipleOrgs \
  --web-redirect-uris "https://anuwknikgsijbameytzr.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

• df021288-bdef-4463-88db-98f22de89214 = User.ReadWrite.All (Application) — also covers license assignment per Microsoft Graph (assignLicense accepts User.ReadWrite.All as higher-privileged alternative)

Multi-tenant SaaS: Use AzureADMultipleOrgs for the shared Encore app. Grant admin consent per customer tenant via tenant=organizations (see Step 6). The full 18-scope catalog lives in src/platform/integrations/entra-permissions.ts and REQUIRED_GRAPH_SCOPES in supabase/functions/_shared/entra-client.ts.

​

Step 4: Create Client Secret

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

​

Step 5: Store Secrets in Supabase

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

# 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://anuwknikgsijbameytzr.supabase.co/functions/v1/entra-oauth/callback"

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

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

v2 admin consent (current): Encore now uses the Microsoft identity platform v2 endpoint with scope=https://graph.microsoft.com/.default:

https://login.microsoftonline.com/{tenant}/v2.0/adminconsent?client_id={app_id}&redirect_uri={encoded_uri}&scope=https://graph.microsoft.com/.default

For guided setup when the tenant ID is unknown, use tenant=organizations so a Microsoft administrator signs in and grants consent for their directory. The callback verifies consent by acquiring a Graph token (authoritative tid claim) and caches verified domains.

​

Tenant admin workflow (in Encore — no Supabase access)

1. Settings → Integrations → Microsoft Entra ID → Guided setup
2. Choose Encore shared app (recommended) or bring your own app registration
3. Enter primary email domain
4. Consent as Microsoft administrator (organization-wide admin consent)
5. Run connection test — verifies Graph token, caches verified domains, and pins the client secret to your organization vault (shared app)
6. Optionally enable Microsoft sign-in in the wizard or under Settings → Single Sign-On

​

Platform operator workflow (Encore / Supabase — not shown to tenants)

​

Supabase Azure Provider Checklist (PF-112 Login SSO — platform operators only)

​

1. Redirect URI on the Entra app registration

https://<project-ref>.supabase.co/auth/v1/callback

​

2. Optional claims in the app manifest

"optionalClaims": {
  "idToken": [
    { "name": "email", "essential": false },
    { "name": "xms_edov", "essential": false }
  ],
  "accessToken": [
    { "name": "email", "essential": false },
    { "name": "xms_edov", "essential": false }
  ]
}

​

3. Delegated sign-in scopes (admin-consented)

​

4. Supabase Auth Azure provider tenant (multi-tenant)

​

5. Encore-side prerequisites

​

6. Gate audit markers (server-side)

​

Current Configuration (NorthSight dev2 — 2026-06-18)

Retired: production project anuwknikgsijbameytzr redirect URIs remain on the Entra app for legacy reference but are superseded by dev2 URLs above.

​

Historical Configuration (retired dev project)

​

Verification Checklist

• Azure CLI installed and working
• Logged in to Azure CLI
• App registration created successfully
• API permissions added (User.ReadWrite.All — 18-scope catalog on shared app)
• 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 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