# 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