Company SSO: setup to verified sign-in

Before you begin

You need an owner role, recent sign-in, an identity administrator for your company provider and a platform implementation contact. Administrators can inspect SSO settings; owners prepare and submit the connection.

SSO authenticates a person. It does not automatically provision a ZubLMS membership, grant roles or link accounts by matching email addresses. Arrange approved identity linking and company membership before acceptance testing.

Prepare the connection

1. Open Company settings → Single sign-on and choose Add connection. Give each connection a recognisable name, such as Employees or Partners.
2. Choose SAML 2.0 or OpenID Connect and enter the provider details.
3. Copy this connection’s exact ACS/redirect URI into the provider configuration. Each connection has its own callback; do not reuse another connection’s URL.
4. Optionally enter exact work-email routing domains, one per line. Save the draft, then choose Validate settings.
5. Choose Request activation and arrange the operator review.
6. After activation, choose Test company sign-in with an approved linked account.

Choose a connection without guessing

A company can hold up to 20 independent SAML/OIDC connections. Use the company sign-in chooser at /company-sign-in or share a connection’s exact Test company sign-in link. Display order and names do not make a connection the default.

The application resolves the company from its verified website hostname, or from the current authorised workspace session. A supplied company ID or email address cannot select another tenant. On a shared hostname, sign in normally and switch to your company before testing its provider.

The /auth/company-sso route accepts either connection=<UUID> or domain=<exact-domain>. If both are supplied, or a supplied hint is unknown or disabled, the request is rejected without falling back to another provider. Without either hint, exactly one active connection can start automatically; zero or several return to the chooser.

Routing domains are exact, case-normalised names, not wildcards or email addresses. Each domain is reserved by at most one connection in a company, including drafts and disabled connections. A domain routes a login; it does not prove domain ownership, grant membership or automatically link an identity.

Understand the status

• Draft: details can be prepared and reviewed.
• Validation: checks required fields, public HTTPS endpoints and certificate validity. It does not prove credentials or fetch arbitrary discovery metadata.
• Pending activation: the operator must review ownership, endpoint destinations and the exact configuration revision.
• Active: the reviewed broker connection has been enabled. Other connections are independent.
• Disabling: ZubLMS has blocked new sign-ins immediately; the operator must still confirm Keycloak cleanup. A broker outage keeps this local block in place.
• Disabled: operator cleanup completed. The draft can be revised and revalidated; its routing domains stay reserved until explicitly removed.
• Verified sign-in: a successful company-provider callback matched the expected connection and revision. A normal password sign-in is not evidence of this test.

Changes and recovery

Pending or active configurations are frozen. Ask the operator to disable the connection before preparing a reviewed replacement. Blank secret fields on edit preserve the encrypted stored secret.

For a transition, prepare a separately named replacement connection, activate it and test approved accounts using its explicit link. Keep the working connection available until the replacement is verified. To reuse a routing domain, block and finish disabling its previous connection, clear that domain from the disabled draft, then configure and activate the replacement. This domain cutover may need a planned interruption; there is no hidden default or automatic fallback.

After a connection has been activated, its protocol, issuer/entity ID and OIDC client ID are fixed to protect existing federated identity links. Use a new connection for another provider or identity namespace. Credentials and certificates for the same identity can be rotated through the disabled-draft review workflow.

Owners can choose Block this connection to stop new sign-ins locally. The operator uses the exact company UUID, connection UUID and current revision to finish disablement. Existing LMS sessions require separate incident revocation when needed. Save or discard a draft before switching connection cards.

Normal sign-in remains available. SSO enforcement, automatic account linking, SCIM provisioning and upstream logout propagation are not enabled by this setup. Disabling a connection blocks new broker logins but does not itself revoke existing LMS sessions.