@itc-bio/vendure-entra-auth

Microsoft Entra ID and Microsoft Entra External ID authentication strategies for Vendure.

The package provides:

• a Shop API strategy for customer login through an Entra External ID / CIAM tenant;
• an Admin API strategy for dashboard users through a company Entra ID tenant;
• a public entraAuthConfig GraphQL query that exposes only non-secret login metadata to browser UIs;
• explicit Entra claim-to-Vendure-role mapping for administrator auto-provisioning.

Native Vendure authentication can remain enabled alongside these strategies for break-glass access.

Installation

npm install @itc-bio/vendure-entra-auth

The package expects Vendure ^3.6.0.

Vendure Config

// vendure-config.ts
import {
    EntraAuthPlugin,
    createEntraAdminAuthenticationStrategy,
    createEntraShopAuthenticationStrategy,
    parseRoleMappings,
    toPublicAuthProviderConfig,
} from '@itc-bio/vendure-entra-auth';
import { NativeAuthenticationStrategy, VendureConfig } from '@vendure/core';

const ciam = {
    issuer: process.env.ENTRA_CIAM_ISSUER!,
    clientId: process.env.ENTRA_CIAM_CLIENT_ID!,
    allowedRedirectUris: ['https://storefront.example.com/store/auth/callback'],
    scopes: ['openid', 'profile', 'email'],
    strategyName: 'entraCiam',
};

const admin = {
    issuer: process.env.ENTRA_ADMIN_ISSUER!,
    clientId: process.env.ENTRA_ADMIN_CLIENT_ID!,
    allowedRedirectUris: ['https://admin.example.com/dashboard/auth/callback'],
    roleMappings: parseRoleMappings(process.env.ENTRA_ADMIN_ROLE_MAPPINGS),
    scopes: ['openid', 'profile', 'email'],
    strategyName: 'entraAdmin',
};

export const config: VendureConfig = {
    authOptions: {
        shopAuthenticationStrategy: [
            new NativeAuthenticationStrategy(),
            createEntraShopAuthenticationStrategy({
                ...ciam,
                requireVerifiedEmail: true,
            }),
        ],
        adminAuthenticationStrategy: [
            new NativeAuthenticationStrategy(),
            createEntraAdminAuthenticationStrategy({
                ...admin,
                allowAutoCreate: false,
            }),
        ],
        // ...
    },
    plugins: [
        EntraAuthPlugin.init({
            ciam: toPublicAuthProviderConfig(ciam),
            admin: toPublicAuthProviderConfig(admin),
        }),
    ],
};

Browser Login Flow

The browser application owns the Microsoft authorization redirect:

1. Generate state, nonce, a PKCE codeVerifier, and an S256 codeChallenge.
2. Redirect to the configured Microsoft authorize endpoint.
3. Receive code and state on the configured callback route.
4. Validate state locally in the browser.
5. Call Vendure's authenticate mutation with the authorization code, codeVerifier, redirectUri, and nonce.
6. Let Vendure create its normal cookie or bearer-token session.

Shop API example:

mutation AuthenticateWithEntra($input: AuthenticationInput!) {
    authenticate(input: $input) {
        ... on CurrentUser {
            id
            identifier
        }
        ... on ErrorResult {
            errorCode
            message
        }
    }
}

{
    "input": {
        "entraCiam": {
            "code": "<authorization-code>",
            "codeVerifier": "<pkce-code-verifier>",
            "redirectUri": "https://storefront.example.com/store/auth/callback",
            "nonce": "<nonce>"
        }
    }
}

Admin API example:

{
    "input": {
        "entraAdmin": {
            "code": "<authorization-code>",
            "codeVerifier": "<pkce-code-verifier>",
            "redirectUri": "https://admin.example.com/dashboard/auth/callback",
            "nonce": "<nonce>"
        }
    }
}

The redirectUri must match both the Microsoft app registration and the strategy's allowedRedirectUris list.

Public Config Query

The plugin exposes non-secret login metadata so UIs do not need to hard-code tenant settings:

query EntraAuthConfig {
    entraAuthConfig {
        ciam {
            issuer
            clientId
            scopes
            strategyName
            allowedRedirectUris
        }
        admin {
            issuer
            clientId
            scopes
            strategyName
            allowedRedirectUris
        }
    }
}

The Shop API resolver returns CIAM config. The Admin API resolver returns admin config. Client secrets and token responses are never exposed.

Admin Role Mapping

Administrator auto-creation is disabled unless allowAutoCreate is set and at least one role mapping is configured.

Mappings use this syntax:

claim=value:VendureRoleCode

Examples:

groups=00000000-0000-0000-0000-000000000000:CatalogAdmin
roles=VendureAdmin:Administrator

The role code must already exist in Vendure. The plugin resolves role codes through Vendure's RoleService, so Entra configuration cannot invent new permissions.

Security Notes

• Use authorization code flow with PKCE. Do not use implicit flow.
• Keep native Vendure admin authentication enabled until SSO is proven and documented as your break-glass procedure.
• Use allowedRedirectUris and allowedTenantIds in production.
• Do not expose Microsoft token endpoint responses or ID-token claims to the browser.
• Prefer app roles or group object IDs for admin authorization; do not grant administrator access based only on email domain.

Testing

npm test

The test suite covers claim parsing, role-code mapping, redirect allowlists, token endpoint errors, nonce mismatch, tenant allowlists, and basic claim mapping.