Full-Stack MSAL (Client + Server) – Discussion & Working Example

[DaliborHomola]

Hey everyone! 👋
I’d like to open a discussion around full-stack MSAL v5 usage (client + server) in TanStack Start.
I couldn't find any complete public example—so here’s my working setup to help others and hopefully spark better ideas.

In my example, I've got:
✅ MSAL on the client (interactive login, Graph calls)
✅ MSAL on the server (server-side validation, protected server functions)
✅ Group-based authorization via Azure AD Groups
✅ Perform permission checks in beforeLoad route prop

This is a long-ish post, but useful for anyone building a full-stack MSAL setup.

Install packages: npm i @azure/msal-browser @azure/msal-node @azure/msal-react jose

Let's start from beggining - load user into router context and wrap app with provider

// __root.tsx
export const Route = createRootRouteWithContext<RouterContext>()({
  beforeLoad: async () => {
    const user = await getUser();
    return { user };
  },
});

return (
  <MsalAuthProvider>
    {children}
  </MsalAuthProvider>
);

Implementation of MSAL in client

// /src/lib/auth/client.ts
export const pca = new PublicClientApplication({
  auth: {
    clientId: clientEnv.VITE_ENTRA_CLIENT_ID,
    authority: `https://login.microsoftonline.com/${clientEnv.VITE_ENTRA_TENANT_ID}`,
    redirectUri: "/",
  },
});

const restoreActiveAccount = () => {
  if (pca.getActiveAccount()) return;
  const [firstAccount] = pca.getAllAccounts();
  if (firstAccount) pca.setActiveAccount(firstAccount);
};

const initializeMsal = async () => {
  if (globalThis.window === undefined) return;

  await pca.initialize();

  pca.addEventCallback((event: EventMessage) => {
    if (event.eventType === EventType.LOGIN_SUCCESS && event.payload) {
      const payload = event.payload as AuthenticationResult;
      pca.setActiveAccount(payload.account);
    }
  });

  const response = await pca.handleRedirectPromise();
  if (response?.account) {
    pca.setActiveAccount(response.account);
    return;
  }

  restoreActiveAccount();
};

const initializationPromise = initializeMsal();
await initializationPromise;

export const msalReady = () => initializationPromise;

export class TanStackNavigationClient extends NavigationClient {
  constructor(private readonly navigate: ReturnType<typeof useNavigate>) {
    super();
  }
  async navigateInternal(url: string, options: NavigationOptions) {
    const relative = url.replace(location.origin, "");
    this.navigate({ to: relative, replace: options.noHistory });
    return false;
  }
}

export const getUser = createIsomorphicFn()
  .server(() => null)
  .client(async (): Promise<User | null> => {
    await initializationPromise;
    restoreActiveAccount();

    const account = pca.getActiveAccount();
    if (!account?.idToken) return null;

    return buildUser(decodeJwt(account.idToken));
  });

/**
 * Token Acquisition: Get authenticated access token.
 * Use when: Making API calls from the browser to secured endpoints.
 */
export const getAccessToken = createClientOnlyFn(async (scopeKey: keyof typeof definedScopes) => {
  await initializationPromise;
  restoreActiveAccount();

  const account = pca.getActiveAccount();
  if (!account) throw new Error("No active account. User not signed in.");

  const scopes = [...definedScopes[scopeKey]];

  try {
    const { accessToken } = await pca.acquireTokenSilent({ scopes, account });
    return accessToken;
  } catch (error) {
    if (error instanceof InteractionRequiredAuthError) {
      try {
        await pca.acquireTokenRedirect({ scopes, account });
      } catch (redirectError) {
        // Another interaction is already in progress — MSAL will handle it.
        if (
          !(redirectError instanceof BrowserAuthError) ||
          redirectError.errorCode !== "interaction_in_progress"
        ) {
          throw redirectError;
        }
      }

      // Keep the caller suspended until the page navigates away so pending
      // server functions don't fire without an Authorization header.
      await new Promise<never>(() => {});
    }

    throw error;
  }
});

The server needs a separate msalConfig because only server code can safely access confidential environment variables.

// /src/lib/auth/server.ts
// Singleton instance for server
let ccaInstance: ConfidentialClientApplication | null = null;
function getCCA(): ConfidentialClientApplication {
  ccaInstance ??= new ConfidentialClientApplication({
    auth: {
      clientId: serverEnv.ENTRA_CLIENT_ID,
      clientSecret: serverEnv.ENTRA_CLIENT_SECRET,
      authority: `https://login.microsoftonline.com/${serverEnv.ENTRA_TENANT_ID}`,
    },
  });
  return ccaInstance;
}

/**
 * On-Behalf-Of flow: Exchange user token for a token to call downstream API
 * Use when: Server needs to call microservice on behalf of the logged-in user
 */
export const getTokenOnBehalfOf = createServerOnlyFn(
  async (userToken: string, scopeKey: keyof typeof definedScopes): Promise<string> => {
    const cca = getCCA();
    const scopes = [...definedScopes[scopeKey]];
    const result = await cca.acquireTokenOnBehalfOf({
      oboAssertion: userToken,
      scopes,
    });
    if (!result) throw new Error("Failed to acquire OBO token");
    return result.accessToken;
  },
);

/**
 * Client Credentials flow: Get app-only token (no user context)
 * Use when: Background jobs, scheduled tasks, service-to-service calls
 */
export const getAppToken = createServerOnlyFn(
  async (scopeKey: keyof typeof definedScopes): Promise<string> => {
    const cca = getCCA();
    const scopes = definedScopes[scopeKey];
    const defaultScopes = scopes.map((scope) => {
      const lastSlash = scope.lastIndexOf("/");
      const baseUri = scope.substring(0, lastSlash);
      return `${baseUri}/.default`;
    });
    const uniqueScopes = [...new Set(defaultScopes)];
    const result = await cca.acquireTokenByClientCredential({ scopes: uniqueScopes });
    if (!result) throw new Error("Failed to acquire app token");
    return result.accessToken;
  },
);

Define Types

// src/models/User.ts
export type User = {
  id: string;
  name: string;
  email: string;
  hasPermission: (key: keyof typeof permissions) => boolean;
};

// src/lib/auth/permissions.ts - if you plan to have authorization (optional)
export const permissions = {
  admin: ["developers"],
} as const;

// src/lib/auth/scopes.ts - if you plan to use multiple microservices within your organization (optional)
export const scopes = {
  graph: ["User.Read"],
  api: ["api://wistron.com/my-scope/access_as_user"],
} as const;

// src/types/auth.ts - typesafety for scope/permissions (optional)
declare module "your-path" {
  export const permissions: typeof import("~/lib/auth/permissions").permissions;
  export const scopes: typeof import("~/lib/auth/scopes").scopes;
}

Now the Provider

// src/providers/MsalAuthProvider.ts
const MsalAuthEffects: FC = () => {
  const { inProgress, instance } = useMsal();
  const router = useRouter();
  const previousInProgress = useRef(inProgress);
  const navigate = useNavigate();

  useEffect(() => {
    pca.setNavigationClient(new TanStackNavigationClient(navigate));
  }, [navigate]);

  useEffect(() => {
    const callbackId = instance.addEventCallback((event: EventMessage) => {
      if (
        event.eventType === EventType.LOGIN_SUCCESS ||
        event.eventType === EventType.ACQUIRE_TOKEN_SUCCESS ||
        event.eventType === EventType.LOGOUT_SUCCESS
      ) {
        void router.invalidate();
      }
    });

    return () => {
      if (callbackId) {
        instance.removeEventCallback(callbackId);
      }
    };
  }, [instance, router]);

  useEffect(() => {
    const wasInteracting = previousInProgress.current !== InteractionStatus.None;
    previousInProgress.current = inProgress;

    if (wasInteracting && inProgress === InteractionStatus.None) {
      void router.invalidate();
    }
  }, [inProgress, router]);

  return null;
};

export const MsalAuthProvider: FC<MsalAuthProviderProps> = ({ children }) => (
  <MsalProvider instance={pca}>
    <MsalAuthEffects />
    {children}
  </MsalProvider>
);

We are going to finish now, let's implement TanStack Start middleware

// /src/server/middleware/auth.ts
const requiredAuthenticationMiddleware = createMiddleware().server<{ user: User }>(
  async ({ next, request }) => {
    const accessToken = request.headers.get("Authorization");

    if (!accessToken?.startsWith("Bearer"))
      throw Response.json(
        { message: "Unauthorized: Invalid Authorization header" },
        { status: 401 },
      );

    let tokenPayload: TokenPayload;
    try {
      tokenPayload = await verifyToken(accessToken.substring(7));
    } catch (error) {
      throw Response.json(
        { message: error instanceof Error ? error.message : "Unauthorized: Invalid access token" },
        { status: 401 },
      );
    }

    const user = buildUser(tokenPayload);

    return next({ context: { user } });
  },
);

const publicAuthenticationMiddleware = createMiddleware().server<{ user: User | null }>(
  async ({ next, request }) => {
    const accessToken = request.headers.get("Authorization");

    if (!accessToken?.startsWith("Bearer")) return next({ context: { user: null } });

    let tokenPayload: TokenPayload;
    try {
      tokenPayload = await verifyToken(accessToken.substring(7));
    } catch (error) {
      throw Response.json(
        { message: error instanceof Error ? error.message : "Unauthorized: Invalid access token" },
        { status: 401 },
      );
    }

    const user = buildUser(tokenPayload);

    return next({ context: { user } });
  },
);

export function authenticationMiddleware(options?: {
  optional?: false;
}): typeof requiredAuthenticationMiddleware;

export function authenticationMiddleware(options: {
  optional: true;
}): typeof publicAuthenticationMiddleware;

export function authenticationMiddleware(options: {
  optional: boolean;
}): typeof requiredAuthenticationMiddleware | typeof publicAuthenticationMiddleware;

export function authenticationMiddleware(options?: { optional?: boolean }) {
  return options?.optional ? publicAuthenticationMiddleware : requiredAuthenticationMiddleware;
}

export const authorizationMiddleware = (permissionKey: keyof typeof permissions) =>
  createMiddleware()
    .middleware([authenticationMiddleware()])
    .server(async ({ next, context }) => {
      if (context.user.hasPermission(permissionKey)) return next();
      throw Response.json(
        {
          message: `Forbidden: User ${context.user.name} is not authorized to access this resource`,
        },
        { status: 403 },
      );
    });

export const serverFnAccessTokenMiddleware = (scopeKey: keyof typeof definedScopes) =>
  createMiddleware({ type: "function" }).client(async ({ next }) => {
    try {
      const accessToken = await getAccessToken(scopeKey);
      return next({
        headers: {
          Authorization: `Bearer ${accessToken}`,
        },
      });
    } catch {
      return next();
    }
  });

async function verifyToken(token: string): Promise<TokenPayload> {
  const { payload } = await jose.jwtVerify(token, getJWKS(), {
    issuer: `https://login.microsoftonline.com/${serverEnv.ENTRA_TENANT_ID}/v2.0`,
    audience: serverEnv.ENTRA_CLIENT_ID,
  });
  return payload as unknown as TokenPayload;
}

let jwksCache: ReturnType<typeof jose.createRemoteJWKSet> | null = null;

function getJWKS() {
  jwksCache ??= jose.createRemoteJWKSet(
    new URL(`https://login.microsoftonline.com/${serverEnv.ENTRA_TENANT_ID}/discovery/v2.0/keys`),
  );
  return jwksCache;
}

And last thing: configuration and helpers

// src/start.ts
export const startInstance = createStart(() => ({
  defaultSsr: false,
  functionMiddleware: [serverFnAccessTokenMiddleware("api")], // serverFn auto-token inject
}));

// utils.ts
export const requirePermission = (permissionKey: keyof typeof permissions) => {
  return async () => {
    const user = await getUser();

    if (!user?.hasPermission(permissionKey))
      throw new Error("You do not have permission to access this page.");

    return { user };
  };
};

And the usage is simple as that

// Using middlewares
const getSecureData = createServerFn({ method: "GET" })
    .middleware([
        authenticationMiddleware(), // Use only if you do not need check permissions
        authorizationMiddleware(["admin"]) // Use when you need to check permissions
    ])
    .handler(() => {
        return { data: "Secret information" };
    });

// Using permissions checks in Route
export const Route = createFileRoute("/")({
  beforeLoad: requirePermission("all"),
});

Known limitation:

• serverFnAccessTokenMiddleware and authenticationMiddleware cannot be applied globally in src/start.ts because they would run during SSR — before the user is initialized. Still looking for a clean workaround.

[iRajatDas]

@DaliborHomola Did you find any workaround?

[DaliborHomola]

Hi, I've managed to check user permission on beforeLoad, but you have to give up the SSR. I'll update the code soon.