Remix Auth Microsoft Strategy

Common errors

• AADSTS65001: The user or administrator has not consented to use the application

  cause The application lacks the necessary permissions, or an administrator has not granted consent for the requested scopes, especially common for delegated permissions.
  fix Ensure all required API permissions are configured in your Azure App Registration (API permissions blade). For organizational accounts, an administrator might need to grant tenant-wide consent. For personal accounts, the user needs to consent during the login flow.

• AADSTS50011: The reply URL specified in the request does not match the reply URLs configured for the application.

  cause The `redirectURI` configured in your `MicrosoftStrategy` instance does not exactly match one of the 'Redirect URIs' specified in your Azure App Registration.
  fix Verify that the `redirectURI` in your `MicrosoftStrategy` options (e.g., `http://localhost:3000/auth/microsoft/callback`) is identical to an entry in the 'Authentication' blade -> 'Redirect URIs' section of your Azure App Registration. Include scheme (http/https) and path.

• AADSTS7000215: Invalid client secret provided.

  cause The `clientSecret` configured in your `MicrosoftStrategy` is incorrect, expired, or doesn't match the secret generated in your Azure App Registration.
  fix Go to your Azure App Registration -> 'Certificates & secrets' blade. Ensure you have an active client secret, copy its 'Value' (not 'Secret ID'), and update the `clientSecret` in your `MicrosoftStrategy` configuration.

• Error: Authenticator already has a strategy with the name 'microsoft'

  cause You are attempting to register the MicrosoftStrategy with the same name ('microsoft' by default) more than once with the same Authenticator instance, or another strategy is using the 'microsoft' name.
  fix Ensure `authenticator.use()` for `MicrosoftStrategy` is called only once. If you need multiple Microsoft strategies, provide a unique second argument to `authenticator.use(strategy, 'unique-name')` for each instance.

Warnings

• breaking Version 3.0.0 upgraded remix-auth to v4 and remix-auth-oauth2 to v3. This also removed the default value for the `prompt` parameter in the strategy configuration, requiring explicit definition if desired.
  Fix: Update `remix-auth` and `remix-auth-oauth2` to their latest major versions. If your MicrosoftStrategy configuration previously relied on a default `prompt` behavior, you must now explicitly set `prompt: 'select_account'` (or 'login', 'consent', etc.) in the strategy options.
• breaking Version 2.0.0 introduced variable renames to better align with Microsoft documentation, which may require updates to existing strategy configuration objects.
  Fix: Review your strategy configuration against the v2.0.0 documentation or examples to ensure all variable names are updated, e.g., to align with 'clientId', 'clientSecret', 'redirectURI', 'tenantId'.
• gotcha Do not use the email address provided by Microsoft Entra ID (Azure AD) as the sole identifier for users, especially in multi-tenant applications. The email address is not validated and can be changed by users in the Azure Portal, creating a spoofing risk.
  Fix: Always use a robust, immutable identifier like the 'id' from the user profile (which maps to the 'sub' claim in the ID token) or the 'oid' claim for organizational IDs, to identify and retrieve users from your database.
• gotcha When using cookie-based session storage with Remix Auth, be aware of the 4KB size limit for cookies. Storing large user objects or extensive token data directly in the session can exceed this limit.
  Fix: Minimize the data stored directly in the session. Consider storing only a user ID in the session and fetching full user details from a database on each request. If storing tokens, only store what's absolutely necessary (e.g., refresh token for renewal) and keep other data external.
• gotcha For single-tenant applications, it is crucial to explicitly set the `tenantId` attribute in the MicrosoftStrategy configuration to the 'Directory (tenant) ID' from your App Registration. This restricts logins to users within that specific organization, enhancing security.
  Fix: Ensure `tenantId: 'YOUR_DIRECTORY_TENANT_ID'` is set in your `MicrosoftStrategy` options when you intend to limit access to a single organization. Without it, the application might default to multi-tenant behavior if configured as such in Azure AD.

Install

• npm install remix-auth-microsoft npm
• yarn add remix-auth-microsoft yarn
• pnpm add remix-auth-microsoft pnpm

Imports

• MicrosoftStrategy
  wrong:

  const MicrosoftStrategy = require('remix-auth-microsoft');

  correct:

  import { MicrosoftStrategy } from 'remix-auth-microsoft';

  remix-auth-microsoft is an ESM-first package. Use named imports.
• Authenticator
  wrong:

  const Authenticator = require('remix-auth');

  correct:

  import { Authenticator } from 'remix-auth';

  Authenticator is imported from the peer dependency remix-auth.
• MicrosoftStrategy.userProfile

  let profile = await MicrosoftStrategy.userProfile(accessToken);

  This is a static method on the strategy class used to fetch user details from Microsoft Graph after obtaining an access token.

Quickstart

Demonstrates how to set up the MicrosoftStrategy with Remix Auth, including environment variable usage for credentials, recommended scopes, and a basic user resolution logic. It also includes an example of an authenticator instance and how to use it with the strategy.

// app/services/auth.server.ts
import { MicrosoftStrategy } from "remix-auth-microsoft";
import { Authenticator } from "remix-auth";

interface User {
  id: string;
  // ... other user properties
}

export let authenticator = new Authenticator<User>(/* SessionStorage */);

let microsoftStrategy = new MicrosoftStrategy(
  {
    clientId: process.env.MICROSOFT_CLIENT_ID ?? '',
    clientSecret: process.env.MICROSOFT_CLIENT_SECRET ?? '',
    redirectURI: process.env.MICROSOFT_REDIRECT_URI ?? 'http://localhost:3000/auth/microsoft/callback',
    tenantId: process.env.MICROSOFT_TENANT_ID, // optional for multi-tenant apps
    scopes: ['openid', 'profile', 'email', 'offline_access'], // recommended scopes
    prompt: 'select_account' // 'login', 'consent', 'none', 'select_account'
  },
  async ({ request, tokens, profile }) => {
    // Here you can fetch the user from your database or create a new user
    // based on the profile data from Microsoft.
    // `tokens` contains accessToken, refreshToken, idToken, etc.
    // `profile` contains basic user info parsed from the ID token or user info endpoint.

    // Example: Using a placeholder User.findOrCreate
    // It's crucial to use a reliable identifier like 'sub' from the ID token
    // or 'id' from the user profile, not email, to prevent spoofing.

    const userProfileId = profile.id; // or profile.sub from the ID token
    if (!userProfileId) {
      throw new Error("Could not get user ID from Microsoft profile.");
    }

    // Replace with your actual user management logic
    const user = { id: userProfileId, email: profile.emails?.[0]?.value || 'unknown@example.com' };
    console.log(`Authenticated user: ${user.id} (${user.email})`);

    // The returned object is stored in the session by the authenticator
    return user;
  }
);

authenticator.use(microsoftStrategy, "microsoft");

// Example of a route to initiate authentication
// app/routes/auth.microsoft.tsx
// import type { ActionFunctionArgs } from "@remix-run/node";
// import { redirect } from "@remix-run/node";
// import { authenticator } from "~/services/auth.server";

// export async function action({ request }: ActionFunctionArgs) {
//   return authenticator.authenticate("microsoft", request, {
//     successRedirect: "/dashboard",
//     failureRedirect: "/login",
//   });
// }