Context7 Platform -- Up-to-date docs for AI agents
feat(mcp): multi-tenant Entra ID validation (#2629)
Fahreddin Özcan1fb2d421276f
diff --git a/.changeset/mcp-multi-tenant-entra.md b/.changeset/mcp-multi-tenant-entra.mdnew file mode 100644index 00000000..3b984c12--- /dev/null+++ b/.changeset/mcp-multi-tenant-entra.md@@ -0,0 +1,5 @@+---+"@upstash/context7-mcp": minor+---++Add multi-tenant Microsoft Entra ID validation for MCP tokens. The server now detects inbound Entra v2 tokens by issuer pattern, fetches per-teamspace configuration (`tenantId`, `audience`, `requiredScope`) from the Context7 app, and verifies the token against the matching tenant's JWKS, enforcing the required scope claim when configured. User resolution happens downstream in the Context7 app against a pre-provisioned user mapping table — the MCP server only validates. Per-tenant JWKS cache and a 5-minute in-memory config cache keyed by JWT audience reduce overhead under load.diff --git a/packages/mcp/src/lib/jwt.ts b/packages/mcp/src/lib/jwt.tsindex beacb113..2695c461 100644--- a/packages/mcp/src/lib/jwt.ts+++ b/packages/mcp/src/lib/jwt.ts@@ -1,10 +1,58 @@import * as jose from "jose";-import { CLERK_DOMAIN } from "./constants.js";+import { CLERK_DOMAIN, CONTEXT7_API_BASE_URL } from "./constants.js";-const JWKS_URL = `https://${CLERK_DOMAIN}/.well-known/jwks.json`;-const ISSUER = `https://${CLERK_DOMAIN}`;+const CLERK_ISSUER = `https://${CLERK_DOMAIN}`;+const clerkJwks = jose.createRemoteJWKSet(new URL(`https://${CLERK_DOMAIN}/.well-known/jwks.json`));-const jwks = jose.createRemoteJWKSet(new URL(JWKS_URL));+const ENTRA_V2_ISSUER_RE = /^https:\/\/login\.microsoftonline\.com\/[0-9a-f-]{36}\/v2\.0$/;++const jwksByTenant = new Map<string, ReturnType<typeof jose.createRemoteJWKSet>>();+function entraJwks(tenantId: string) {+ let jwks = jwksByTenant.get(tenantId);+ if (!jwks) {+ jwks = jose.createRemoteJWKSet(+ new URL(`https://login.microsoftonline.com/${tenantId}/discovery/v2.0/keys`)+ );+ jwksByTenant.set(tenantId, jwks);+ }+ return jwks;+}++interface EntraConfig {+ teamspaceId: string;+ tenantId: string;+ requiredScope: string | null;+}++const CONFIG_TTL_MS = 5 * 60 * 1000;+const configByAudience = new Map<string, { value: EntraConfig | null; expiresAt: number }>();++async function fetchEntraConfig(audience: string): Promise<EntraConfig | null> {+ const now = Date.now();+ const cached = configByAudience.get(audience);+ if (cached && cached.expiresAt > now) return cached.value;++ try {+ const res = await fetch(+ `${CONTEXT7_API_BASE_URL}/v2/entra/config/${encodeURIComponent(audience)}`+ );+ if (res.ok) {+ const value = (await res.json()) as EntraConfig;+ configByAudience.set(audience, { value, expiresAt: now + CONFIG_TTL_MS });+ return value;+ }+ if (res.status === 404) {+ // Authoritative "not configured" response — safe to cache the miss so we+ // don't hammer the app on every token verification.+ configByAudience.set(audience, { value: null, expiresAt: now + CONFIG_TTL_MS });+ return null;+ }+ } catch {+ // Network or JSON parse error: transient. Fall through without caching so+ // the next request retries.+ }+ return null;+}export interface JWTValidationResult {valid: boolean;@@ -12,16 +60,37 @@ export interface JWTValidationResult {}export function isJWT(token: string): boolean {- const parts = token.split(".");- return parts.length === 3;+ return token.split(".").length === 3;}export async function validateJWT(token: string): Promise<JWTValidationResult> {try {- await jose.jwtVerify(token, jwks, {- issuer: ISSUER,- });+ const decoded = jose.decodeJwt(token);+ const iss = typeof decoded.iss === "string" ? decoded.iss : "";++ if (ENTRA_V2_ISSUER_RE.test(iss)) {+ const audience = typeof decoded.aud === "string" ? decoded.aud : "";+ if (!audience) return { valid: false, error: "Missing audience" };++ const config = await fetchEntraConfig(audience);+ if (!config) return { valid: false, error: "Unknown audience" };++ const { payload } = await jose.jwtVerify(token, entraJwks(config.tenantId), {+ issuer: `https://login.microsoftonline.com/${config.tenantId}/v2.0`,+ audience,+ });++ if (config.requiredScope) {+ const scopes = String(payload.scp ?? "").split(" ");+ if (!scopes.includes(config.requiredScope)) {+ return { valid: false, error: "Missing required scope" };+ }+ }++ return { valid: true };+ }+ await jose.jwtVerify(token, clerkJwks, { issuer: CLERK_ISSUER });return { valid: true };} catch (error) {if (error instanceof jose.errors.JWTExpired) {diff --git a/packages/mcp/test/jwt.test.ts b/packages/mcp/test/jwt.test.tsnew file mode 100644index 00000000..4abd8cc0--- /dev/null+++ b/packages/mcp/test/jwt.test.ts@@ -0,0 +1,193 @@+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";+import * as jose from "jose";++vi.mock("jose", async () => {+ const actual = await vi.importActual<typeof jose>("jose");+ return {+ ...actual,+ createRemoteJWKSet: vi.fn(+ () => "fake-jwks" as unknown as ReturnType<typeof jose.createRemoteJWKSet>+ ),+ jwtVerify: vi.fn(),+ };+});++const TENANT_ID = "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa";+const ENTRA_ISSUER = `https://login.microsoftonline.com/${TENANT_ID}/v2.0`;+const AUDIENCE = "6ff6a635-03d9-472d-a7f1-dc98a4e5fde2";++async function loadModule() {+ vi.resetModules();+ return import("../src/lib/jwt.js");+}++function makeFetchResponse(init: Partial<Response> & { jsonData?: unknown }): Response {+ const { jsonData, ...rest } = init;+ return {+ ok: true,+ status: 200,+ json: async () => jsonData,+ ...rest,+ } as Response;+}++function makeEntraToken(payload: jose.JWTPayload): string {+ const header = Buffer.from(JSON.stringify({ alg: "RS256", typ: "JWT" })).toString("base64url");+ const body = Buffer.from(JSON.stringify(payload)).toString("base64url");+ return `${header}.${body}.signature`;+}++beforeEach(() => {+ vi.stubGlobal("fetch", vi.fn());+});++afterEach(() => {+ vi.unstubAllGlobals();+ vi.clearAllMocks();+});++describe("isJWT", () => {+ test("returns true for 3-part dotted strings", async () => {+ const { isJWT } = await loadModule();+ expect(isJWT("a.b.c")).toBe(true);+ });++ test("returns false for non-JWT strings", async () => {+ const { isJWT } = await loadModule();+ expect(isJWT("not-a-jwt")).toBe(false);+ expect(isJWT("only.two")).toBe(false);+ expect(isJWT("a.b.c.d")).toBe(false);+ });+});++describe("validateJWT - Entra path", () => {+ test("validates token after fetching tenant config", async () => {+ const fetchMock = vi.mocked(fetch);+ fetchMock.mockResolvedValueOnce(+ makeFetchResponse({+ jsonData: { teamspaceId: "team-1", tenantId: TENANT_ID, requiredScope: "mcp.access" },+ })+ );+ vi.mocked(jose.jwtVerify).mockResolvedValue({+ payload: { oid: "user-oid", scp: "mcp.access" },+ protectedHeader: { alg: "RS256" },+ } as unknown as Awaited<ReturnType<typeof jose.jwtVerify>>);++ const { validateJWT } = await loadModule();+ const result = await validateJWT(makeEntraToken({ iss: ENTRA_ISSUER, aud: AUDIENCE }));++ expect(result.valid).toBe(true);+ expect(fetchMock).toHaveBeenCalledTimes(1);+ expect(fetchMock.mock.calls[0][0]).toContain(`/v2/entra/config/${AUDIENCE}`);+ });++ test("returns 'Unknown audience' when config endpoint returns 404", async () => {+ vi.mocked(fetch).mockResolvedValue(makeFetchResponse({ ok: false, status: 404 }));++ const { validateJWT } = await loadModule();+ const result = await validateJWT(makeEntraToken({ iss: ENTRA_ISSUER, aud: "unknown-aud" }));++ expect(result.valid).toBe(false);+ expect(result.error).toBe("Unknown audience");+ expect(jose.jwtVerify).not.toHaveBeenCalled();+ });++ test("returns 'Missing required scope' when scp claim lacks the configured scope", async () => {+ vi.mocked(fetch).mockResolvedValue(+ makeFetchResponse({+ jsonData: { teamspaceId: "team-1", tenantId: TENANT_ID, requiredScope: "mcp.access" },+ })+ );+ vi.mocked(jose.jwtVerify).mockResolvedValue({+ payload: { scp: "other.scope" },+ protectedHeader: { alg: "RS256" },+ } as unknown as Awaited<ReturnType<typeof jose.jwtVerify>>);++ const { validateJWT } = await loadModule();+ const result = await validateJWT(makeEntraToken({ iss: ENTRA_ISSUER, aud: AUDIENCE }));++ expect(result.valid).toBe(false);+ expect(result.error).toBe("Missing required scope");+ });++ test("returns 'Missing audience' for Entra issuer with no aud claim", async () => {+ const { validateJWT } = await loadModule();+ const result = await validateJWT(makeEntraToken({ iss: ENTRA_ISSUER }));++ expect(result.valid).toBe(false);+ expect(result.error).toBe("Missing audience");+ expect(fetch).not.toHaveBeenCalled();+ });++ test("caches config across repeated audiences", async () => {+ const fetchMock = vi.mocked(fetch);+ fetchMock.mockResolvedValue(+ makeFetchResponse({+ jsonData: { teamspaceId: "team-1", tenantId: TENANT_ID, requiredScope: null },+ })+ );+ vi.mocked(jose.jwtVerify).mockResolvedValue({+ payload: { oid: "u" },+ protectedHeader: { alg: "RS256" },+ } as unknown as Awaited<ReturnType<typeof jose.jwtVerify>>);++ const { validateJWT } = await loadModule();+ const token = makeEntraToken({ iss: ENTRA_ISSUER, aud: AUDIENCE });+ await validateJWT(token);+ await validateJWT(token);++ expect(fetchMock).toHaveBeenCalledTimes(1);+ });++ test("does not cache transient 500 errors — next request retries", async () => {+ const fetchMock = vi.mocked(fetch);+ fetchMock.mockResolvedValueOnce(makeFetchResponse({ ok: false, status: 500 }));+ fetchMock.mockResolvedValueOnce(+ makeFetchResponse({+ jsonData: { teamspaceId: "team-1", tenantId: TENANT_ID, requiredScope: null },+ })+ );+ vi.mocked(jose.jwtVerify).mockResolvedValue({+ payload: { oid: "u" },+ protectedHeader: { alg: "RS256" },+ } as unknown as Awaited<ReturnType<typeof jose.jwtVerify>>);++ const { validateJWT } = await loadModule();+ const token = makeEntraToken({ iss: ENTRA_ISSUER, aud: AUDIENCE });++ const first = await validateJWT(token);+ expect(first.valid).toBe(false);+ expect(first.error).toBe("Unknown audience");++ const second = await validateJWT(token);+ expect(second.valid).toBe(true);+ expect(fetchMock).toHaveBeenCalledTimes(2);+ });+});++describe("validateJWT - Clerk path", () => {+ test("verifies against Clerk JWKS for non-Entra issuers", async () => {+ vi.mocked(jose.jwtVerify).mockResolvedValue({+ payload: {},+ protectedHeader: { alg: "RS256" },+ } as unknown as Awaited<ReturnType<typeof jose.jwtVerify>>);++ const { validateJWT } = await loadModule();+ const result = await validateJWT(makeEntraToken({ iss: "https://clerk.context7.com" }));++ expect(result.valid).toBe(true);+ expect(fetch).not.toHaveBeenCalled();+ });++ test("returns 'Token expired' when jwtVerify throws JWTExpired", async () => {+ vi.mocked(jose.jwtVerify).mockRejectedValue(+ new jose.errors.JWTExpired("expired", { payload: {}, protectedHeader: { alg: "RS256" } })+ );++ const { validateJWT } = await loadModule();+ const result = await validateJWT(makeEntraToken({ iss: "https://clerk.context7.com" }));++ expect(result.valid).toBe(false);+ expect(result.error).toBe("Token expired");+ });+});