Operator SSO

Operator SSO lets the people who manage an Account sign in through your organization’s OpenID Connect identity provider. Each Account can have one active Operator SSO provider, configured independently from the provider used by Users to connect accounts and approve agent access. Using the same provider or email for both sign-ins does not merge the identities or their authority.

Prepare management access

Configure SSO as an Operator administrator, or through a Service Account with operators:write. Reads of the configuration require an Operator management session or the operators:read permission; browser mutations also require Operator CSRF protection. Keep a working password-based administrator available for recovery, because an SSO configuration or identity-provider outage should not be your only path back into management.

Before enabling SSO, restrict assignment to the identity provider’s management application. A first eligible sign-in creates a Viewer with Account-wide read access, so application assignment is an admission control rather than merely a convenience for showing a login button. Neither group claims nor other token claims promote the new Operator to administrator.

Register the identity-provider application

Read the Account’s configuration to obtain the server-owned callback and sign-in addresses:

GET /api/v1/ws/acme/operator-sso

Use the response’s redirect_uri as the identity provider’s registered redirect URI. It is derived from the Axec API’s public base URL and ends in /auth/management/oidc/callback; for a deployment at https://axec.dev, it is https://axec.dev/auth/management/oidc/callback. Use the returned value rather than constructing it yourself, particularly if the deployment has a URL prefix.

Register an OpenID Connect client with the provider, then obtain its issuer URL, client ID, and client secret. The management API discovers the authorization, token, and signing-key endpoints from the issuer and uses the openid, profile, and email scopes with RS256 signing. Endpoint URLs, scopes, algorithms, and the callback are not editable fields on this API.

Enable SSO

Submit the provider configuration through the authenticated management API, replacing the example identity-provider values and supplying the secret securely:

PATCH /api/v1/ws/acme/operator-sso
Content-Type: application/json

{
  "enabled": true,
  "issuer": "https://idp.example.com",
  "client_id": "axec-management",
  "client_secret": "<client-secret>"
}

Axec validates issuer discovery and stores the configuration without returning the client secret in subsequent reads. Open the response’s initiate_login_uri in a separate browser session to test management sign-in while preserving your recovery session.

An unknown issuer-and-subject identity with a valid, available email enrolls as a Viewer without creating a User or password credential. An existing binding signs in as the same Operator and retains its current role and profile. Disabled Operators, revoked identity bindings, and email collisions are denied rather than automatically linked or reactivated; an administrator must explicitly link an existing Operator using the configured issuer and the exact subject for this OIDC client, not an assumed email address.

Maintain roles and recovery access

An administrator can change an Operator’s role, profile, status, or password while SSO is enabled. Manual creation of new password-based Operators is blocked while SSO is enabled, so create any additional recovery Operator before enabling it, or temporarily disable SSO for that task. Existing password sign-in remains available.

To disable SSO, submit {"enabled": false} to the same PATCH endpoint. Operator SSO configuration changes do not change User OIDC configuration or User sessions, and signing in as an Operator supplies no User Connection, consent, or review assignment. For automated administration, see Service Accounts and the management SDK reference.