---
title: "Organization SSO and Cross-App Federation"
description: "Distinguish organization OIDC or SAML login from cross-app identity federation."
---

# Organization SSO and Cross-App Federation

Organization SSO authenticates a person with their company's OIDC or SAML
identity provider when they sign in to one Agent-Native deployment. Cross-app
federation carries verified identity or organization context between separate
Agent-Native deployments. The two capabilities have different setup, credentials,
and trust boundaries. For organization provider setup, see
[Administered Deployments](/docs/administered-deployments#organization-sso-and-directory-provisioning).
This page describes cross-app federation through the browser, Desktop, and
server-side protocols. For the one-click connection and marketplace direction,
see [Cross-App Connect and the Agent-Native Marketplace](/docs/cross-app-connect-design).

<!-- i18n-copy-ignore: Agent-Native is a proper name. -->

<Callout tone="info">

If all apps share one origin, a shared cookie domain already provides shared
login. No federation is needed.

For configuring an organization's own OIDC or SAML provider, see
[Administered Deployments](/docs/administered-deployments#organization-sso-and-directory-provisioning).

</Callout>

## Cross-app federation

### Packaged Desktop workspace

Workspace sign-in is an explicit action in Desktop Settings. When enabled,
Desktop can provision eligible registered apps through its dedicated broker.
Each target app still owns its local user store, session, and access checks.
Desktop does not intercept anonymous browser navigation to an app sign-in page.

An app is eligible only when all of these are true:

- Desktop enables workspace SSO for the app.
- The production URL is exact HTTPS.
- Dispatch has an exact server-side registration for the app.
- The <code>desktop.workspace-sso</code> rollout flag is enabled.

The per-device <code>desktopSsoEnabled</code> preference is enabled by default.
An explicit false remains an opt-out. If the flag, preference, registration, or
eligibility check is unavailable, ordinary per-app sign-in remains available.

### Server-side federation

Canonical Agent-Native sign-in pages expose an explicit **Continue with
Agent-Native** action. It starts the same short-lived, server-verified protocol
used by broker and server-side callers. A person with an active Dispatch
session can continue; otherwise, Dispatch asks them to authenticate there. On
first use, they may need to establish a Dispatch identity. The target app then
links or creates its local user using the verified email and issues its own
session.

1. The caller requests an exact registered app binding.
2. Dispatch authenticates the workspace identity and returns a short-lived,
   one-time authorization code.
3. The target app server redeems the code with its PKCE verifier.
4. The target app verifies the signed assertion, exact app binding, callback,
   scope, nonce, and expiry.
5. The target app links or creates a local user by verified email and mints its
   normal local session.

The assertion is returned only through the server-to-server exchange. It never
appears in a browser URL and it is not a reusable bearer token.

## Organization federation

The <code>organization.cross-app-federation</code> flag is off by default. When
enabled, the source app registers its local organization with Dispatch and
stores the exact <code>(identity_authority, identity_id)</code> mapping. A
target app accepts the canonical organization ID, name, and verified membership
role only from the server-verified assertion.

Organization names, email domains, and browser cookies are not join keys. An
existing local organization without a mapping remains unchanged until an
explicit migration links it. Linked memberships continue to use the target
app's normal access checks.

Organization federation uses a separate credential for each registered source
app:

- Set <code>AGENT_NATIVE_IDENTITY_FEDERATION_SECRET</code> on the source app.
- Set the matching
  `AGENT_NATIVE_IDENTITY_FEDERATION_SECRET_<NORMALIZED_APP_ID>` on Dispatch.
- Do not reuse <code>A2A_SECRET</code> for this authority boundary.

The app ID suffix replaces every run of non-alphanumeric characters with an
underscore and uppercases the result. For example, the app ID

<code>workspace-reports</code> uses
<code>AGENT_NATIVE_IDENTITY_FEDERATION_SECRET_WORKSPACE_REPORTS</code>.

Identity and organization writes are additive. Existing same-email users are
reused without modification. A new verified email creates a local user.
Disabling federation does not delete users, organizations, memberships, or
credentials.

## Configuration

<code>AGENT_NATIVE_IDENTITY_HUB_URL</code> identifies the hub for the
server-side and browser paths when a self-hosted app needs an explicit Dispatch
deployment. Exact registered first-party apps can show the explicit browser
action. The <code>browser.identity-sso</code> rollout flag controls silent
<code>prompt=none</code> sign-in and post-local-login bootstrap; keep that
automatic path limited to the selected rollout cohort. The local sign-in form
remains available as a fallback.

For a self-hosted Dispatch deployment, register every custom app with its
exact app ID, client ID, HTTPS origin, callback path, and

<code>identity-sso</code> capability through
<code>IDENTITY_SSO_APP_REGISTRY_JSON</code>. An example registration is:

```bash
IDENTITY_SSO_APP_REGISTRY_JSON='[{"appId":"workspace-reports","clientId":"workspace-reports","origin":"https://reports.example.com","callbackPath":"/_agent-native/identity/callback","capabilities":["identity-sso"]}]'
```

Production registrations must use HTTPS and an exact callback path. Localhost
is allowed only for local development. Unknown subdomains, mismatched app IDs,
arbitrary paths, and cross-origin callbacks are rejected.

## Security contract

- One-time codes and PKCE prevent a code from being replayed by another
  client.
- The signed assertion is server-only, short-lived, and scoped to identity.
- Exact app, origin, client, and callback checks prevent token exfiltration.
- Verified email is the only local user join key.
- Exact organization ID is the only organization join key.
- Per-app federation credentials prevent one app from minting another app's
  organization identity.
- Identity and organization writes never rename, repoint, or delete existing
  data.

## Verification and rollback

After deployment:

1. Verify that normal email, password, magic-link, and configured provider
   sign-in continue to work in a browser.
2. With <code>browser.identity-sso</code> off, verify the explicit Continue with
   Agent-Native action and ordinary local sign-in. With it on, verify the silent
   <code>prompt=none</code> probe and local-form fallback without introducing a
   wildcard cookie.
3. If Desktop workspace SSO is enabled, verify one exact registered app from
   the explicit Desktop Settings action.
4. If organization federation is enabled, verify the exact organization ID
   and membership role in the target app.

To roll back the silent browser or Desktop path, disable its feature flag. To
remove the explicit browser action from a self-hosted app, remove

<code>AGENT_NATIVE_IDENTITY_HUB_URL</code> or its exact app registration, then
redeploy. Local sign-in remains available, and additive identity and
organization records remain intact.

## Browser identity SSO rollout runbook

The silent browser path is intentionally a rollout, not a default switch in
core. The explicit Continue with Agent-Native action is available to exact
registered first-party clients and does not enable silent sign-in.
For one canonical `*.agent-native.com` app:

1. Keep `browser.identity-sso` disabled for the general population and enable
   it for one test email or equivalent rollout cohort.
2. Sign in to Dispatch, sign out of the target app, and load the target app.
   Confirm the silent `prompt=none` probe returns the same verified account and
   that the app lands in its normal local session.
3. Repeat with no active hub session. Confirm `login_required` returns to the
   ordinary local sign-in form and the explicit action still lets a person
   authenticate with Dispatch when they choose it.
4. Widen the cohort only after checking that logout and revocation behave as
   expected. The first enablement may require one-time revocation of existing
   sessions so stale local sessions do not mask the probe result.

The probe never changes the verified-email JIT-link rule. Identity-link rows are
append-only, and a wildcard cookie is not part of this rollout.

## Related docs

- [Authentication](/docs/authentication)
- [A2A Protocol](/docs/a2a-protocol)
- [Dispatch](/docs/dispatch)
- [Security & Data Scoping](/docs/security)
- [Multi-App Workspaces](/docs/multi-app-workspace)