MODEL/usda-vision
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
b77bca6f0a0293ace7d52406c0a9faa0bbc954c5
usda-vision/docs/MICROSOFT_ENTRA_SETUP.md

13 KiB
Raw Blame History

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 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
  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
  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:
[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
  1. Set enabled = true to activate Azure authentication

5.2 Set Environment Variables

Create or update your environment file (.env or set in your deployment):

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

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

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

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

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:

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

Supabase Documentation

Troubleshooting Resources

Last Updated: January 2026
Maintained By: USDA Vision System Team

Reference in New Issue View Git Blame Copy Permalink