Add Microsoft sign-in

You need: the auth capability composed, and access to a Microsoft Entra ID directory where you can register an app.

Time: fifteen minutes, and one optional claim that decides how the first sign-in goes.

Register an application

Google and GitHub are the same shape. What lands at the end is a credential.

Microsoft Entra admin center → Entra ID → App registrations → New registration.

  • Name — whatever your users should see on the consent screen
  • Supported account types — who may sign in. It has to agree with the tenant you store, below
  • Redirect URI — platform Web, and the exact URI below

The overview page gives you an Application (client) ID and a Directory (tenant) ID. Under Certificates & secrets → Client secrets, create a secret and copy its Value, not its Secret ID. Entra shows it once.

Entra client secrets expire, 24 months at the longest. Put the date on somebody’s calendar.

The exact redirect URI

<baseURL><basePath>/callback/microsoft

With the default base path, /auth/callback/microsoft. Register one per environment, under Authentication → Web → Redirect URIs.

EnvironmentRedirect URI
devhttp://localhost:8787/auth/callback/microsoft
staginghttps://staging.example.com/auth/callback/microsoft
productionhttps://example.com/auth/callback/microsoft

Use your actual local port for dev. Entra accepts http:// for localhost only. One registration can list every environment, but a registration per environment keeps a staging secret from ever signing anyone into production.

Feature-branch previews

A preview URL is not on the registration, so Microsoft refuses it on its own page, before your Worker is reached. Add that deployment’s callback and point its baseURL at the same host, or run the flow against staging. Magic link needs no callback at all.

Choose the tenant

The tenant says which accounts may sign in, and it must match the registration’s Supported account types. A mismatch is refused by Microsoft, not by Pithy.

Who signs inTenant
One organizationthe Directory (tenant) ID
Any work or school accountorganizations
Work, school and personal accountscommon
Personal accounts onlyconsumers

The tenant is required. An empty one is refused when the secret is stored, because Better Auth would otherwise fall back to common without saying so. A single-tenant app is the narrowest door, and the safest default for an internal tool.

Turn on xms_edov

Do this step. It is what lets a work or school address link on the first sign-in.

Entra ID cannot vouch for an email it did not verify. A work or school ID token carries no email_verified claim, and its email is a directory attribute a tenant admin can set to anything — your customer’s address included. So Pithy treats a Microsoft address as unverified unless Microsoft says otherwise.

xms_edov, email domain owner verified, is how it says so. Open the registration, go to Manage → Token configuration → Add optional claim, choose token type ID, tick xms_edov, and add it. Pithy already requests the email scope the claim needs.

Skip it, and every work and school address is unverified. Its first sign-in is refused, whether or not an account exists at that address. The person signs in with a magic link, then connects Microsoft from their account, and from then on Microsoft signs them straight in. One magic link, once, per person. Personal accounts are unaffected.

Scope and profile

Pithy requests openid, profile, email, User.Read and offline_access. You do not configure scopes anywhere.

The profile photo is not fetched, so a Microsoft user starts with initials. A directory user with no mail attribute arrives with no email, and that sign-in is refused: there is no address to own an account by.

Mobile

You do not register a deep link with Microsoft. Microsoft only ever redirects to your Worker’s callback.

The app opens the Worker’s GET /auth/sign-in/social/start in the system browser’s sign-in sheet, never posting /auth/sign-in/social itself. Its callbackURL is the app’s own link, carrying as handoff_challenge the S256 challenge of a verifier only the app holds. The Worker completes the exchange, returns to that link with a one-time ?code= rather than a cookie, and the app trades the code and the verifier for its session at POST /auth/handoff. Sign in on iOS and Android has the steps, and pithy ui add react-native scaffolds them. The link has to be in your trusted origins, an https universal link by its origin and a custom scheme by prefix:

auth({
  trustedOrigins: ["myapp://", "https://app.example.com"],
}),

Store the credentials

All three values travel as one typed JSON secret: the client id, the client secret and the tenant.

pithy secrets create auth-microsoft-credentials

An agent or a script pipes the document in on stdin:

printf '%s' '{"clientId":"<client-id>","clientSecret":"<secret-value>","tenantId":"<tenant>"}' | pithy secrets create auth-microsoft-credentials --env <env>

Then enable it, with no credential values in config:

auth({
  microsoft: { enabled: true },
}),

Account linking decides per sign-in

Microsoft is not a trusted provider, and never will be. Whether its address is verified is decided on each sign-in, from claims Microsoft computes and a tenant cannot write.

A Microsoft address is verified when, and only when:

  • the ID token carries xms_edov: true
  • the token’s tenant is the one every personal Microsoft account signs in under
  • you are connecting Microsoft from inside your account, and its address is the one your account already holds

Anything else is unverified. Absence is never read as verification.

The sign-in’s addressWhat happens
Verified, matching an existing userLinks into that account. No second account
UnverifiedRefused. No link, and no new account either
Already connectedSigns in on the Microsoft account itself, not the address

The way through an unverified address is a magic link to it, then connecting Microsoft from the account. If no account exists yet, the magic link creates it. A connected identity signs in by Microsoft’s immutable object id, so a later change to the directory’s mail attribute changes nothing.

allowSignUp is per provider, so microsoft: { enabled: true, allowSignUp: false } lets Microsoft sign existing users in without creating anyone.

When the credential will not read

An enabled provider whose secret is missing or malformed costs that provider and nothing else. Magic link, one-time code and every other provider keep working.

A Microsoft attempt answers 503 with auth/provider_unavailable, naming the provider — rather than the 404 a provider nobody enabled gets. The attempt is recorded in the audit trail.

Checklist

ESC