usda-vision/docs/MICROSOFT_ENTRA_QUICKSTART.md

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: Added Microsoft login button and OAuth flow
2. MicrosoftIcon.tsx: Created Microsoft logo component
3. vite-env.d.ts: Added TypeScript type for new environment variable
4. .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:

[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:

AZURE_CLIENT_ID="your-application-client-id"
AZURE_CLIENT_SECRET="your-client-secret"
AZURE_TENANT_ID="common"  # or specific tenant ID

Restart Supabase:

docker-compose down && docker-compose up -d

3. Application Environment

Set in .env file:

VITE_ENABLE_MICROSOFT_LOGIN=true

Testing

Enable Microsoft Login

# In .env file
VITE_ENABLE_MICROSOFT_LOGIN=true

Disable Microsoft Login

# 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 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 - 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 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