Merge branch 'main' into db-fixes-and-patches

2026-03-09 12:50:57 -04:00
parent 0a2b24fdbf 1452a42ef4
commit 0882d8d484
30 changed files with 2277 additions and 33 deletions
--- a/docs/MICROSOFT_ENTRA_QUICKSTART.md
+++ b/docs/MICROSOFT_ENTRA_QUICKSTART.md
@@ -0,0 +1,138 @@
+# Microsoft Entra OpenID Connect - Quick Start
+
+## What Was Implemented
+
+The Login flow now supports Microsoft Entra ID (Azure AD) authentication via OpenID Connect using Supabase's Azure OAuth provider.
+
+## Files Modified
+
+1. **[Login.tsx](management-dashboard-web-app/src/components/Login.tsx)**: Added Microsoft login button and OAuth flow
+2. **[MicrosoftIcon.tsx](management-dashboard-web-app/src/components/MicrosoftIcon.tsx)**: Created Microsoft logo component
+3. **[vite-env.d.ts](management-dashboard-web-app/src/vite-env.d.ts)**: Added TypeScript type for new environment variable
+4. **[.env.example](management-dashboard-web-app/.env.example)**: Added Microsoft login configuration
+
+## How It Works
+
+### User Experience
+1. User visits login page and sees two options:
+   - Traditional email/password login (existing)
+   - "Sign in with Microsoft" button (new)
+2. Clicking Microsoft button redirects to Microsoft login
+3. User authenticates with Microsoft credentials
+4. Microsoft redirects back to app with authenticated session
+
+### Technical Flow
+```
+User clicks "Sign in with Microsoft"
+    ↓
+Supabase signInWithOAuth() with provider: 'azure'
+    ↓
+Redirect to Microsoft Entra login page
+    ↓
+User authenticates with Microsoft
+    ↓
+Microsoft redirects to Supabase callback URL
+    ↓
+Supabase validates and creates session
+    ↓
+User redirected back to application (authenticated)
+```
+
+## Configuration Required
+
+### 1. Azure Portal Setup
+- Register application in Microsoft Entra ID
+- Configure redirect URI: 
+  - **Supabase Cloud**: `https://<supabase-ref>.supabase.co/auth/v1/callback`
+  - **Self-hosted**: `http://<your-host>:<port>/auth/v1/callback`
+- Generate client ID and client secret
+- Set API permissions (openid, profile, email)
+
+### 2. Supabase Configuration
+
+#### For Supabase Cloud:
+Navigate to Authentication > Providers > Azure and configure:
+- **Azure Client ID**: From Azure app registration
+- **Azure Secret**: From Azure client secrets
+- **Azure Tenant**: Use `common` for multi-tenant or specific tenant ID
+
+#### For Self-Hosted Supabase:
+
+Edit `supabase/config.toml`:
+```toml
+[auth.external.azure]
+enabled = true
+client_id = "env(AZURE_CLIENT_ID)"
+secret = "env(AZURE_CLIENT_SECRET)"
+redirect_uri = ""
+url = "https://login.microsoftonline.com/env(AZURE_TENANT_ID)/v2.0"
+skip_nonce_check = false
+```
+
+Set environment variables:
+```bash
+AZURE_CLIENT_ID="your-application-client-id"
+AZURE_CLIENT_SECRET="your-client-secret"
+AZURE_TENANT_ID="common"  # or specific tenant ID
+```
+
+Restart Supabase:
+```bash
+docker-compose down && docker-compose up -d
+```
+
+### 3. Application Environment
+Set in `.env` file:
+```bash
+VITE_ENABLE_MICROSOFT_LOGIN=true
+```
+
+## Testing
+
+### Enable Microsoft Login
+```bash
+# In .env file
+VITE_ENABLE_MICROSOFT_LOGIN=true
+```
+
+### Disable Microsoft Login
+```bash
+# In .env file
+VITE_ENABLE_MICROSOFT_LOGIN=false
+# Or simply remove the variable
+```
+
+## Features
+
+✅ **Hybrid Authentication**: Supports both email/password and Microsoft login  
+✅ **Feature Flag**: Microsoft login can be enabled/disabled via environment variable  
+✅ **Dark Mode Support**: Microsoft button matches the existing theme  
+✅ **Error Handling**: Displays authentication errors to users  
+✅ **Loading States**: Shows loading indicator during authentication  
+✅ **Type Safety**: Full TypeScript support with proper types  
+
+## Next Steps
+
+1. **Complete Azure Setup**: Follow [MICROSOFT_ENTRA_SETUP.md](./MICROSOFT_ENTRA_SETUP.md) for detailed configuration
+2. **Configure Supabase**: Enable Azure provider in Supabase dashboard
+3. **Test Authentication**: Verify the complete login flow
+4. **Deploy**: Update production environment variables
+
+## Documentation
+
+- **Full Setup Guide**: [MICROSOFT_ENTRA_SETUP.md](./MICROSOFT_ENTRA_SETUP.md) - Complete Azure and Supabase configuration
+- **Supabase Docs**: https://supabase.com/docs/guides/auth/social-login/auth-azure
+- **Microsoft Identity Platform**: https://docs.microsoft.com/azure/active-directory/develop/
+
+## Support
+
+For issues or questions:
+- Check [MICROSOFT_ENTRA_SETUP.md](./MICROSOFT_ENTRA_SETUP.md) troubleshooting section
+- Review Supabase Auth logs
+- Check Azure sign-in logs in Azure Portal
+- Verify redirect URIs match exactly
+
+---
+
+**Implementation Date**: January 9, 2026  
+**Status**: Ready for configuration and testing
--- a/docs/MICROSOFT_ENTRA_SETUP.md
+++ b/docs/MICROSOFT_ENTRA_SETUP.md
@@ -0,0 +1,425 @@
+# Microsoft Entra (Azure AD) OpenID Connect Setup Guide
+
+## Overview
+
+This guide walks you through configuring Microsoft Entra ID (formerly Azure Active Directory) authentication for the USDA Vision Management Dashboard using Supabase's Azure OAuth provider.
+
+> **📌 Self-Hosted Supabase Users**: If you're using a self-hosted Supabase instance, see the simplified guide: [SELF_HOSTED_AZURE_SETUP.md](SELF_HOSTED_AZURE_SETUP.md). Self-hosted instances configure OAuth providers via `config.toml` and environment variables, not through the UI.
+
+## Prerequisites
+
+- Access to Azure Portal (https://portal.azure.com)
+- Admin permissions to register applications in Azure AD
+- Access to your Supabase project (Cloud dashboard or self-hosted instance)
+- The USDA Vision application deployed and accessible via URL
+
+## Step 1: Register Application in Microsoft Entra ID
+
+### 1.1 Navigate to Azure Portal
+
+1. Log in to [Azure Portal](https://portal.azure.com)
+2. Navigate to **Microsoft Entra ID** (or **Azure Active Directory**)
+3. Select **App registrations** from the left sidebar
+4. Click **+ New registration**
+
+### 1.2 Configure Application Registration
+
+Fill in the following details:
+
+- **Name**: `USDA Vision Management Dashboard` (or your preferred name)
+- **Supported account types**: Choose one of:
+  - **Single tenant**: Only users in your organization can sign in (most restrictive)
+  - **Multitenant**: Users in any Azure AD tenant can sign in
+  - **Multitenant + personal Microsoft accounts**: Broadest support
+- **Redirect URI**: 
+  - Platform: **Web**
+  - URI: `https://<your-supabase-project-ref>.supabase.co/auth/v1/callback`
+  - Example: `https://abcdefghij.supabase.co/auth/v1/callback`
+
+Click **Register** to create the application.
+
+### 1.3 Note Application (Client) ID
+
+After registration, you'll be taken to the app overview page. Copy and save:
+- **Application (client) ID**: This is your `AZURE_CLIENT_ID`
+- **Directory (tenant) ID**: This is your `AZURE_TENANT_ID`
+
+## Step 2: Configure Client Secret
+
+### 2.1 Create a Client Secret
+
+1. In your app registration, navigate to **Certificates & secrets**
+2. Click **+ New client secret**
+3. Add a description: `Supabase Auth`
+4. Choose an expiration period (recommendation: 12-24 months)
+5. Click **Add**
+
+### 2.2 Save the Secret Value
+
+**IMPORTANT**: Copy the **Value** immediately - it will only be shown once!
+- This is your `AZURE_CLIENT_SECRET`
+- Store it securely (password manager, secure vault, etc.)
+
+## Step 3: Configure API Permissions
+
+### 3.1 Add Required Permissions
+
+1. Navigate to **API permissions** in your app registration
+2. Click **+ Add a permission**
+3. Select **Microsoft Graph**
+4. Choose **Delegated permissions**
+5. Add the following permissions:
+   - `openid` (Sign users in)
+   - `profile` (View users' basic profile)
+   - `email` (View users' email address)
+   - `User.Read` (Sign in and read user profile)
+
+6. Click **Add permissions**
+
+### 3.2 Grant Admin Consent (Optional but Recommended)
+
+If you have admin privileges:
+1. Click **Grant admin consent for [Your Organization]**
+2. Confirm the action
+
+This prevents users from seeing a consent prompt on first login.
+
+## Step 4: Configure Authentication Settings
+
+### 4.1 Set Token Configuration
+
+1. Navigate to **Token configuration** in your app registration
+2. Click **+ Add optional claim**
+3. Choose **ID** token type
+4. Add the following claims:
+   - `email`
+   - `family_name`
+   - `given_name`
+   - `upn` (User Principal Name)
+
+5. Check **Turn on the Microsoft Graph email, profile permission** if prompted
+
+### 4.2 Configure Authentication Flow
+
+1. Navigate to **Authentication** in your app registration
+2. Under **Implicit grant and hybrid flows**, ensure:
+   - ✅ **ID tokens** (used for implicit and hybrid flows) is checked
+3. Under **Allow public client flows**:
+   - Select **No** (keep it secure)
+
+## Step 5: Configure Supabase
+
+### For Supabase Cloud (Hosted)
+
+#### 5.1 Navigate to Supabase Auth Settings
+
+1. Log in to your [Supabase Dashboard](https://app.supabase.com)
+2. Select your project
+3. Navigate to **Authentication** > **Providers**
+4. Find **Azure** in the provider list
+
+#### 5.2 Enable and Configure Azure Provider
+
+1. Toggle **Enable Sign in with Azure** to ON
+2. Fill in the configuration:
+
+   - **Azure Client ID**: Paste your Application (client) ID from Step 1.3
+   - **Azure Secret**: Paste your client secret value from Step 2.2
+   - **Azure Tenant**: You have two options:
+     - Use `common` for multi-tenant applications
+     - Use your specific **Directory (tenant) ID** for single-tenant
+     - Format: Just the GUID (e.g., `12345678-1234-1234-1234-123456789012`)
+
+3. Click **Save**
+
+#### 5.3 Note the Callback URL
+
+Supabase provides the callback URL in the format:
+```
+https://<your-project-ref>.supabase.co/auth/v1/callback
+```
+
+Verify this matches what you configured in Azure (Step 1.2).
+
+### For Self-Hosted Supabase
+
+If you're running a self-hosted Supabase instance, OAuth providers are configured via the `config.toml` file and environment variables rather than through the UI.
+
+#### 5.1 Edit config.toml
+
+1. Open your `supabase/config.toml` file
+2. Find or add the `[auth.external.azure]` section:
+
+```toml
+[auth.external.azure]
+enabled = true
+client_id = "env(AZURE_CLIENT_ID)"
+secret = "env(AZURE_CLIENT_SECRET)"
+redirect_uri = ""
+url = "https://login.microsoftonline.com/env(AZURE_TENANT_ID)/v2.0"
+skip_nonce_check = false
+```
+
+3. Set `enabled = true` to activate Azure authentication
+
+#### 5.2 Set Environment Variables
+
+Create or update your environment file (`.env` or set in your deployment):
+
+```bash
+# Azure AD OAuth Configuration
+AZURE_CLIENT_ID="your-application-client-id-from-azure"
+AZURE_CLIENT_SECRET="your-client-secret-from-azure"
+AZURE_TENANT_ID="common"  # or your specific tenant ID
+```
+
+**Important**: 
+- Use `common` for multi-tenant (any Azure AD organization)
+- Use `organizations` for any Azure AD organization (excludes personal Microsoft accounts)
+- Use `consumers` for personal Microsoft accounts only
+- Use your specific tenant ID (GUID) for single-tenant applications
+
+#### 5.3 Update Azure Redirect URI
+
+For self-hosted Supabase, your callback URL will be:
+```
+http://<your-host>:<supabase-port>/auth/v1/callback
+```
+
+For example, if your Supabase API is at `http://192.168.1.100:54321`:
+```
+http://192.168.1.100:54321/auth/v1/callback
+```
+
+**Go back to Azure Portal** (Step 1.2) and add this redirect URI to your app registration.
+
+#### 5.4 Restart Supabase Services
+
+After making these changes, restart your Supabase services:
+
+```bash
+# If using docker-compose
+docker-compose down
+docker-compose up -d
+
+# Or if using the provided script
+./docker-compose.sh restart
+```
+
+#### 5.5 Verify Configuration
+
+Check that the auth service picked up your configuration:
+
+```bash
+# View auth service logs
+docker-compose logs auth
+
+# Or for specific service name
+docker-compose logs supabase-auth
+```
+
+Look for log entries indicating Azure provider is enabled.
+
+## Step 6: Configure Application Environment
+
+### 6.1 Update Environment Variables
+
+In your application's `.env` file, add or update:
+
+```bash
+# Supabase Configuration (if not already present)
+VITE_SUPABASE_URL=https://<your-project-ref>.supabase.co
+VITE_SUPABASE_ANON_KEY=<your-anon-key>
+
+# Enable Microsoft Login
+VITE_ENABLE_MICROSOFT_LOGIN=true
+```
+
+### 6.2 Restart Development Server
+
+If running locally:
+```bash
+npm run dev
+```
+
+## Step 7: Test the Integration
+
+### 7.1 Test Login Flow
+
+1. Navigate to your application's login page
+2. You should see a "Sign in with Microsoft" button
+3. Click the button
+4. You should be redirected to Microsoft's login page
+5. Sign in with your Microsoft account
+6. Grant consent if prompted
+7. You should be redirected back to your application, logged in
+
+### 7.2 Verify User Data
+
+After successful login, check that:
+- User profile information is available
+- Email address is correctly populated
+- User roles/permissions are properly assigned (if using RBAC)
+
+### 7.3 Common Issues and Troubleshooting
+
+#### Redirect URI Mismatch
+**Error**: `AADSTS50011: The redirect URI ... does not match the redirect URIs configured`
+
+**Solution**: Ensure the redirect URI in Azure matches exactly:
+```
+https://<your-project-ref>.supabase.co/auth/v1/callback
+```
+
+#### Invalid Client Secret
+**Error**: `Invalid client secret provided`
+
+**Solution**: 
+- Verify you copied the secret **Value**, not the Secret ID
+- Generate a new client secret if the old one expired
+
+#### Missing Permissions
+**Error**: User consent required or permission denied
+
+**Solution**:
+- Add the required API permissions in Azure (Step 3)
+- Grant admin consent if available
+
+#### CORS Errors
+**Error**: CORS policy blocking requests
+
+**Solution**:
+- Ensure your application URL is properly configured in Supabase
+- Check that you're using the correct Supabase URL
+
+## Step 8: Production Deployment
+
+### 8.1 Update Redirect URI for Production
+
+1. Go back to Azure Portal > App registrations
+2. Navigate to **Authentication**
+3. Add production redirect URI:
+   ```
+   https://your-production-domain.com/
+   ```
+4. Ensure Supabase callback URI is still present
+
+### 8.2 Set Production Environment Variables
+
+Update your production environment with:
+```bash
+VITE_SUPABASE_URL=https://<your-project-ref>.supabase.co
+VITE_SUPABASE_ANON_KEY=<your-production-anon-key>
+VITE_ENABLE_MICROSOFT_LOGIN=true
+```
+
+### 8.3 Security Best Practices
+
+1. **Rotate Secrets Regularly**: Set calendar reminders before client secret expiration
+2. **Use Azure Key Vault**: Store secrets in Azure Key Vault for enhanced security
+3. **Monitor Sign-ins**: Use Azure AD sign-in logs to monitor authentication activity
+4. **Implement MFA**: Require multi-factor authentication for sensitive accounts
+5. **Review Permissions**: Regularly audit API permissions and remove unnecessary ones
+
+## Advanced Configuration
+
+### Multi-Tenant Support
+
+If you want to support users from multiple Azure AD tenants:
+
+1. In Azure App Registration > **Authentication**:
+   - Set **Supported account types** to **Multitenant**
+
+2. In Supabase Azure provider configuration:
+   - Set **Azure Tenant** to `common`
+
+### Custom Domain Configuration
+
+If using a custom domain with Supabase:
+
+1. Configure custom domain in Supabase dashboard
+2. Update redirect URI in Azure to use custom domain
+3. Update application environment variables
+
+### User Attribute Mapping
+
+To map Azure AD attributes to Supabase user metadata:
+
+1. Use Supabase database triggers or functions
+2. Extract attributes from JWT token
+3. Update user metadata in `auth.users` table
+
+Example attributes available:
+- `sub`: User's unique ID
+- `email`: Email address
+- `name`: Full name
+- `given_name`: First name
+- `family_name`: Last name
+- `preferred_username`: Username
+
+## Integration with RBAC System
+
+To integrate Microsoft Entra authentication with your existing RBAC system:
+
+### Option 1: Manual Role Assignment
+
+After user signs in via Microsoft:
+1. Admin assigns roles in the management dashboard
+2. Roles stored in your `user_roles` table
+3. User gets appropriate permissions on next login
+
+### Option 2: Azure AD Group Mapping
+
+Map Azure AD groups to application roles:
+1. Configure group claims in Azure token configuration
+2. Read groups from JWT token in Supabase
+3. Automatically assign roles based on group membership
+
+### Option 3: Hybrid Approach
+
+Support both Microsoft and email/password login:
+- Keep existing email/password authentication
+- Add Microsoft as an additional option
+- Users can link accounts or use either method
+
+## Monitoring and Maintenance
+
+### Azure AD Monitoring
+
+- **Sign-in logs**: Monitor authentication attempts
+- **Audit logs**: Track configuration changes
+- **Usage analytics**: Understand authentication patterns
+
+### Supabase Monitoring
+
+- **Auth logs**: View authentication events
+- **User activity**: Track active users
+- **Error logs**: Identify authentication issues
+
+### Regular Maintenance Tasks
+
+- [ ] Rotate client secrets before expiration (set reminders)
+- [ ] Review and update API permissions quarterly
+- [ ] Audit user access and remove inactive users
+- [ ] Update token configuration as needed
+- [ ] Test authentication flow after any infrastructure changes
+
+## Support and Resources
+
+### Microsoft Documentation
+- [Microsoft identity platform documentation](https://docs.microsoft.com/azure/active-directory/develop/)
+- [Azure AD app registration](https://docs.microsoft.com/azure/active-directory/develop/quickstart-register-app)
+- [OpenID Connect on Microsoft identity platform](https://docs.microsoft.com/azure/active-directory/develop/v2-protocols-oidc)
+
+### Supabase Documentation
+- [Supabase Auth with Azure](https://supabase.com/docs/guides/auth/social-login/auth-azure)
+- [Supabase Auth API reference](https://supabase.com/docs/reference/javascript/auth-signinwithoauth)
+
+### Troubleshooting Resources
+- Azure AD Error Codes: https://docs.microsoft.com/azure/active-directory/develop/reference-aadsts-error-codes
+- Supabase Discord Community: https://discord.supabase.com
+
+---
+
+**Last Updated**: January 2026  
+**Maintained By**: USDA Vision System Team
--- a/docs/OAUTH_USER_SYNC_FIX.md
+++ b/docs/OAUTH_USER_SYNC_FIX.md
@@ -0,0 +1,139 @@
+# OAuth User Synchronization Fix
+
+## Problem
+When a user signs on with an OAuth provider (Microsoft Entra/Azure AD) for the first time, the user is added to `auth.users` in Supabase but NOT to the application's `user_profiles` table. This causes the application to fail when trying to load user data, as there's no user profile available.
+
+## Solution
+Implemented automatic user profile creation for OAuth users through a multi-layered approach:
+
+### 1. Database Trigger (00003_oauth_user_sync.sql)
+- **Location**: `supabase/migrations/00003_oauth_user_sync.sql` and `management-dashboard-web-app/supabase/migrations/00003_oauth_user_sync.sql`
+- **Function**: `handle_new_oauth_user()` 
+  - Automatically creates a user profile in `public.user_profiles` when a new user is created in `auth.users`
+  - Handles the synchronization at the database level, ensuring it works regardless of where users are created
+  - Includes race condition handling with `ON CONFLICT DO NOTHING`
+  
+- **Trigger**: `on_auth_user_created`
+  - Fires after INSERT on `auth.users`
+  - Ensures every new OAuth user gets a profile entry
+
+### 2. Client-Side Utility Function (src/lib/supabase.ts)
+- **Function**: `userManagement.syncOAuthUser()`
+  - Provides a fallback synchronization mechanism for any OAuth users that slip through
+  - Checks if user profile exists before creating
+  - Handles race conditions gracefully (duplicate key errors)
+  - Includes comprehensive error logging for debugging
+
+**Logic**:
+```typescript
+1. Get current authenticated user from Supabase Auth
+2. Check if user profile already exists in user_profiles table
+3. If exists: return (no action needed)
+4. If not exists: create user profile with:
+   - id: user's UUID from auth.users
+   - email: user's email from auth.users
+   - status: 'active' (default status)
+5. Handle errors gracefully:
+   - "No rows returned" (PGRST116): Expected, user doesn't exist yet
+   - "Duplicate key" (23505): Race condition, another process created it first
+   - Other errors: Log and continue
+```
+
+### 3. App Integration (src/App.tsx)
+- **Updated**: Auth state change listener
+- **Triggers**: When `SIGNED_IN` or `INITIAL_SESSION` event occurs
+- **Action**: Calls `userManagement.syncOAuthUser()` asynchronously
+- **Benefit**: Ensures user profile exists before the rest of the app tries to access it
+
+## How It Works
+
+### OAuth Sign-In Flow (New)
+```
+1. User clicks "Sign in with Microsoft"
+   ↓
+2. Redirected to Microsoft login
+   ↓
+3. Microsoft authenticates and redirects back
+   ↓
+4. Supabase creates entry in auth.users
+   ↓
+5. Database trigger fires → user_profiles entry created
+   ↓
+6. App receives SIGNED_IN event
+   ↓
+7. App calls syncOAuthUser() as extra safety measure
+   ↓
+8. User profile is guaranteed to exist
+   ↓
+9. getUserProfile() and loadData() succeed
+```
+
+## Backward Compatibility
+- **Non-invasive**: The solution uses triggers and utility functions, doesn't modify existing tables
+- **Graceful degradation**: If either layer fails, the other provides a fallback
+- **No breaking changes**: Existing APIs and components remain unchanged
+
+## Testing Recommendations
+
+### Test 1: First-Time OAuth Sign-In
+1. Clear browser cookies/session
+2. Click "Sign in with Microsoft"
+3. Complete OAuth flow
+4. Verify:
+   - User is in Supabase auth
+   - User is in `user_profiles` table
+   - App loads user data without errors
+   - Dashboard displays correctly
+
+### Test 2: Verify Database Trigger
+1. Directly create a user in `auth.users` via SQL
+2. Verify that `user_profiles` entry is automatically created
+3. Check timestamp to confirm trigger fired
+
+### Test 3: Verify Client-Side Fallback
+1. Manually delete a user's `user_profiles` entry
+2. Reload the app
+3. Verify that `syncOAuthUser()` recreates the profile
+4. Check browser console for success logs
+
+## Files Modified
+1. **Database Migrations**:
+   - `/usda-vision/supabase/migrations/00003_oauth_user_sync.sql` (NEW)
+   - `/usda-vision/management-dashboard-web-app/supabase/migrations/00003_oauth_user_sync.sql` (NEW)
+
+2. **TypeScript/React**:
+   - `/usda-vision/management-dashboard-web-app/src/lib/supabase.ts` (MODIFIED)
+     - Added `syncOAuthUser()` method to `userManagement` object
+   
+   - `/usda-vision/management-dashboard-web-app/src/App.tsx` (MODIFIED)
+     - Import `userManagement` 
+     - Call `syncOAuthUser()` on auth state change
+
+## Deployment Steps
+
+1. **Apply Database Migrations**:
+   ```bash
+   # Run the new migration
+   supabase migration up
+   ```
+
+2. **Deploy Application Code**:
+   - Push the changes to `src/lib/supabase.ts` and `src/App.tsx`
+   - No environment variable changes needed
+   - No configuration changes needed
+
+3. **Test in Staging**:
+   - Test OAuth sign-in with a fresh account
+   - Verify user profile is created
+   - Check app functionality
+
+4. **Monitor in Production**:
+   - Watch browser console for any errors from `syncOAuthUser()`
+   - Check database logs to confirm trigger is firing
+   - Monitor user creation metrics
+
+## Future Enhancements
+- Assign default roles to new OAuth users (currently requires manual assignment)
+- Pre-populate `first_name` and `last_name` from OAuth provider data
+- Add user profile completion workflow for new OAuth users
+- Auto-disable account creation for users outside organization
--- a/docs/SELF_HOSTED_AZURE_SETUP.md
+++ b/docs/SELF_HOSTED_AZURE_SETUP.md
@@ -0,0 +1,158 @@
+# Self-Hosted Supabase - Microsoft Entra Setup
+
+## Quick Setup Guide
+
+For self-hosted Supabase instances, OAuth providers like Microsoft Entra (Azure AD) are configured through config files and environment variables, not through the UI.
+
+### Step 1: Configure Azure Application
+
+Follow steps 1-4 in [MICROSOFT_ENTRA_SETUP.md](MICROSOFT_ENTRA_SETUP.md) to:
+1. Register your app in Azure Portal
+2. Get your Client ID and Secret
+3. Set up API permissions
+4. Configure token claims
+
+**Important**: Your redirect URI should be:
+```
+http://<your-host-ip>:<supabase-port>/auth/v1/callback
+```
+
+Example: `http://192.168.1.100:54321/auth/v1/callback`
+
+### Step 2: Configure Supabase
+
+The Azure provider configuration is already added to `supabase/config.toml`:
+
+```toml
+[auth.external.azure]
+enabled = false  # Change this to true
+client_id = "env(AZURE_CLIENT_ID)"
+secret = "env(AZURE_CLIENT_SECRET)"
+redirect_uri = ""
+url = "https://login.microsoftonline.com/env(AZURE_TENANT_ID)/v2.0"
+skip_nonce_check = false
+```
+
+### Step 3: Set Environment Variables
+
+1. Copy the example file:
+   ```bash
+   cp .env.azure.example .env.azure
+   ```
+
+2. Edit `.env.azure` with your actual values:
+   ```bash
+   AZURE_CLIENT_ID=your-application-client-id
+   AZURE_CLIENT_SECRET=your-client-secret
+   AZURE_TENANT_ID=common  # or your specific tenant ID
+   ```
+
+3. Source the environment file before starting Supabase:
+   ```bash
+   source .env.azure
+   ```
+
+   Or add it to your docker-compose environment.
+
+### Step 4: Enable Azure Provider
+
+Edit `supabase/config.toml` and change:
+```toml
+[auth.external.azure]
+enabled = true  # Change from false to true
+```
+
+### Step 5: Restart Supabase
+
+```bash
+docker-compose down
+docker-compose up -d
+```
+
+Or if using the project script:
+```bash
+./docker-compose.sh restart
+```
+
+### Step 6: Enable in Application
+
+In `management-dashboard-web-app/.env`:
+```bash
+VITE_ENABLE_MICROSOFT_LOGIN=true
+```
+
+### Verification
+
+1. Check auth service logs:
+   ```bash
+   docker-compose logs auth | grep -i azure
+   ```
+
+2. You should see the Microsoft login button on your application's login page
+
+3. Click it and verify you're redirected to Microsoft login
+
+### Troubleshooting
+
+#### Azure Provider Not Working
+
+**Check logs**:
+```bash
+docker-compose logs auth
+```
+
+**Verify environment variables are loaded**:
+```bash
+docker-compose exec auth env | grep AZURE
+```
+
+#### Redirect URI Mismatch
+
+Ensure the redirect URI in Azure exactly matches:
+```
+http://<your-host-ip>:<supabase-port>/auth/v1/callback
+```
+
+Common mistake: Using `localhost` instead of the actual IP address.
+
+#### Environment Variables Not Set
+
+If you see errors about missing AZURE variables, make sure to:
+1. Export them in your shell before running docker-compose
+2. Or add them to your docker-compose.yml environment section
+3. Or use a .env file that docker-compose automatically loads
+
+### Docker Compose Environment Variables
+
+You can also add the variables directly to your `docker-compose.yml`:
+
+```yaml
+services:
+  auth:
+    environment:
+      AZURE_CLIENT_ID: ${AZURE_CLIENT_ID}
+      AZURE_CLIENT_SECRET: ${AZURE_CLIENT_SECRET}
+      AZURE_TENANT_ID: ${AZURE_TENANT_ID:-common}
+```
+
+Then create a `.env` file in the same directory:
+```bash
+AZURE_CLIENT_ID=your-client-id
+AZURE_CLIENT_SECRET=your-secret
+AZURE_TENANT_ID=common
+```
+
+### Security Notes
+
+- Never commit `.env.azure` or `.env` files with real secrets to git
+- Add them to `.gitignore`
+- Use environment variable substitution in config.toml
+- Rotate client secrets regularly (before expiration)
+- Monitor sign-in logs in Azure Portal
+
+### Additional Resources
+
+- Full setup guide: [MICROSOFT_ENTRA_SETUP.md](MICROSOFT_ENTRA_SETUP.md)
+- Quick reference: [MICROSOFT_ENTRA_QUICKSTART.md](MICROSOFT_ENTRA_QUICKSTART.md)
+- Supabase self-hosting docs: https://supabase.com/docs/guides/self-hosting
+- Azure OAuth docs: https://docs.microsoft.com/azure/active-directory/develop/v2-oauth2-auth-code-flow