@open-mercato/enterprise 0.4.6-develop-15c18897fc → 0.4.6-develop-34aa847ce6

package/src/modules/sso/data/entities.ts

@@ -0,0 +1,240 @@
+import { Entity, PrimaryKey, Property, Unique, Index } from '@mikro-orm/core'
+
+@Entity({ tableName: 'sso_configs' })
+// Unique index on organization_id (partial: WHERE deleted_at IS NULL) — managed by migration
+export class SsoConfig {
+  @PrimaryKey({ type: 'uuid', defaultRaw: 'gen_random_uuid()' })
+  id!: string
+
+  @Property({ name: 'tenant_id', type: 'uuid', nullable: true })
+  tenantId?: string | null
+
+  @Property({ name: 'organization_id', type: 'uuid' })
+  organizationId!: string
+
+  @Property({ type: 'text', nullable: true })
+  name?: string | null
+
+  @Property({ type: 'text' })
+  protocol!: string
+
+  @Property({ type: 'text', nullable: true })
+  issuer?: string | null
+
+  @Property({ name: 'client_id', type: 'text', nullable: true })
+  clientId?: string | null
+
+  @Property({ name: 'client_secret_enc', type: 'text', nullable: true })
+  clientSecretEnc?: string | null
+
+  @Property({ name: 'allowed_domains', type: 'jsonb', default: '[]' })
+  allowedDomains: string[] = []
+
+  @Property({ name: 'jit_enabled', type: 'boolean', default: true })
+  jitEnabled: boolean = true
+
+  @Property({ name: 'auto_link_by_email', type: 'boolean', default: true })
+  autoLinkByEmail: boolean = true
+
+  @Property({ name: 'is_active', type: 'boolean', default: false })
+  isActive: boolean = false
+
+  @Property({ name: 'sso_required', type: 'boolean', default: false })
+  ssoRequired: boolean = false
+
+  @Property({ name: 'app_role_mappings', type: 'jsonb', default: '{}' })
+  appRoleMappings: Record<string, string> = {}
+
+  @Property({ name: 'created_at', type: Date, onCreate: () => new Date() })
+  createdAt: Date = new Date()
+
+  @Property({ name: 'updated_at', type: Date, onCreate: () => new Date(), onUpdate: () => new Date() })
+  updatedAt: Date = new Date()
+
+  @Property({ name: 'deleted_at', type: Date, nullable: true })
+  deletedAt?: Date | null
+}
+
+@Entity({ tableName: 'sso_identities' })
+// Unique indexes (partial: WHERE deleted_at IS NULL) — managed by migration
+export class SsoIdentity {
+  @PrimaryKey({ type: 'uuid', defaultRaw: 'gen_random_uuid()' })
+  id!: string
+
+  @Property({ name: 'tenant_id', type: 'uuid', nullable: true })
+  tenantId?: string | null
+
+  @Property({ name: 'organization_id', type: 'uuid' })
+  organizationId!: string
+
+  @Property({ name: 'sso_config_id', type: 'uuid' })
+  @Index({ name: 'sso_identities_config_id_idx' })
+  ssoConfigId!: string
+
+  @Property({ name: 'user_id', type: 'uuid' })
+  @Index({ name: 'sso_identities_user_id_idx' })
+  userId!: string
+
+  @Property({ name: 'idp_subject', type: 'text' })
+  idpSubject!: string
+
+  @Property({ name: 'idp_email', type: 'text' })
+  idpEmail!: string
+
+  @Property({ name: 'idp_name', type: 'text', nullable: true })
+  idpName?: string | null
+
+  @Property({ name: 'idp_groups', type: 'jsonb', default: '[]' })
+  idpGroups: string[] = []
+
+  @Property({ name: 'external_id', type: 'text', nullable: true })
+  externalId?: string | null
+
+  @Property({ name: 'provisioning_method', type: 'text' })
+  provisioningMethod!: string
+
+  @Property({ name: 'first_login_at', type: Date, nullable: true })
+  firstLoginAt?: Date | null
+
+  @Property({ name: 'last_login_at', type: Date, nullable: true })
+  lastLoginAt?: Date | null
+
+  @Property({ name: 'created_at', type: Date, onCreate: () => new Date() })
+  createdAt: Date = new Date()
+
+  @Property({ name: 'updated_at', type: Date, onCreate: () => new Date(), onUpdate: () => new Date() })
+  updatedAt: Date = new Date()
+
+  @Property({ name: 'deleted_at', type: Date, nullable: true })
+  deletedAt?: Date | null
+}
+
+@Entity({ tableName: 'scim_tokens' })
+@Index({ name: 'scim_tokens_token_prefix_idx', properties: ['tokenPrefix'] })
+export class ScimToken {
+  @PrimaryKey({ type: 'uuid', defaultRaw: 'gen_random_uuid()' })
+  id!: string
+
+  @Property({ name: 'tenant_id', type: 'uuid', nullable: true })
+  tenantId?: string | null
+
+  @Property({ name: 'organization_id', type: 'uuid' })
+  organizationId!: string
+
+  @Property({ name: 'sso_config_id', type: 'uuid' })
+  @Index({ name: 'scim_tokens_sso_config_id_idx' })
+  ssoConfigId!: string
+
+  @Property({ type: 'text' })
+  name!: string
+
+  @Property({ name: 'token_hash', type: 'text' })
+  tokenHash!: string
+
+  @Property({ name: 'token_prefix', type: 'text' })
+  tokenPrefix!: string
+
+  @Property({ name: 'is_active', type: 'boolean', default: true })
+  isActive: boolean = true
+
+  @Property({ name: 'created_by', type: 'uuid', nullable: true })
+  createdBy?: string | null
+
+  @Property({ name: 'created_at', type: Date, onCreate: () => new Date() })
+  createdAt: Date = new Date()
+
+  @Property({ name: 'updated_at', type: Date, onCreate: () => new Date(), onUpdate: () => new Date() })
+  updatedAt: Date = new Date()
+}
+
+@Entity({ tableName: 'sso_user_deactivations' })
+@Unique({ properties: ['userId', 'ssoConfigId'], name: 'sso_user_deactivations_user_config_unique' })
+export class SsoUserDeactivation {
+  @PrimaryKey({ type: 'uuid', defaultRaw: 'gen_random_uuid()' })
+  id!: string
+
+  @Property({ name: 'tenant_id', type: 'uuid', nullable: true })
+  tenantId?: string | null
+
+  @Property({ name: 'organization_id', type: 'uuid' })
+  organizationId!: string
+
+  @Property({ name: 'user_id', type: 'uuid' })
+  @Index({ name: 'sso_user_deactivations_user_id_idx' })
+  userId!: string
+
+  @Property({ name: 'sso_config_id', type: 'uuid' })
+  ssoConfigId!: string
+
+  @Property({ name: 'deactivated_at', type: Date })
+  deactivatedAt: Date = new Date()
+
+  @Property({ name: 'reactivated_at', type: Date, nullable: true })
+  reactivatedAt?: Date | null
+
+  @Property({ name: 'created_at', type: Date, onCreate: () => new Date() })
+  createdAt: Date = new Date()
+}
+
+@Entity({ tableName: 'scim_provisioning_log' })
+@Index({ name: 'scim_provisioning_log_config_created_idx', properties: ['ssoConfigId', 'createdAt'] })
+export class ScimProvisioningLog {
+  @PrimaryKey({ type: 'uuid', defaultRaw: 'gen_random_uuid()' })
+  id!: string
+
+  @Property({ name: 'tenant_id', type: 'uuid', nullable: true })
+  tenantId?: string | null
+
+  @Property({ name: 'organization_id', type: 'uuid' })
+  organizationId!: string
+
+  @Property({ name: 'sso_config_id', type: 'uuid' })
+  ssoConfigId!: string
+
+  @Property({ type: 'text' })
+  operation!: string
+
+  @Property({ name: 'resource_type', type: 'text' })
+  resourceType!: string
+
+  @Property({ name: 'resource_id', type: 'uuid', nullable: true })
+  resourceId?: string | null
+
+  @Property({ name: 'scim_external_id', type: 'text', nullable: true })
+  scimExternalId?: string | null
+
+  @Property({ name: 'response_status', type: 'integer' })
+  responseStatus!: number
+
+  @Property({ name: 'error_message', type: 'text', nullable: true })
+  errorMessage?: string | null
+
+  @Property({ name: 'created_at', type: Date, onCreate: () => new Date() })
+  createdAt: Date = new Date()
+}
+
+@Entity({ tableName: 'sso_role_grants' })
+@Unique({ properties: ['userId', 'roleId', 'ssoConfigId'], name: 'sso_role_grants_user_role_config_unique' })
+export class SsoRoleGrant {
+  @PrimaryKey({ type: 'uuid', defaultRaw: 'gen_random_uuid()' })
+  id!: string
+
+  @Property({ name: 'tenant_id', type: 'uuid', nullable: true })
+  tenantId?: string | null
+
+  @Property({ name: 'organization_id', type: 'uuid' })
+  organizationId!: string
+
+  @Property({ name: 'user_id', type: 'uuid' })
+  @Index({ name: 'sso_role_grants_user_id_idx' })
+  userId!: string
+
+  @Property({ name: 'role_id', type: 'uuid' })
+  roleId!: string
+
+  @Property({ name: 'sso_config_id', type: 'uuid' })
+  ssoConfigId!: string
+
+  @Property({ name: 'created_at', type: Date, onCreate: () => new Date() })
+  createdAt: Date = new Date()
+}

package/src/modules/sso/data/validators.ts

@@ -0,0 +1,140 @@
+import { z } from 'zod'
+import { validateDomain } from '../lib/domains'
+
+const uuid = () => z.string().uuid()
+
+const domainString = () =>
+  z.string().trim().min(1).max(253).refine(
+    (val) => validateDomain(val).valid,
+    { message: 'Invalid domain format — only valid DNS hostnames with at least one dot are accepted' },
+  )
+
+// --- SSO Config schema (for internal use / seeding) ---
+
+export const ssoConfigCreateSchema = z.object({
+  organizationId: uuid(),
+  tenantId: uuid().optional(),
+  protocol: z.enum(['oidc', 'saml']),
+  issuer: z.string().url().optional(),
+  clientId: z.string().min(1).optional(),
+  clientSecret: z.string().min(1).optional(),
+  allowedDomains: z.array(domainString()).default([]),
+  jitEnabled: z.boolean().default(true),
+  autoLinkByEmail: z.boolean().default(true),
+  isActive: z.boolean().default(false),
+  ssoRequired: z.boolean().default(false),
+  appRoleMappings: z.record(z.string().min(1).max(255), z.string().min(1).max(255)).default({}),
+})
+
+export const ssoConfigUpdateSchema = z
+  .object({
+    id: uuid(),
+  })
+  .merge(ssoConfigCreateSchema.partial().omit({ organizationId: true, tenantId: true }))
+
+// --- API request schemas ---
+
+export const hrdRequestSchema = z.object({
+  email: z.string().email(),
+})
+
+export const ssoInitiateSchema = z.object({
+  configId: uuid(),
+  returnUrl: z.string().max(2048).refine(
+    (val) => val.startsWith('/') && !val.startsWith('//'),
+    { message: 'returnUrl must be a relative path starting with / and must not start with //' },
+  ).optional(),
+})
+
+export const oidcCallbackSchema = z.object({
+  code: z.string().min(1),
+  state: z.string().min(1),
+})
+
+// --- Admin API schemas ---
+
+export const ssoConfigAdminCreateSchema = z.object({
+  name: z.string().min(1).max(255),
+  organizationId: uuid().optional(),
+  tenantId: uuid().optional(),
+  protocol: z.enum(['oidc', 'saml']),
+  issuer: z.string().url(),
+  clientId: z.string().min(1),
+  clientSecret: z.string().min(1),
+  allowedDomains: z.array(domainString()).default([]),
+  jitEnabled: z.boolean().default(true),
+  autoLinkByEmail: z.boolean().default(true),
+  appRoleMappings: z.record(z.string().min(1).max(255), z.string().min(1).max(255)).default({}),
+})
+
+export const ssoConfigAdminUpdateSchema = z.object({
+  name: z.string().min(1).max(255).optional(),
+  protocol: z.enum(['oidc', 'saml']).optional(),
+  issuer: z.string().url().optional(),
+  clientId: z.string().min(1).optional(),
+  clientSecret: z.string().min(1).optional(),
+  jitEnabled: z.boolean().optional(),
+  autoLinkByEmail: z.boolean().optional(),
+  appRoleMappings: z.record(z.string().min(1).max(255), z.string().min(1).max(255)).optional(),
+})
+
+export const ssoConfigListQuerySchema = z.object({
+  page: z.coerce.number().min(1).default(1),
+  pageSize: z.coerce.number().min(1).max(100).default(50),
+  search: z.string().optional(),
+  organizationId: uuid().optional(),
+  tenantId: uuid().optional(),
+})
+
+export const ssoDomainAddSchema = z.object({
+  domain: domainString(),
+})
+
+export const ssoActivateSchema = z.object({
+  active: z.boolean(),
+})
+
+// --- SCIM User payload schema ---
+
+export const scimUserPayloadSchema = z.object({
+  schemas: z.array(z.string()).optional(),
+  userName: z.string().min(1).max(255),
+  externalId: z.string().max(255).optional(),
+  displayName: z.string().max(255).optional(),
+  active: z.union([z.boolean(), z.string()]).optional(),
+  name: z.object({
+    givenName: z.string().max(255).optional(),
+    familyName: z.string().max(255).optional(),
+    formatted: z.string().max(512).optional(),
+  }).optional(),
+  emails: z.array(z.object({
+    value: z.string().email(),
+    primary: z.boolean().optional(),
+    type: z.string().optional(),
+  })).optional(),
+}).passthrough()
+
+// --- SCIM Token schemas ---
+
+export const createScimTokenSchema = z.object({
+  ssoConfigId: uuid(),
+  name: z.string().min(1).max(100),
+})
+
+export const scimTokenListSchema = z.object({
+  ssoConfigId: uuid(),
+})
+
+// --- Type exports ---
+
+export type SsoConfigCreateInput = z.infer<typeof ssoConfigCreateSchema>
+export type SsoConfigUpdateInput = z.infer<typeof ssoConfigUpdateSchema>
+export type SsoConfigAdminCreateInput = z.infer<typeof ssoConfigAdminCreateSchema>
+export type SsoConfigAdminUpdateInput = z.infer<typeof ssoConfigAdminUpdateSchema>
+export type SsoConfigListQuery = z.infer<typeof ssoConfigListQuerySchema>
+export type HrdRequestInput = z.infer<typeof hrdRequestSchema>
+export type SsoInitiateInput = z.infer<typeof ssoInitiateSchema>
+export type OidcCallbackInput = z.infer<typeof oidcCallbackSchema>
+export type ScimUserPayloadInput = z.infer<typeof scimUserPayloadSchema>
+export type CreateScimTokenInput = z.infer<typeof createScimTokenSchema>
+export type ScimTokenListInput = z.infer<typeof scimTokenListSchema>

package/src/modules/sso/di.ts

@@ -0,0 +1,25 @@
+import { asClass, asValue } from 'awilix'
+import type { AppContainer } from '@open-mercato/shared/lib/di/container'
+import { SsoProviderRegistry } from './lib/registry'
+import { OidcProvider } from './lib/oidc-provider'
+import { SsoService } from './services/ssoService'
+import { AccountLinkingService } from './services/accountLinkingService'
+import { SsoConfigService } from './services/ssoConfigService'
+import { HrdService } from './services/hrdService'
+import { ScimTokenService } from './services/scimTokenService'
+import { ScimService } from './services/scimService'
+
+export function register(container: AppContainer) {
+  const registry = new SsoProviderRegistry()
+  registry.register(new OidcProvider())
+
+  container.register({
+    ssoProviderRegistry: asValue(registry),
+    ssoService: asClass(SsoService).scoped(),
+    accountLinkingService: asClass(AccountLinkingService).scoped(),
+    ssoConfigService: asClass(SsoConfigService).scoped(),
+    hrdService: asClass(HrdService).scoped(),
+    scimTokenService: asClass(ScimTokenService).scoped(),
+    scimService: asClass(ScimService).scoped(),
+  })
+}

package/src/modules/sso/docs/entra-id-setup.md

@@ -0,0 +1,281 @@
+# Microsoft Entra ID Setup Guide for Open Mercato SSO + SCIM
+
+This guide walks through setting up Microsoft Entra ID (formerly Azure AD) as the identity provider for both OIDC login and SCIM user provisioning in Open Mercato.
+
+**Free tier**: Entra ID Free is included with any Azure subscription — no paid license required for basic OIDC + SCIM.
+
+---
+
+## 1. Create an Azure Account + Entra ID Tenant
+
+1. Go to https://azure.microsoft.com/free and create a free account (or use an existing one)
+2. Navigate to https://entra.microsoft.com (the Entra admin center)
+3. You'll have a default tenant — note your **Tenant ID** from **Overview** → **Tenant ID**
+
+## 2. Create Test Users
+
+1. In the Entra admin center, go to **Identity** → **Users** → **All users**
+2. Click **+ New user** → **Create new user**
+3. Fill in:
+   - **User principal name**: e.g., `testuser@yourtenant.onmicrosoft.com`
+   - **Display name**: e.g., `Test User`
+   - **First name** / **Last name**
+   - **Password**: auto-generate or set manually
+4. Click **Create**
+5. Repeat for 2-3 test users
+
+## 3. Register the OIDC Application (SSO Login)
+
+1. In the Entra admin center, go to **Identity** → **Applications** → **App registrations**
+2. Click **+ New registration**
+3. Configure:
+
+| Field | Value |
+|-------|-------|
+| **Name** | `Open Mercato` |
+| **Supported account types** | `Accounts in this organizational directory only` (Single tenant) |
+| **Redirect URI** | Platform: `Web`, URI: `http://localhost:3000/api/sso/callback/oidc` |
+
+4. Click **Register**
+5. You'll land on the app's **Overview** page — note:
+   - **Application (client) ID** — this is your Client ID
+   - **Directory (tenant) ID** — used in the issuer URL
+
+### Create a Client Secret
+
+1. Go to **Certificates & secrets** → **Client secrets** tab
+2. Click **+ New client secret**
+3. Description: `Open Mercato Dev`, Expiry: `6 months` (or your preference)
+4. Click **Add**
+5. **Copy the secret Value immediately** — it's shown only once
+
+### OIDC Credentials Summary
+
+| Credential | Where to find it | Value |
+|------------|-----------------|-------|
+| **Issuer URL** | Computed from Tenant ID | `https://login.microsoftonline.com/{tenant-id}/v2.0` |
+| **Client ID** | App registration → Overview | Copy from portal |
+| **Client Secret** | App registration → Certificates & secrets | Copy the **Value** (not Secret ID) |
+| **Redirect URI** | You configured this | `http://localhost:3000/api/sso/callback/oidc` |
+
+### Configure Token Claims
+
+By default, Entra ID v2.0 tokens may not include `email` in the ID token. Fix this:
+
+1. Go to your App registration → **Token configuration**
+2. Click **+ Add optional claim**
+3. Token type: **ID**
+4. Check: `email`, `given_name`, `family_name`
+5. Click **Add**
+6. When prompted about Microsoft Graph permissions, check the box and click **Add**
+
+### API Permissions
+
+1. Go to **API permissions**
+2. Verify these are present (they should be by default):
+   - `Microsoft Graph` → `openid` (Delegated)
+   - `Microsoft Graph` → `profile` (Delegated)
+   - `Microsoft Graph` → `email` (Delegated)
+3. If any are missing, click **+ Add a permission** → **Microsoft Graph** → **Delegated permissions** → search and add them
+4. Click **Grant admin consent for [your tenant]** (green checkmark button)
+
+### Assign Users to the Application
+
+1. Go to **Identity** → **Applications** → **Enterprise applications**
+2. Find and click **Open Mercato**
+3. Go to **Users and groups** → **+ Add user/group**
+4. Select your test users (or a group containing them)
+5. Click **Assign**
+
+**Important**: If "Assignment required?" is set to **Yes** (under Properties), only assigned users can log in. Set to **No** for dev if you want all tenant users to access it.
+
+---
+
+## 4. Create the SSO Config in Open Mercato
+
+1. Log into Open Mercato as admin
+2. Go to **Settings** → **Single Sign-On** → **Create New**
+3. Select **OIDC** as the protocol
+4. Enter:
+   - **Name**: `Entra ID`
+   - **Issuer URL**: `https://login.microsoftonline.com/{your-tenant-id}/v2.0`
+   - **Client ID**: (paste from Entra)
+   - **Client Secret**: (paste the secret Value from Entra)
+5. Add allowed email domains (e.g., `yourtenant.onmicrosoft.com`)
+6. Test the connection (Verify Discovery)
+7. Activate the config
+
+### Verify OIDC Login
+
+1. Open a private/incognito browser window
+2. Go to the Open Mercato login page
+3. Enter an email address belonging to one of your test users (e.g., `testuser@yourtenant.onmicrosoft.com`)
+4. The HRD check should detect SSO and redirect to Microsoft login
+5. Authenticate at Microsoft
+6. You should be redirected back to Open Mercato and logged in
+
+---
+
+## 5. Configure SCIM Provisioning
+
+**Prerequisite**: You need a SCIM bearer token from Open Mercato. Generate one via:
+- The admin UI: SSO config → Provisioning tab → Generate Token
+- Or the API: `POST /api/sso/scim/tokens` with the SSO config ID
+
+### Set Up Provisioning in Entra ID
+
+1. Go to **Identity** → **Applications** → **Enterprise applications**
+2. Find and click **Open Mercato**
+3. Go to **Provisioning** → click **Get started**
+4. Set **Provisioning Mode** to **Automatic**
+5. In **Admin Credentials**:
+
+| Field | Value |
+|-------|-------|
+| **Tenant URL** | `http://localhost:3000/api/sso/scim/v2` (dev) or `https://<your-domain>/api/sso/scim/v2` (prod) |
+| **Secret Token** | Paste the SCIM bearer token from Open Mercato |
+
+6. Click **Test Connection** — should show "The supplied credentials are authorized to enable provisioning"
+7. Click **Save**
+
+### Configure Attribute Mappings
+
+1. Under **Mappings**, click **Provision Microsoft Entra ID Users**
+2. Verify these mappings exist:
+
+| Entra ID Attribute | SCIM Attribute | Notes |
+|--------------------|----------------|-------|
+| `userPrincipalName` | `userName` | Required |
+| `Switch([IsSoftDeleted]...)` | `active` | Required — Entra uses a Switch expression |
+| `givenName` | `name.givenName` | Required |
+| `surname` | `name.familyName` | Required |
+| `mail` | `emails[type eq "work"].value` | Required — user's email |
+| `displayName` | `displayName` | Optional |
+| `objectId` | `externalId` | Required — Entra's unique ID |
+
+3. Keep default mappings — they should work out of the box
+4. Click **Save**
+
+### Start Provisioning
+
+1. Back on the **Provisioning** page, set **Provisioning Status** to **On**
+2. Click **Save**
+3. Entra will run an initial provisioning cycle (may take up to 40 minutes for the first cycle)
+4. Check **Provisioning logs** for results
+
+### Provisioning Cycle Timing
+
+- **Initial cycle**: Processes all users in scope. Can take 20-40 minutes.
+- **Incremental cycles**: Every 40 minutes, processes changes since last cycle.
+- **On-demand provisioning**: Click **Provision on demand** to immediately provision a specific user (useful for testing).
+
+---
+
+## 6. Test the Full Flow
+
+### Test SCIM Provisioning
+
+1. In Entra, go to **Enterprise applications** → **Open Mercato** → **Provisioning**
+2. Click **Provision on demand**
+3. Search for a test user and click **Provision**
+4. **Expected**: Entra sends `POST /Users` to your SCIM endpoint → user appears in Open Mercato
+5. Check the provisioning log in Open Mercato admin UI
+
+### Test User Update
+
+1. In Entra, go to **Users** → edit a test user's display name
+2. Wait for the next provisioning cycle (or use Provision on demand)
+3. **Expected**: Entra sends `PATCH /Users/{id}` → user's name updated in Open Mercato
+
+### Test User Deactivation
+
+1. In Entra, either:
+   - **Delete** the user (soft-delete moves to Deleted users)
+   - **Block sign-in** for the user (Users → select user → Edit properties → Block sign in: Yes)
+   - **Remove** the user from the application assignment
+2. **Expected**: Entra sends `PATCH /Users/{id}` with `active: false` → user deactivated in Open Mercato, all sessions revoked
+
+### Test OIDC + SCIM Together
+
+1. **Create a new user in Entra** and assign them to the Open Mercato Enterprise app
+2. **Provision on demand** (or wait for cycle)
+3. **Verify** the user exists in Open Mercato (pre-provisioned, no login needed)
+4. **Log in as that user** via OIDC (Open Mercato login → redirect to Microsoft → authenticate → redirect back)
+5. **Expected**: The SCIM-provisioned account is used (no JIT provisioning, `provisioningMethod` stays `scim`)
+6. **Block sign-in for the user in Entra**
+7. **Expected**: SCIM deactivates the user → existing sessions revoked → OIDC login no longer works
+
+---
+
+## Entra ID SCIM Quirks
+
+When building the SCIM endpoint, account for these Entra-specific behaviors:
+
+| Quirk | Description | How to handle |
+|-------|-------------|---------------|
+| **PascalCase `op` in PATCH** | Entra sends `"op": "Replace"` instead of `"op": "replace"` | Case-insensitive comparison on PATCH operations |
+| **String booleans** | `active` may be sent as `"True"` / `"False"` strings | Parse with `parseBooleanToken` |
+| **Non-standard PATCH paths** | Sometimes sends `emails[type eq "work"].value` in PATCH path | Support bracket-notation in PATCH path parser |
+| **Mixed-case filter operators** | Sends `Eq` instead of `eq` in filters | Case-insensitive filter parsing |
+| **`externalId` mapping** | Maps `objectId` → `externalId` by default | Always store `externalId` from SCIM requests |
+| **Soft delete** | Uses `IsSoftDeleted` Switch expression → `active: false` | Handle as user deactivation |
+
+---
+
+## Troubleshooting
+
+### OIDC login redirects but fails
+
+- Verify the Redirect URI in App Registration matches exactly: `http://localhost:3000/api/sso/callback/oidc`
+- Check that the Issuer URL includes the tenant ID: `https://login.microsoftonline.com/{tenant-id}/v2.0`
+- Verify Client ID and Client Secret (the Value, not the Secret ID)
+- Ensure `email` optional claim is added to the ID token
+- Ensure API permissions have admin consent granted
+
+### "AADSTS50011: The redirect URI does not match"
+
+The redirect URI in the authorization request doesn't match what's registered. Check:
+- `APP_URL` in `.env` matches what you registered (e.g., `http://localhost:3000`)
+- No trailing slash differences
+- Protocol matches (http vs https)
+
+### Users not provisioning
+
+- Check that users are assigned to the Enterprise application
+- Check **Provisioning logs** in Entra for error details
+- Verify the SCIM token is valid and not revoked
+- For local dev, Entra needs to reach your server — use ngrok for SCIM (even though OIDC works with localhost)
+
+### SCIM "Test Connection" fails
+
+- For local dev, Entra's provisioning service needs to reach your endpoint over the internet
+- Use ngrok: `ngrok http 3000`
+- Set Tenant URL to: `https://<id>.ngrok-free.app/api/sso/scim/v2`
+- **Note**: OIDC redirect URIs can use `localhost`, but SCIM provisioning requires a publicly reachable URL
+
+### email claim missing from ID token
+
+1. Go to App registration → **Token configuration** → **+ Add optional claim** → ID token → check `email`
+2. Go to **API permissions** → verify `email` permission → click **Grant admin consent**
+
+---
+
+## Key Differences from JumpCloud
+
+| Aspect | Entra ID | JumpCloud |
+|--------|----------|-----------|
+| **Issuer URL** | `https://login.microsoftonline.com/{tenant-id}/v2.0` | `https://oauth.id.jumpcloud.com/` |
+| **Redirect URI** | Supports `http://localhost` for dev | Requires HTTPS |
+| **SCIM provisioning** | Enterprise App → Provisioning (automatic) | SSO App → Identity Management (SCIM API) |
+| **Provisioning cycles** | Every 40 minutes (or on-demand) | Near real-time |
+| **SCIM quirks** | PascalCase ops, string booleans, mixed-case filters | Mostly spec-compliant |
+| **Free tier** | Free with any Azure account | 10 users forever |
+
+---
+
+## Reference
+
+- [Entra ID App Registration - OIDC](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app)
+- [Entra ID SCIM Provisioning](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/use-scim-to-provision-users-and-groups)
+- [Entra ID Optional Claims](https://learn.microsoft.com/en-us/entra/identity-platform/optional-claims)
+- [Entra ID SCIM Known Issues](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/application-provisioning-config-problem-scim-compatibility)