@microsoft/rayfin-auth-provider-fabric

@microsoft/rayfin-auth-provider-fabric signs Rayfin users in with Microsoft Entra ID. Browser helpers broker through Fabric SSO. signInWithEntraToken() exchanges an existing delegated Entra token directly in browsers or Node.js. New in 1.36

The package operates on an Auth instance from @microsoft/rayfin-auth.

Installation

npm install @microsoft/rayfin-auth-provider-fabric @microsoft/rayfin-auth @microsoft/rayfin-lib

Where each flow works

Popup and embedded Fabric SSO require a Rayfin backend deployed to Fabric. The popup flow works from any origin listed in allowedRedirectUris. The embedded Fabric flow requires the app to be loaded inside a Fabric iframe.

Exports

export type { FabricAuthOptions };
export type { EntraTokenSignInOptions };
export { bridgeFabricCallback };
export { embeddedFabricLogin };
export { ensureSignedInWithFabric };
export { initEmbeddedAuth };
export { initiateFabricLogin };
export { requestHandoff };
export { signInWithBrokeredToken, signInWithEntraToken };

The public root can be imported in Node.js. Browser broker helpers still require browser APIs such as window.open(), postMessage, BroadcastChannel, and window.location.

FabricAuthOptions

interface FabricAuthOptions {
  workspaceId: string;
  projectId: string;
  fabricPortalUrl: string;
  returnOrigin: string;
  callbackUrl?: string;
  fabricEmbedded?: boolean;
}

ensureSignedInWithFabric

function ensureSignedInWithFabric(
  auth: Auth,
  options: FabricAuthOptions
): Promise<OpaqueSession>;

Browser-only primary entry point for Fabric SSO. It runs a waterfall where the first successful step short-circuits the rest:

1. Return a safe existing session.
2. Try auth.refreshSession() if a refresh token exists.
3. Use embedded postMessage handoff if Fabric embedded mode or external-embed classification applies. Changed in 1.36
4. Open the Fabric broker popup.

Step 4 calls window.open(). Call this function directly from a user gesture.

import { RayfinClient } from '@microsoft/rayfin-client';
import { ensureSignedInWithFabric } from '@microsoft/rayfin-auth-provider-fabric';

const client = new RayfinClient({
  baseUrl: import.meta.env.VITE_RAYFIN_API_URL,
  publishableKey: import.meta.env.VITE_RAYFIN_PUBLISHABLE_KEY,
});

document.querySelector('#sign-in')?.addEventListener('click', async () => {
  const session = await ensureSignedInWithFabric(client.auth, {
    workspaceId: import.meta.env.VITE_FABRIC_WORKSPACE_ID,
    projectId: import.meta.env.VITE_FABRIC_ITEM_ID,
    fabricPortalUrl: import.meta.env.VITE_FABRIC_PORTAL_URL,
    returnOrigin: window.location.origin,
  });

  console.log('Signed in:', session.user?.email);
});

initEmbeddedAuth

function initEmbeddedAuth(
  auth: Auth,
  options: FabricAuthOptions
): Promise<OpaqueSession | null>;

Browser-only startup helper. It never opens a popup. It first runs the one-shot external-embed classification handshake, then proceeds when either a third-party parent acknowledges that scenario or Fabric embedded mode is detected. Changed in 1.36

It returns null when no embedded scenario applies. Await it before trusting a stored session in iframe scenarios.

import { initEmbeddedAuth } from '@microsoft/rayfin-auth-provider-fabric';

const session = await initEmbeddedAuth(client.auth, fabricOptions);
if (session) {
  console.log('Embedded session established:', session.user?.email);
}

initiateFabricLogin

function initiateFabricLogin(auth: Auth, options: FabricAuthOptions): Promise<void>;

Low-level popup helper used by ensureSignedInWithFabric(). It opens the broker, sends the PKCE challenge after brokeredAuth.ready, receives brokeredAuth.handoff, exchanges the handoff code, and installs the session. Most apps should use ensureSignedInWithFabric() instead.

signInWithEntraToken

interface EntraTokenSignInOptions {
  entraToken: string;
}

function signInWithEntraToken(
  auth: Auth,
  options: EntraTokenSignInOptions
): Promise<OpaqueSession>;

Exchanges an existing delegated Entra token for a Rayfin session. It works in browsers and Node.js and does not require FabricAuthOptions, a popup, or an iframe. New in 1.36

The Auth instance's ApiClient must point at an absolute HTTPS AppBackend workload API base URL. The helper resolves /api/auth/v1/brokered/token against that base and rejects URLs with credentials, query strings, fragments, whitespace, backslashes, or non-HTTPS protocols.

import { Auth } from '@microsoft/rayfin-auth';
import { ApiClient } from '@microsoft/rayfin-lib';
import { signInWithEntraToken } from '@microsoft/rayfin-auth-provider-fabric';

const apiClient = new ApiClient({
  baseUrl: process.env.RAYFIN_API_URL!,
  publishableKey: process.env.RAYFIN_PUBLISHABLE_KEY!,
});

const auth = new Auth(apiClient, { storage: false });
auth.attachToClient(apiClient);

try {
  const session = await signInWithEntraToken(auth, {
    entraToken: process.env.ENTRA_ACCESS_TOKEN!,
  });
  console.log('Authenticated:', session.isAuthenticated);
} finally {
  auth.destroy();
}

signInWithBrokeredToken

function signInWithBrokeredToken(
  auth: Auth,
  tokenResponse: TokenResponse
): Promise<OpaqueSession>;

Installs a token response that was already obtained from POST /api/auth/v1/brokered/token by a trusted caller. It performs no network request. Prefer signInWithEntraToken() when the caller has the raw Entra token and an HTTPS-reachable backend. New in 1.36

The local development adapter uses this helper to install a token response obtained through the developer's rayfin login session.

Embedded transport helpers

function embeddedFabricLogin(auth: Auth, options: FabricAuthOptions): Promise<void>;

function requestHandoff(params: {
  callbackUrl: string;
  codeChallenge: string;
  codeChallengeMethod: string;
  state: string;
  timeoutMs?: number;
  brokeredAuthorizeUrl?: string;
  artifactId?: string;
  targetOrigin?: string;
}): Promise<{ handoffCode: string; state: string }>;

These are low-level browser helpers. In external embed mode, embeddedFabricLogin() adds brokeredAuthorizeUrl, artifactId, and a pinned targetOrigin to the handoff request. Normal Fabric embedded payloads remain unchanged. Changed in 1.36

Most applications should call initEmbeddedAuth() rather than these helpers directly.

bridgeFabricCallback

function bridgeFabricCallback(): boolean;

Legacy callback bridge for Fabric portals that redirect the popup to an app callback page. It forwards any Fabric handoff parameters found in the URL back to the opener window and closes the popup. Modern Fabric broker handoff uses postMessage.

Environment variables

rayfin dev and rayfin up write the Fabric coordinates needed for FabricAuthOptions. For Vite apps, framework environment generation maps them to these names:

See Fabric SSO and rayfin.yml auth configuration.

Direct token exchange errors

signInWithEntraToken() throws AuthError with these stable codes:

Browser broker errors

Troubleshooting

See Errors and troubleshooting for the full site-wide index.

Security notes

• Popup and embedded Fabric SSO use PKCE S256 and state nonces.
• The PKCE verifier stays in memory and is not persisted to localStorage.
• Popup origin checks are advisory because the Fabric extension frame can differ from the portal origin; state plus PKCE are the enforcement boundary.
• Normal Fabric embedded handoff does not set fabricPortalUrl as targetOrigin; external embed handoff uses the parent origin pinned by classification. Changed in 1.36
• Direct token exchange never stores the supplied Entra token and sanitizes exchange errors.

Runtime requirements

The package root and signInWithEntraToken() can run in Node.js without browser globals. Use memory-only or custom storage outside a browser.

The popup, iframe, and legacy callback helpers are browser-only. They depend on browser APIs such as window.open(), postMessage, BroadcastChannel, and window.location.