Skip to main content

OAuth with Microsoft

Enable Microsoft Sign-In for InstaCRUD users using Azure Active Directory (Entra ID).

Overview​

Microsoft OAuth allows users to:

  • Sign in with Microsoft personal accounts (Outlook, Hotmail)
  • Sign in with Microsoft 365 work/school accounts
  • Use existing Microsoft identity

Step 1: Register Application in Azure​

  1. Go to Azure Portal
  2. Navigate to Microsoft Entra ID (formerly Azure AD)
  3. Select App registrations
  4. Click New registration

Registration Settings​

  • Name: InstaCRUD
  • Supported account types: Choose based on your needs:
    • Single tenant — Only your organization
    • Multitenant — Any organization
    • Multitenant + personal — Any org + personal Microsoft accounts (recommended for SaaS)
  • Redirect URI: Select Web and enter: 
    http://localhost:8000/oauth/microsoft/callback
  1. Click Register
  2. Copy the Application (client) ID

Step 2: Create Client Secret​

  1. In your app registration, go to Certificates & secrets
  2. Click New client secret
  3. Add a description (e.g., "InstaCRUD Production")
  4. Select expiration (24 months recommended)
  5. Click Add
  6. Copy the secret value immediately — it won't be shown again

Step 3: Configure API Permissions​

  1. Go to API permissions
  2. Click Add a permission
  3. Select Microsoft Graph
  4. Choose Delegated permissions
  5. Add these permissions:
    • email
    • openid
    • profile
    • User.Read
  6. Click Add permissions

For organization-wide access without user consent prompts:

  1. Click Grant admin consent for [Organization]
  2. Confirm the action

Step 4: Configure Redirect URIs​

  1. Go to Authentication
  2. Under Web > Redirect URIs, add all environments:
http://localhost:8000/oauth/microsoft/callback
https://your-domain.com/oauth/microsoft/callback
https://your-backend.ngrok-free.app/oauth/microsoft/callback

  1. Under Implicit grant and hybrid flows, enable:

    • Access tokens
    • ID tokens

  2. Click Save

Step 5: Configure InstaCRUD​

Add credentials to your backend .env file:

# Microsoft OAuth
MS_CLIENT_ID=your-application-client-id
MS_CLIENT_SECRET=your-client-secret-value
MS_TENANT_ID=common

Tenant ID Options​

ValueDescription
commonAny Microsoft account (personal + work/school)
organizationsOnly work/school accounts
consumersOnly personal Microsoft accounts
{tenant-id}Specific organization only

Step 6: Verify Configuration​

Restart the backend server. The OAuth endpoint should be available:

GET /oauth/microsoft/login

This redirects users to Microsoft's consent screen.

Environment-Specific Setup​

Local Development​

Redirect URI: http://localhost:8000/oauth/microsoft/callback

ngrok Development​

Redirect URI: https://your-backend.ngrok-free.app/oauth/microsoft/callback

Production​

Redirect URI: https://api.your-domain.com/oauth/microsoft/callback

Single-Tenant Configuration​

For internal applications restricted to one organization:

  1. Set Supported account types to Single tenant
  2. Use your organization's tenant ID:
MS_TENANT_ID=your-tenant-id-guid

Find your tenant ID in Azure Portal > Microsoft Entra ID > Overview.

Troubleshooting​

"AADSTS50011: Reply URL Mismatch"​

  • Redirect URI in Azure must match exactly
  • Check for trailing slashes
  • Verify protocol (http vs https)

"AADSTS7000215: Invalid Client Secret"​

  • Client secret may have expired
  • Create a new secret and update .env
  • Ensure no extra whitespace

"AADSTS700016: Application Not Found"​

  • Verify MS_CLIENT_ID is correct
  • Check the application exists in the correct tenant
  • Grant admin consent in Azure Portal
  • Or ensure required permissions are configured

Security Recommendations​

  1. Rotate secrets regularly — Set calendar reminders before expiration
  2. Use separate app registrations — One for development, one for production
  3. Limit permissions — Only request permissions you need
  4. Monitor sign-ins — Review Azure AD sign-in logs

Summary​

Microsoft OAuth configuration requires:

  1. Azure app registration with correct account type
  2. Client secret (keep secure, track expiration)
  3. API permissions for user profile access
  4. Redirect URIs for all environments
  5. Environment variables in InstaCRUD backend