auth.group.sso.connection

The auth.group.sso.connection namespace manages group SSO records. Each record links a group (tenant) to an identity provider configuration. It is also the root namespace for group connection domain management through auth.group.sso.connection.domain.*. The returned connectionId is passed to the rest of the group SSO APIs.

This page documents the server-side helper API: auth.group.sso.connection.*. If you want client-callable admin RPC like api.auth.group.createConnection, expose app-owned group SSO wrappers first.

Methods

Method	Signature	Returns	Description
create	(ctx, { groupId, slug?, name?, status?, domains?, ... })	{ connectionId, groupId }	Creates a new SSO connection for a group.
get	(ctx, connectionId)	Doc \| null	Fetches a connection by ID.
getByDomain	(ctx, domain)	Doc \| null	Looks up a connection by email domain.
list	(ctx, { where?, limit?, cursor?, orderBy?, order? })	Paginated list	Lists SSO connections with optional filtering and sorting.
update	(ctx, connectionId, data)	{ connectionId }	Updates connection fields (status, metadata, domains, etc.).
delete	(ctx, connectionId)	{ connectionId }	Deletes an SSO connection.
status	(ctx, connectionId)	Status object	Returns readiness and per-protocol status for the connection.

Domain methods

The auth.group.sso.connection.domain namespace manages domains owned by the connection.

Method	Signature	Returns	Description
list	(ctx, connectionId)	Domain list	Lists domains attached to the connection.
status	(ctx, connectionId)	Onboarding status	Returns trust status, pending challenges, warnings, and recommended next steps.
validate	(ctx, connectionId)	Status info	Returns onboarding diagnostics for domains.
set	(ctx, connectionId, domains)	{ connectionId, domains }	Replaces the connection’s full domain set and returns the canonical result.
verification.request	(ctx, { connectionId, domain })	Verification challenge	Issues a DNS TXT verification challenge for an attached domain.
verification.confirm	(ctx, { connectionId, domain })	Confirmation result	Resolves the TXT record and marks the domain verified on success.

Example

// Create an SSO connection for a tenant
const { connectionId } = await auth.group.sso.connection.create(ctx, {
  groupId: orgId,
  slug: "acme",
  name: "Acme SSO",
  status: "active",
});

// Replace the attached group connection domains
const domainResult = await auth.group.sso.connection.domain.set(ctx, connectionId, [
  { domain: "acme.com", isPrimary: true },
  { domain: "login.acme.com" },
]);

const challenge = await auth.group.sso.connection.domain.verification.request(ctx, {
  connectionId,
  domain: "acme.com",
});

const confirmation = await auth.group.sso.connection.domain.verification.confirm(ctx, {
  connectionId,
  domain: "acme.com",
});

const domains = await auth.group.sso.connection.domain.list(ctx, connectionId);

const domainStatus = await auth.group.sso.connection.domain.status(ctx, connectionId);

// Inspect domain onboarding readiness
const diagnostics = await auth.group.sso.connection.domain.validate(ctx, connectionId);

// Check connection health
const status = await auth.group.sso.connection.status(ctx, connectionId);

Trust semantics

Verified domains establish trusted ownership for a connection.

• domain-based SSO discovery should rely on verified domains
• primary-domain verification is the clearest signal that a connection is ready
• automatic account linking is only safe when your linking policy allows it and the connection has verified domain ownership

Use domain.status(...) when building onboarding UIs. It returns the current primary domain, verified domains, pending DNS challenges, warnings, and the next recommended admin steps.

verification.request(...) also acts as the renewal path for expired TXT challenges.