SSO Connection widget

Install

pnpm add @authio/widgets react react-dom

1. Mint a widget token from your backend

Call the management-API from your BFF using the same dashboard session JWT you already use for tenant administration. The mint endpoint enforces owner / admin role on the org and clamps ttl_seconds to [60, 3600] (default 1800).

// server-side — never expose this code to the browser
const res = await fetch("https://api.authio.com/v1/widget-tokens", {
  method: "POST",
  headers: {
    authorization: `Bearer ${dashboardSessionJwt}`,
    "x-authio-tenant": tenantId,
    "content-type": "application/json",
  },
  body: JSON.stringify({
    organization_id: "org_abc",
    scope: ["sso_connection"],
    origins: ["https://app.acme.com"],
    ttl_seconds: 1800, // 30 minutes
  }),
});
const { token, expires_at, id } = await res.json();
// Hand `token` to the front-end. `id` lets you revoke it later.

2. Embed the widget

import { AuthioSSOConnectionWidget } from "@authio/widgets";

export function SsoSettingsPage({ widgetToken }: { widgetToken: string }) {
  return (
    <AuthioSSOConnectionWidget
      token={widgetToken}
      organizationId="org_abc"
      onConnectionUpdate={(event) => {
        // Optional. Fires on every load / create / update / delete /
        // test / error so you can mirror the change into your own UI.
        if (event.type === "created") {
          analytics.track("sso_connection_created", { id: event.connection.id });
        }
      }}
    />
  );
}

3. Hand the SP metadata to the IT admin

Inside the widget, the IT admin can click Metadata on any SAML connection to download the SP-side EntityDescriptor XML. They paste this into Okta’s “Service Provider Metadata” field (or equivalent in their IdP), upload their IdP metadata back through Edit, and click Test to fire a round-trip login.

What the widget calls

• GET /widget/sso-connections — list
• POST /widget/sso-connections — create
• PATCH /widget/sso-connections/:id — update
• DELETE /widget/sso-connections/:id — delete
• POST /widget/sso-connections/:id/test — trigger a test login
• GET /widget/sso-connections/:id/metadata — return SP metadata XML

Every call carries the widget JWT in Authorization: Bearer. Origin enforcement happens server-side — see the security page for the threat model.

Imperative mount (non-React)

import { mountSSOConnectionWidget } from "@authio/widgets";

const handle = mountSSOConnectionWidget(
  document.querySelector("#sso-mount")!,
  { token, organizationId: "org_abc" },
);

// later, when the host rotates the JWT:
handle.update({ token: newToken, organizationId: "org_abc" });

// teardown:
handle.unmount();