OIDC login with Azure (Entra ID) — enterprise

[Rimander]

Motivation

Some of the sites I've planned to build on EmDash have been missing, among other things, the ability to connect to Azure (Entra ID) for user authentication, since it's a fairly standardized authentication system in corporate environments.

Starting point: almost everything is already there

EmDash already has OIDC login working with Google and GitHub. Google is in fact OIDC (scopes: openid email profile, reads the sub claim). The mechanism can be enabled with a single line of config and works end-to-end (button on /admin/login + OAuth redirect with PKCE). Adding Azure is an additive change of the same kind, not auth from scratch.

There are two layers, both already in place for google/github:

• Server (packages/auth/src/oauth/* + routes /_emdash/api/auth/oauth/[provider]): Authorization Code + PKCE flow + token exchange + profile.
• UI/registration (packages/core/src/auth/providers/*): the button on the login page, enabled via authProviders: [...] in the site config.

What needs to be added for Azure

1. Azure provider (server) — modeled on google.ts

• packages/auth/src/oauth/providers/azure.ts with the Entra endpoints per tenant:
  • authorize: https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize
  • token: https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token
  • userinfo: https://graph.microsoft.com/oidc/userinfo
• parseProfile adapted to Azure: the email may come in email, preferred_username or upn (fallback), and Azure does not send email_verified (treated as verified because it's a trusted IdP).
• Generalize the "github" | "google" union and add tenantId to the config.

2. id_token verification (the "enterprise" part)

Instead of trusting userinfo alone, we validate the id_token returned by Azure:

• Verify the RS256 signature against Azure's JWKS.
• Validate claims: iss, aud (= client_id), exp and nonce (the nonce is already provisioned in the state and the state store already persists it).

This prevents accepting tokens not issued for our app. It's the correct approach in a corporate setting.

3. Login button (UI)

• packages/core/src/auth/providers/azure.ts (descriptor) + azure-admin.tsx (the "Azure" button), just like google/github. Strings via Lingui, RTL-safe.

4. Role mapping

Reuse what already exists: allowed_domains maps email domain → role. So "users from @mycompany.com → Editor role", while the admin still logs in via passkey or it gets assigned to another person.

How it would be used

In the site's astro.config.*:

import { azure } from "emdash/auth/providers/azure";

emdash({
  // ...
  authProviders: [azure()],
});

And in .env:

EMDASH_OAUTH_AZURE_CLIENT_ID=...
EMDASH_OAUTH_AZURE_CLIENT_SECRET=...
EMDASH_OAUTH_AZURE_TENANT_ID=...

In Entra, register the redirect URI: https://<domain>/_emdash/api/auth/oauth/azure/callback

[danielmlr]

I have the same need, and I would like to build this if nobody else is on it.

@Rimander, are you still working on this? Your write-up already covers the parts that are easy to get wrong, in particular the RS256 signature check against the JWKS and the nonce validation. I would rather help than duplicate the work.

I keep running into the same case: a company with 5–20 people. Everyone there has a Microsoft 365 account. Nobody has a GitHub or Google identity. They want editors to sign in with their work account, and they want that account to stop working when IT disables it in the directory. Passkeys work for them, but a passkey does not connect the account to the directory.

Why the Cloudflare Access route doesn't close this

access() already federates Entra ID and maps IdP groups to EmDash roles (resolveRoleFromGroups in packages/cloudflare/src/auth/cloudflare-access.ts:221). Two things keep it from covering this case.

It runs only on Cloudflare. A site on Node with PostgreSQL has no Microsoft path today.

It also replaces the login flow instead of adding to it. Once authMode is anything other than passkey, the login page redirects instead of rendering (packages/admin/src/components/LoginPage.tsx:185), /_emdash/api/auth/mode reports signupEnabled: false because it counts allowed domains only in passkey mode (packages/core/src/astro/routes/api/auth/mode.ts:26), and the admin hides both the passkey and the self-signup settings screens (packages/admin/src/components/settings/SecuritySettings.tsx:30, packages/admin/src/components/settings/AllowedDomainsSettings.tsx:52). An editor then has one way in, and it is the one Access provides.

Three shapes a provider can have

Since #398 there are two ways to build a provider, plus a third option on top.

A core provider next to google(). packages/core/src/auth/providers/google.ts is only a descriptor: an id, a label, an admin entry. The OAuth work sits in the shared consumer, where the provider name is the fixed union "github" | "google". A third name has to be added in four files. packages/auth/src/oauth/consumer.ts names the providers in five places — the providers config shape, two function signatures, the getProvider signature and its switch — plus the import and re-export of the provider module. packages/auth/src/config.ts names them twice, once in the Zod schema and once in the TypeScript interface. The route files [provider].ts and [provider]/callback.ts each declare their own ProviderName alias and VALID_PROVIDERS set.

A separate package on the @emdash-cms/auth-atproto model. An AuthProviderDescriptor carries its own routes, publicRoutes, adminEntry and storage, and its id is a plain string (packages/core/src/auth/types.ts:94). A provider in this shape needs none of the edits above. The descriptor is defined in packages/core, not in packages/cloudflare, so the shape itself does not tie a provider to one runtime.

A generic oidc({ issuer }) provider. Discovery at ${issuer}/.well-known/openid-configuration would cover Entra ID, Keycloak, Authentik, Okta and Auth0 in one go. It costs more: discovery caching and JWKS handling. The other two options can hardcode the endpoints and read the profile from the userinfo endpoint, the way google does today. Whether they also verify the id_token against the JWKS is a separate choice.

There is a hint that something like the third option was planned early. packages/auth/src/types.ts:203 still carries this interface from the first commit. Nothing references it, and no table backs it:

export interface OAuthConnection {
  id: string;
  name: string;
  provider: "oidc" | "github" | "google";
  clientId: string;
  clientSecretEnc: string; // Encrypted
  issuerUrl: string | null;
  ...
}

The encrypted secret and the nullable issuerUrl suggest a different model: connections that an admin configures at runtime and the database stores. Providers work the other way today, wired up in astro.config.mjs with environment variables.

The harder question is email verification

Entra ID does not send email_verified, and the ID token claims reference documents no such claim. Your post treats the address as verified because it comes from a trusted IdP. That is the part I would want settled before anyone writes code.

emailVerified gates two things in EmDash. It gates auto-linking an OAuth login to an existing account with the same email (packages/auth/src/oauth/consumer.ts:336):

// Check if user with this email exists (auto-link)
// Only auto-link when the provider has verified the email to prevent
// account takeover via unverified email on a third-party provider
const existingUser = await adapter.getUserByEmail(profile.email);
if (existingUser) {
  if (!profile.emailVerified) {
    throw new OAuthError("signup_not_allowed", "Cannot link account: email not verified by provider");
  }

A second guard in acceptInviteViaOAuth rejects an invite with invite_email_unverified (consumer.ts:154). Setting the flag to true for every Entra login turns off both for Microsoft accounts.

Microsoft's claims reference argues against a blanket true. It calls preferred_username mutable and adds that it "can't be used to make authorization decisions". For email it says "Never use it for authorization or to save data for a user". Availability differs as well: email is a default claim only for guest accounts, and managed users need either the optional claim or the email scope.

A blanket true looks defensible for a single-tenant app where every user is a managed member of that tenant. It looks wrong for a multi-tenant registration or the common endpoint, where the address comes from a directory the site does not control. Either way it should be a deliberate setting in the provider config, not a side effect of a missing claim.

Naming

Microsoft renamed the product to Entra ID in 2023, and "Azure AD" is the legacy name. The login host stays login.microsoftonline.com either way. I'd suggest microsoft() over azure(): it survives the next rename, and it matches what the button says to an editor.

Questions

1. Is a built-in Microsoft provider wanted at all, or is Access the intended answer for company directories?
2. If it is wanted: a separate package on the auth-atproto model, or a core provider next to google()?
3. Should a generic oidc({ issuer }) come first instead, so Keycloak and Okta arrive with it?
4. What should emailVerified be for Entra, and under which tenant configuration?

Happy to open the PR once the direction is settled. Without an answer I'd default to a separate package, because that shape leaves the provider union untouched.

[Rimander]

Thanks so much for your comment, @danielmlr ! First of all, my apologies for the late reply.

As a temporary workaround while waiting for feedback/approval on this discussion (cc @ascorbic ), I went ahead and implemented it locally for all the sites we currently run on EmDash.

I ended up going with the first option (core provider, editing the union in the core files) simply to follow the exact same flow already in place for Google and GitHub.

Your points regarding email_verified are really insightful and make a lot of sense. I hadn't considered the security implications because our setup is strictly single-tenant, where trusting the directory directly works fine, but I see why a blanket true is problematic for multi-tenant or generic setups.

Please feel free to open a PR if you'd like to take the lead on this! That said, unless the project's contribution rules have changed recently, I believe discussions usually need to be approved/blessed first before opening a PR. Since this is an additive provider rather than a core overhaul, I'm not entirely sure if that strict rule applies here, but it's worth keeping in mind.

Happy to test, review, or collaborate however I can!

[ascorbic]

Thanks, both. I've approved this one for a PR, so whoever is able to work on it feel free to open one!