Sign in through a central identity provider

This page is for administrators planning to let users sign in to Workspace through an upstream OpenID Connect (OIDC) provider. The provider confirms the user's identity. Each Workspace installation still decides which tenants and features that user may access.

The capability is off by default. Only the System Tenant can enable it for an individual target tenant. Configuration does not activate any other tenant and is not by itself approval for production use.

For example, an employee may be a regular user in one installation and a tenant administrator in another. Central sign-in does not add that employee to any other customer tenants.

To let other applications use Workspace as their provider instead, see Use Workspace as an identity provider.

Enablement and prerequisites

Only the System Tenant can enable auth.upstream_oidc_login for an individual tenant. The capability is off by default. Ordinary tenant administrators cannot enable it themselves, and the System Tenant remains local-login-only. The separate identity_provider.sso capability does not enable upstream login.

Before configuration, arrange:

  • An active, verified HTTPS domain for the target tenant's administration interface. Register the exact connection-specific callback derived from that domain with the provider.
  • A supported Workspace, Microsoft Entra, or Google provider profile and a dedicated client registration.
  • A client secret in the tenant's secret store if required by the profile. Do not copy secrets into tickets or agent prompts.
  • Operator-approved outbound HTTPS access to the provider. Permissions for other integrations do not automatically allow this traffic.
  • A tested local emergency account with the required permissions and a second factor that does not depend on the upstream provider.

Start sign-in on the target tenant's canonical administration domain. Additional domains of the same tenant are not alternative callback addresses. If the canonical domain changes or loses active verification, pending sign-ins cannot complete. Update the provider registration first, then start a new sign-in. The global server address does not replace the tenant's domain.

Manage connections and access policies

In the target tenant, open Sign-in > OIDC connections. Viewing this page requires federation_connections:list and federation_connections:read. Creating, changing, and deleting connections require the corresponding federation_connections:create, federation_connections:update, and federation_connections:delete scopes.

Select the provider profile and enter the name, issuer, client ID, secret reference, activation status, and session lifetime. The API field sessionLifetimeSeconds defaults to eight hours and cannot exceed the installation maximum of 24 hours. Workspace derives the callback, front-channel logout, and back-channel logout URIs from the verified administration domain. These fields are read-only.

Then open Sign-in > Access policies. Viewing policies requires federation_policies:list and federation_policies:read; changes use the corresponding create, update, or delete scopes. Each policy binds a connection, an organization, and an allow or deny decision. Set includeDescendants only when the policy must include suborganizations. An optional shorter sessionLifetimeSeconds only shortens sessions in that scope.

The connection is saved when it remains listed with the selected status after a reload and its derived endpoints remain unchanged. The setup is functionally verified when an explicitly assigned test account completes sign-in, reaches the intended tenant, and sees only its local roles and organizations. Also test a denied policy and a tenant without capability enablement.

Connect two Workspace installations

Setup requires authorized administrators on both sides. The source tenant operates the identity provider; the target tenant uses it for sign-in. They may belong to different installations. The following procedure is manual, not an automatic link between the two systems.

The source issuer is https://<source-host>/api/v1/idp/oidc/tenants/<source-tenant-id>. Use the exact value published in the source tenant's discovery document.

  1. Check the separate capabilities: identity_provider.sso at the source and auth.upstream_oidc_login at the target. Agree on the source tenant, target tenant, exact issuer, client ID, and a stable application key for the source registration.
  2. Save an inactive target connection with that issuer and client ID. Then read its server-derived callback URI. Do not invent or edit this URI.
  3. Register the source OIDC client under the agreed application key with the exact client ID and callback URI. Also check source membership and application entitlement for the intended users. The target connection does not grant those permissions.
  4. Generate the source client secret once and transfer it through an approved secure channel. Store it in the target tenant's secret store and assign its reference to the connection. The source will not return the plaintext secret again later.
  5. Compare tenants, issuer, client ID, and callback URI on both sides. Only then activate the target connection and verify sign-in and local rights with an explicitly enrolled test account.

Status reads do not create or rotate a secret. Reuse the same application key when repeating client configuration. If secret delivery is uncertain, deactivate the target connection and perform a controlled rotation and new handoff. Plan for an interruption; simultaneous validity of two secrets is not guaranteed. Saving one side does not automatically verify the other installation's configuration.

Bind people and access rights

External identities are matched by the exact pair of issuer and subject. Matching email addresses do not link accounts. Provider roles and groups do not grant local administrative privileges.

Create the person in the target tenant before issuing a new OIDC invitation. The invitation explicitly binds that person to a provider connection and, optionally, an organization in the same tenant. Existing password invitations remain password invitations. Sending another invitation does not silently replace an existing account's verified contact.

Email lookup does not choose an existing account or create an alternative identity for it. Linking another provider account requires fresh proof of ownership of the existing account followed by authentication with the new provider. An existing signed-in browser session is not sufficient on its own.

Organization rules initially cover only the selected organization. Including suborganizations requires an explicit subtree rule. The nearest rule takes precedence, and access is denied without a matching allowance. An individual grant cannot override an applicable organization denial. Organization hierarchies do not create membership in other tenants.

After successful provider proof, Workspace derives the eligible local contexts again. It uses a sole context automatically. If several contexts are eligible, you explicitly choose between personal access and the offered organizations. Workspace rechecks membership and the nearest applicable policy before issuing the session. Organization data is not shown before provider proof.

Browser, nucli, and local passwords

Browser sign-in offers the connections available to the target tenant. Any required local second factor still applies. Switching tenants checks membership and authorization in the destination again.

Use --browser to start the anonymous browser handoff explicitly. Naked nucli login selects that handoff only when public discovery publishes the global auth.upstream_oidc_login implementation signal. That signal does not prove that the current tenant enabled federation or offers a connection. Use --local to select the local password flow explicitly:

bash
nucli --host <workspace-url> login --browser
nucli --host <workspace-url> login --local --email <email>
nucli skills show oidc-login-federation

Without an interactive terminal, nucli does not open a browser. It prints a short-lived verification URL and pairing code and then waits for approval. Treat the URL as sensitive and do not put it in logs or tickets. Use --tenant-id <tenant-id> to reject an unexpected target tenant; the option does not create membership. After login, run nucli whoami --json to verify the stored session and active tenant. Older servers without the implementation signal retain their existing local default; a failed discovery request is reported as an error.

Adding a local password to an OIDC-only account is a separate process: fresh authentication through the existing link, any required local second factor, and an additional confirmation code sent to the stored verified contact. An email address already reserved for a password credential can prevent this optional step. That collision alone does not block OIDC sign-in or an explicit person-bound OIDC invitation.

Password setup does not take over another credential, weaken a second factor, or automatically create a local session. Existing password recovery remains limited to accounts with a local password credential. Password changes are not allowed while impersonating another user.

Outages, revocation, and verification

Test the local emergency account before relying on the upstream provider. A provider outage must not disable local sign-in. Keep this access available after configuration.

Revoking a connection, capability, or applicable access rule must prevent its sessions from regaining access through renewal or a tenant switch. Provider-triggered logout depends on the provider's supported logout contract; immediate global logout through Google is not guaranteed.

Before production use, verify browser and nucli sign-in, different local roles, an excluded suborganization, a customer tenant without enablement, and local login while the provider is unavailable. Successful authentication alone does not prove correct authorization.

Next steps