Microsoft Provider

Add Microsoft OAuth to your Keyloom app using Azure Active Directory (Azure AD). This guide covers Azure app registration and configuration.

Prerequisites

• Microsoft account with Azure AD access
• Keyloom app with @keyloom/providers installed
• Public app URL for callback configuration

Azure AD app registration

1. Create App Registration

1. Go to Azure Portal
2. Navigate to Azure Active Directory → App registrations
3. Click "New registration"
4. Configure:
   • Name: Your application name
   • Supported account types: Choose based on your needs:
     • "Accounts in this organizational directory only" (single tenant)
     • "Accounts in any organizational directory" (multi-tenant)
     • "Accounts in any organizational directory and personal Microsoft accounts" (most common)
   • Redirect URI: Web → https://yourapp.com/api/auth/oauth/microsoft/callback

2. Configure Authentication

1. In your app registration, go to Authentication
2. Add additional redirect URIs if needed:
   • Development: http://localhost:3000/api/auth/oauth/microsoft/callback
   • Production: https://yourapp.com/api/auth/oauth/microsoft/callback
3. Under "Implicit grant and hybrid flows":
   • Enable "ID tokens" if using OpenID Connect
4. Set "Supported account types" as needed

3. Create Client Secret

1. Go to Certificates & secrets
2. Click "New client secret"
3. Configure:
   • Description: "Keyloom OAuth Secret"
   • Expires: Choose appropriate duration (24 months recommended)
4. Copy the Value (not the Secret ID)

4. Configure API Permissions

1. Go to API permissions
2. Default permissions include:
   • Microsoft Graph → User.Read (delegated)
3. Add additional permissions if needed:
   • profile - Basic profile information
   • email - Email address
   • openid - OpenID Connect sign-in

5. Get Application Details

From the Overview page, note:

• Application (client) ID
• Directory (tenant) ID (if single tenant)

Environment variables

MICROSOFT_CLIENT_ID=12345678-1234-1234-1234-123456789012
MICROSOFT_CLIENT_SECRET=abcdefghijklmnopqrstuvwxyz123456789012345
MICROSOFT_TENANT_ID=87654321-4321-4321-4321-210987654321
NEXT_PUBLIC_APP_URL=https://yourapp.com

Provider configuration

Multi-tenant (common)

import { defineKeyloom } from "@keyloom/core";
import { microsoft } from "@keyloom/providers";

export default defineKeyloom({
  baseUrl: process.env.NEXT_PUBLIC_APP_URL!,
  providers: [
    microsoft({
      clientId: process.env.MICROSOFT_CLIENT_ID!,
      clientSecret: process.env.MICROSOFT_CLIENT_SECRET!,
      // Multi-tenant: accepts any Azure AD tenant
      tenant: "common",
      scopes: ["openid", "profile", "email"],
    }),
  ],
  // ... rest of config
});

Single tenant

import { defineKeyloom } from "@keyloom/core";
import { microsoft } from "@keyloom/providers";

export default defineKeyloom({
  baseUrl: process.env.NEXT_PUBLIC_APP_URL!,
  providers: [
    microsoft({
      clientId: process.env.MICROSOFT_CLIENT_ID!,
      clientSecret: process.env.MICROSOFT_CLIENT_SECRET!,
      // Single tenant: specific tenant ID
      tenant: process.env.MICROSOFT_TENANT_ID!,
      scopes: ["openid", "profile", "email"],
    }),
  ],
  // ... rest of config
});

Recommended scopes

Minimal setup: Use openid, profile, and email for basic authentication.

Sign-in UI example

export function SignInWithMicrosoft() {
  return (
    <a
      href="/api/auth/oauth/microsoft/start?callbackUrl=/dashboard"
      className="flex items-center gap-2 px-4 py-2 bg-blue-600 text-white rounded"
    >
      <MicrosoftIcon />
      Continue with Microsoft
    </a>
  );
}

User profile mapping

Microsoft returns this profile data:

{
  "sub": "12345678-1234-1234-1234-123456789012",
  "name": "John Doe",
  "given_name": "John",
  "family_name": "Doe",
  "email": "john.doe@company.com",
  "picture": "https://graph.microsoft.com/v1.0/me/photo/$value"
}

Keyloom maps it to:

{
  id: profile.sub,
  email: profile.email,
  name: profile.name,
  image: profile.picture,
}

Tenant configuration

Common (multi-tenant)

• Accepts users from any Azure AD tenant
• Includes personal Microsoft accounts
• Most flexible option

Organizations (multi-tenant, work/school only)

• Accepts users from any Azure AD tenant
• Excludes personal Microsoft accounts
• Good for B2B applications

Specific tenant ID

• Only accepts users from specific tenant
• Most restrictive but most secure
• Good for internal applications

Error handling

Common Microsoft OAuth errors:

• invalid_client: Client ID/secret mismatch
• invalid_grant: Authorization code expired
• unauthorized_client: App not configured for tenant
• consent_required: User needs to consent to permissions

// In your error boundary or callback handler
if (error?.code === "oauth_error" && error?.provider === "microsoft") {
  switch (error?.details?.error) {
    case "invalid_client":
      return "Microsoft configuration error. Check client ID and secret.";
    case "unauthorized_client":
      return "App not authorized for this tenant. Contact administrator.";
    case "consent_required":
      return "Additional permissions required. Please try again.";
    default:
      return "Microsoft sign-in failed. Please try again.";
  }
}

Security considerations

• Client Secret: Store securely; rotate regularly
• Tenant Configuration: Choose appropriate tenant scope
• Permissions: Request minimal scopes needed
• Conditional Access: May require additional authentication factors

Performance tips

• Microsoft OAuth is generally fast and reliable
• Consider caching user profile data
• Use refresh tokens for long-lived sessions if needed

Troubleshooting

Unauthorized client error

• Verify app is registered in correct tenant
• Check supported account types configuration
• Ensure redirect URI matches exactly

Invalid client credentials

• Verify client ID and secret are correct
• Check if client secret has expired
• Ensure secret value (not ID) is used

Consent issues

• Check API permissions in Azure AD
• Verify scopes requested match configured permissions
• Consider admin consent for organizational apps

Redirect URI mismatch

• Must exactly match Azure AD app registration
• Check protocol, domain, and path
• Verify both development and production URLs are registered

See also

• Providers overview: /docs/providers/overview
• Security: /docs/security/overview
• Installation: /docs/getting-started/installation

Next steps

• Test the complete sign-in flow in development
• Configure appropriate tenant settings for your use case
• Set up conditional access policies if needed