@microsoft/rayfin-embed-host
Parent-page SDK reference for brokering external Entra authentication into a Rayfin app embedded in an iframe.
@microsoft/rayfin-embed-host is the parent-page SDK for embedding a Rayfin app in an iframe and brokering its external Entra authentication. The parent portal supplies a delegated Entra token; the iframe receives only a single-use handoff code.
Installation
npm install @microsoft/rayfin-embed-hostThe package declares an exports map; import from @microsoft/rayfin-embed-host only, never from a dist/ path. Changed in 2.0
The embedded Rayfin app needs @microsoft/rayfin-auth-provider-fabric and a client created with browserSession(); see Embed in your own portal.
Exports
export { createEmbedHost };
export { EmbedHostError };
export type {
EmbedHost,
EmbedHostErrorCode,
EmbedHostOptions,
HandoffProvider,
HandoffRequest,
HandoffResult,
};HandoffProvider is a contributor extension seam, not a Builder-facing API.
createEmbedHost
function createEmbedHost(options: EmbedHostOptions): EmbedHost;Registers a message listener in the parent window. Call it before mounting or navigating the Rayfin iframe because the embedded app sends its readiness message once.
import { createEmbedHost } from '@microsoft/rayfin-embed-host';
const host = createEmbedHost({
allowedOrigins: ['https://my-rayfin-app.example.com'],
getAccessToken: () => acquireDelegatedEntraToken(),
});
host.dispose();createEmbedHost() throws a Rayfin SdkError if called outside a browser environment.
EmbedHostOptions
interface EmbedHostOptions {
allowedOrigins: string[];
getAccessToken: () => string | Promise<string>;
handoffProvider?: HandoffProvider;
}| Option | Type | Description |
|---|---|---|
allowedOrigins | string[] | Exact origins of embedded Rayfin apps this host will broker for. The same list gates the iframe sender origin and the return origin bound into the handoff code. |
getAccessToken | () => string | Promise<string> | Returns the parent portal's delegated Entra access token. Called once per handoff request and never cached by the host. |
handoffProvider | HandoffProvider | Internal acquisition seam. Omit in application code. |
Use origins only, such as https://my-rayfin-app.example.com. Do not include paths.
EmbedHost
interface EmbedHost {
dispose(): void;
}dispose() removes the parent-window message listener and stops brokering handoffs. It is idempotent.
Wire protocol behavior
The host handles two message families on channel fabric-auth:
| Message | Direction | Purpose |
|---|---|---|
externalEmbed.ready | iframe to parent | One-shot readiness announcement. |
externalEmbed.ack | parent to iframe | Scenario acknowledgement declaring externalEmbed. |
auth.requestHandoff | iframe to parent | Correlated handoff request with PKCE challenge, return origin, brokered-authorize endpoint, and artifact ID. |
response | parent to iframe | Correlated success or error response. |
The host ignores readiness and handoff messages from origins outside allowedOrigins. Handoff requests must come from the same window and origin that completed readiness.
The embedded app sends externalEmbed.ready only when it has no Fabric embedded hint — the fabricEmbedded option, a ?fabricEmbedded=true URL parameter, or the Fabric flag remembered in its sessionStorage — and it waits 300 ms for externalEmbed.ack. Without an acknowledgement in that window, the app does not use the external embed flow. Changed in 2.0
HandoffRequest and HandoffResult
interface HandoffRequest {
brokeredAuthorizeUrl: string;
artifactId: string;
returnOrigin: string;
codeChallenge: string;
codeChallengeMethod: string;
state?: string;
getAccessToken: () => string | Promise<string>;
}
interface HandoffResult {
handoffCode: string;
state?: string;
}The default provider posts to brokeredAuthorizeUrl with:
Authorization: Bearer <delegated Entra token>x-ms-workload-resource-moniker: <artifactId>- JSON body containing
returnOrigin, PKCE challenge fields, and optionalstate
The delegated token is never sent over postMessage.
EmbedHostError
type EmbedHostErrorCode =
| 'EXCHANGE_NOT_ENABLED'
| 'AUTH_FAILED'
| 'INSUFFICIENT_PERMISSIONS'
| 'NOT_AVAILABLE'
| 'AUTHORIZE_FAILED'
| 'VALIDATION_FAILED';
class EmbedHostError extends SdkError {
readonly code: EmbedHostErrorCode;
}| Code | Meaning |
|---|---|
EXCHANGE_NOT_ENABLED | The target app has not enabled external Entra exchange. |
AUTH_FAILED | The delegated Entra token was rejected. |
INSUFFICIENT_PERMISSIONS | The user lacks Execute permission on the item. |
NOT_AVAILABLE | The brokered-authorize endpoint is unavailable or wrong. |
AUTHORIZE_FAILED | Network failure, malformed response, missing handoff code, or an unrecognized endpoint status. |
VALIDATION_FAILED | The handoff request failed host-side validation before any network call. |
Messages are safe to log and do not include the delegated token or raw response body.
Default error messages
| Code | Message |
|---|---|
VALIDATION_FAILED | returnOrigin is not permitted by the embed host. |
AUTHORIZE_FAILED | Failed to broker the authentication handoff. |
AUTHORIZE_FAILED | Failed to reach the brokered-authorize endpoint. |
AUTHORIZE_FAILED | Brokered-authorize endpoint returned a malformed response. |
AUTHORIZE_FAILED | Brokered-authorize endpoint returned no handoff code. |
EXCHANGE_NOT_ENABLED, AUTH_FAILED, INSUFFICIENT_PERMISSIONS, NOT_AVAILABLE, AUTHORIZE_FAILED | Brokered-authorize endpoint responded with status <status>. |
Browser requirements
This package runs in a parent browser window. It uses window.addEventListener('message', ...), postMessage, and fetch. It is not for Node.js.
@microsoft/rayfin-auth-provider-fabric
Fabric auth provider reference for Fabric SSO, direct Entra token exchange, embedded handoff, external embed support, and sign-in error codes.
@microsoft/rayfin-functions
SDK reference for functionsService, FunctionClient, FunctionsSchema, InvokeOptions, FunctionsError, and typed client.functions invocations.