@mantlejs/auth-microsoft

Microsoft (Entra ID) OAuth 2.0 strategy for Mantle JS. Implements the authorization code flow with PKCE — no Passport.js dependency. Registers GET /auth/microsoft and GET /auth/microsoft/callback on the HTTP transport, then finds or creates a user record and returns a Mantle JWT pair.

Installation

npm install @mantlejs/auth-microsoft

Concepts

PKCE

Microsoft Sign-In uses the authorization code flow with PKCE (Proof Key for Code Exchange). On each redirect request the plugin generates a fresh code_verifier (via Arctic, which also derives the SHA-256 / base64url code_challenge — see ADR-002). The verifier is stored server-side against a random state token and passed to the token exchange on callback.

Tenant

Entra ID scopes sign-in to a tenant. The default, "common", accepts both work/school (Entra ID) and personal Microsoft accounts. Set tenant to "organizations" (work/school only), "consumers" (personal only), or a specific tenant ID to restrict who can sign in — it must match the Supported account types of your app registration.

Find-or-create

On callback the plugin searches the configured user service for a record where microsoftId (configurable) matches the sub claim from Microsoft Graph's OIDC userinfo endpoint. If no record is found, it creates one with { microsoftId, email, name } from the profile. The same user is returned on every subsequent sign-in.

Quick start

import { mantle } from "@mantlejs/mantle";
import { express } from "@mantlejs/express";
import { auth } from "@mantlejs/auth";
import { microsoftStrategy } from "@mantlejs/auth-microsoft";

const app = mantle()
  .configure(express())
  .configure(auth({ secret: process.env.JWT_SECRET! }))
  .configure(
    microsoftStrategy({
      clientId: process.env.MICROSOFT_CLIENT_ID!,
      clientSecret: process.env.MICROSOFT_CLIENT_SECRET!,
    }),
  );

app.listen(3030);

Sign-in flow:

1. Redirect the browser to GET /auth/microsoft
2. User authenticates on Microsoft and consents
3. Microsoft redirects to GET /auth/microsoft/callback?code=...&state=...
4. The plugin exchanges the code, fetches the profile, finds or creates the user, and responds:

{
  "accessToken": "eyJhbGciOiJIUzI1NiJ9...",
  "refreshToken": "eyJhbGciOiJIUzI1NiJ9...",
  "user": { "id": "1", "microsoftId": "AAAA...", "email": "[email protected]", "name": "Alice" }
}

API

microsoftStrategy(config)

function microsoftStrategy(config: MicrosoftStrategyConfig): MantlePlugin;

interface MicrosoftStrategyConfig extends OAuthPluginConfig {
  tenant?: string; // Default: 'common'
}

| Field | Type | Default | Description | | --------------- | ---------- | -------------------------------- | ------------------------------------------------------------------------------ | | clientId | string | — | Entra ID application (client) ID (required) | | clientSecret | string | — | Entra ID client secret (required) | | tenant | string | 'common' | Entra tenant: 'common', 'organizations', 'consumers', or a tenant ID | | callbackUrl | string | '/auth/microsoft/callback' | Callback path — must match the redirect URI registered in the app registration | | scope | string[] | ['openid', 'profile', 'email'] | Microsoft OAuth scopes | | entity | string | 'users' | Mantle service used to find or create users | | entityIdField | string | 'microsoftId' | Field on the user record matched against Microsoft's sub claim | | redirectUrl | string | none — returns JSON | Frontend URL to redirect to on completion, with tokens (or an error) in the URL fragment — see @mantlejs/auth-oauth |

Routes registered:

| Method | Path | Description | | ------ | -------------------------- | -------------------------------------- | | GET | /auth/microsoft | Redirect to Microsoft sign-in | | GET | /auth/microsoft/callback | Handle callback, issue Mantle JWT pair |

Must be configured after the transport (e.g. express()) and auth().

Types

import type { MicrosoftStrategyConfig } from "@mantlejs/auth-microsoft";

MicrosoftStrategyConfig extends OAuthPluginConfig from @mantlejs/auth-oauth with the optional tenant field.

Microsoft Entra admin center setup

1. Register an application at entra.microsoft.com → App registrations → New registration
2. Choose the Supported account types matching your tenant setting
3. Add a Web redirect URI: https://your-domain.com/auth/microsoft/callback
4. Under Certificates & secrets, create a client secret
5. Copy the Application (client) ID and the secret value into your environment

Development

npx nx build auth-microsoft   # compile
npx nx test auth-microsoft    # run tests
npx nx lint auth-microsoft    # lint

Publishing

npx nx build auth-microsoft
cd packages/auth-microsoft
npm publish --access public