Multi-organization sign-in

A Perihelium account is one person across every organization: the same address can be a member of several, with a different role in each. A session, by contrast, always belongs to one organization at a time, because authority is granted per organization. This page explains how the two meet at sign-in, and how a person moves between their organizations without signing in again.

Choosing the organization at sign-in

When your application sends a user to sign in (Log in with Zynth Auth):

1. An organization hint. The authorization request names the organization (tid) when your application knows it — a workspace URL, a stored preference, a tenant your user picked. The user signs in straight into that organization.
2. The chooser. Without a hint, a user who belongs to exactly one organization lands in it; a user with several is shown a chooser listing their memberships and picks one.
3. The token says which. The id_token carries the chosen organization as tid and its slug as tenant_slug, so your application never guesses.

A user who is a member of no organization is refused sign-in to your application with a clear message; membership is the authority, not the account.

Each organization's policy is its own

Entering an organization re-evaluates that organization's policy. One that enforces SSO or MFA cannot be entered on the strength of a session another organization accepted:

• a user whose current session was established with a password is sent to the identity provider when the target organization requires SSO;
• a user without a second factor is challenged when the target organization requires MFA;
• the session lifetime and idle timeout become the target organization's, where it has set them tighter than the platform's.

This is deliberate: an organization's security posture is decided by its administrators, and no other organization's weaker posture can be used to walk around it.

Switching without a full sign-in

A signed-in person can switch to another of their organizations from the account menu or through the API, subject to the same policy re-evaluation — a step-up where the target demands more, and nothing where it does not. The switch:

• ends authority in the organization being left and establishes it in the target;
• is recorded in both organizations' audit logs;
• re-issues tokens for the target organization, so an application holding the old tokens sees them refused rather than silently acting on the wrong organization.

Your application receives the new tid the same way it did at sign-in, through the tokens.

Default installation of an application

An operator can mark a platform application installed by default in the organizations it provisions, so every new organization can sign in to it from day one. Default installation is visible to every organization administrator, recorded in each organization's audit trail, has a fixed scope ceiling, and an organization keeps the right to withdraw it at any time.

For your application

• Read tid from the id_token and userinfo, never from a field the user typed.
• Treat a tid change on refresh as a new session in your own records.
• If your application is itself organization-aware, pass the hint on the authorization request and the chooser is skipped.