Logo

Microsoft OAuth Setup

⚠️ Important: The screenshots and step-by-step instructions on this page reflect the interface as of December 2025. Third-party services like Google, Facebook, and Microsoft frequently update their user interfaces. While the general process remains similar, the exact screens, button labels, and menu locations may differ from what you see. If you encounter significant differences, consult the provider's official documentation.

This guide walks you through setting up Microsoft OAuth authentication for your site using Azure Active Directory.

Quick Setup (Already Have Credentials?)

If you already have a Microsoft/Azure App Registration with Client ID and Secret, just add them to appsettings.json:

{
  "Authentication": {
    "EnableMicrosoftAuth": true,
    "Microsoft": {
      "ClientId": "your-application-client-id",
      "ClientSecret": "your-client-secret-value"
    }
  }
}

Ensure your redirect URI is configured: https://yourdomain.com/signin-microsoft

Prerequisites

Step 1: Register an Application

  1. Go to the Azure Portal
  2. Search for and select Azure Active Directory
  3. In the left menu, select App registrations
  4. Click + New registration
  5. Enter an application name (e.g., "My Web App")
  6. Under Supported account types, choose one:
    • Single tenant - Only users in your organization
    • Multitenant - Users in any organization
    • Personal Microsoft accounts - Consumer accounts (outlook.com, etc.)
    • Multitenant + personal - All of the above (most flexible)
  7. Click Register

Step 2: Configure Redirect URIs

  1. In your app registration, go to Authentication
  2. Click + Add a platform
  3. Select Web
  4. Enter your redirect URI:
    • For development: https://localhost:{port}/signin-microsoft
    • For production: https://yourdomain.com/signin-microsoft
  5. Click Configure

Step 3: Create a Client Secret

  1. In your app registration, go to Certificates & secrets
  2. Click + New client secret
  3. Enter a description (e.g., "Web App Secret")
  4. Select an expiration period
  5. Click Add
  6. Copy the secret Value immediately (it won't be shown again)
Critical: Copy the secret value immediately! Once you leave this page, you cannot retrieve it again. You would need to create a new secret.

Step 4: Get Application (Client) ID

  1. Go to your app registration's Overview page
  2. Copy the Application (client) ID

Step 5: Configure Your Application

Add the credentials to your appsettings.json:

{
  "Authentication": {
    "EnableMicrosoftAuth": true,
    "Microsoft": {
      "ClientId": "your-application-client-id",
      "ClientSecret": "your-client-secret-value"
    }
  }
}
For Development: Use User Secrets instead of appsettings.json: 
dotnet user-secrets set "Authentication:Microsoft:ClientId" "your-client-id"
dotnet user-secrets set "Authentication:Microsoft:ClientSecret" "your-client-secret"

Account Type Considerations

Account Type Use Case
Single tenant Internal apps for your organization only
Multitenant Apps for any Azure AD organization
Personal accounts Consumer-facing apps (outlook.com, hotmail.com users)
Multitenant + personal Maximum flexibility - supports all account types

Troubleshooting

Error: AADSTS50011 - Reply URL does not match
The redirect URI in your request doesn't match any configured URIs. Verify the URI is exactly correct in Azure, including protocol and trailing slashes.
Error: AADSTS7000218 - Invalid client secret
The client secret may have expired or been entered incorrectly. Create a new secret in Azure and update your configuration.
Error: AADSTS65001 - User or admin hasn't consented
The user needs to grant consent. For admin consent, an administrator must approve the app in Azure AD.
Error: AADSTS700016 - Application not found
The Client ID is incorrect or the app was deleted. Verify the Application (client) ID in Azure.

Related Topics