343 lines
10 KiB
Markdown
343 lines
10 KiB
Markdown
# 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.
|
|
|
|
## Prerequisites
|
|
|
|
- Access to Azure Portal (https://portal.azure.com)
|
|
- Admin permissions to register applications in Azure AD
|
|
- Access to your Supabase project dashboard
|
|
- 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
|
|
|
|
### 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).
|
|
|
|
## 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
|