Sign-in: the coordinator and the directory
Applies to: SimpleTwo 0.9.x, the directory role from 0.83 · Checked: 16.10.2026 against the code
With calendars, distribution groups and contacts merged into the directory role the platform
has two authenticators, and switches in the coordinator's console decide which one acts. This
page is the whole picture; the runbook for the switch itself is
Switching to sign-in through directory.
Two roles
coordinator | directory | |
|---|---|---|
| What it is | the control plane: the fleet, roles and permissions (RBAC), policy, product options, the console | the organisation's directory: accounts, groups and distribution groups, contacts and address books, calendars; SCIM, the LDAP source, the HRMS link |
| In the core | the authenticator: its own sign-in page and the broker to the organisation's identity provider (ADFS, Entra ID, Keycloak); it issues the sessions and tokens every service accepts | the directory: it holds the credentials for the coordinator — guests' passwords, app passwords for mail and CalDAV, the second factor — and verifies them on its request, as AD holds passwords while ADFS signs people in |
| After the switch | keeps the fleet, roles and permissions; leaves the sign-in path once the platform token is switched | the issuer: its own sign-in page — for local accounts and guests the password, an authenticator code, e-mail codes and push approval, for everyone else the broker to the organisation's provider; it issues the platform's tokens |
The organisation's identity provider is an external one: ADFS, Entra ID, Keycloak or SimpleZero ID,
a product of the SimpleZero platform. directory holds the local accounts and the guests — no
external provider knows them, so their password, authenticator code, e-mail codes, push approval
through SimpleTwo Connect and self-service reset are the directory's. Passkeys, OpenID Connect and
SAML for the company's third-party applications and the LDAP server are the provider's, not
SimpleTwo's. The directory brokers sign-in to it and issues the platform token. The role has one
name, dir.<domain>.
The switches
Every switch is in the coordinator's console, Settings. Each refuses to move forward while its conditions are unmet and says what stands in the way; switching back is always allowed.
| # | Where | Switch | Values | What it changes |
|---|---|---|---|---|
| 1 | Settings → the "Sign-in" card (/admin/api/sign-in) | Who runs the sign-in | coordinator · identity | who draws the browser sign-in page: the coordinator's form and its SSO settings, or the directory's page with the second factor and its own brokering to the organisation's provider. The tokens come from the coordinator either way. Conditions: the directory public name answers, the coordinator's public URL is set, and — while the platform token is the coordinator's — the directory's LDAP password pass-through is on if provider accounts exist: until the token switch the apps sign in with a password, and in this mode the coordinator no longer checks it at the provider. On the switch the coordinator registers the client platform on directory. The same card holds the hand-over: the coordinator's SSO settings (issuer, client, secret, claim names, the group → role mapping, sign-in domains) are copied into the directory's upstream, its schema and its role assignments; "Hand over" leaves the upstream off, "Hand over and enable" gives it the sign-in domains — once the provider accepts the directory's redirect URI |
| 2 | the "Sign-in through identity" card | Platform token (platform_token) | hmac · identity | whose token every service accepts: the coordinator's (HMAC over the shared secret) or directory's (signed with its key, with a revocation feed). Conditions: directory's name announced, its issuing on (platform_issuer), keys pinned, the coordinator's public URL set, a break-glass account enrolled, the platform's bots holding directory credentials. Afterwards the console, the web client and the apps sign in through directory, and the coordinator mints no user token |
| 3 | the same card | Service token (service_token) | hmac · keys | what the services sign their calls to each other with: the shared secret or each host's own key |
| 4 | the same card | CalDAV and CardDAV (dav_auth) | calendar · identity | what a calendar or contacts program signs in with: the calendar's device passwords or directory's app passwords alone |
| 5 | the same card | Messaging directory (directory-source) | coordinator · identity | where chat takes people and groups from: the coordinator's directory events or the directory feed, which shows chat the provisioned people only |
Switches 1 and 2 are different things. The first changes only the page: who draws it. The second changes the issuer: after it a person has one session for every service, and sign-out, "that was not me", a password change and a block act everywhere at once. The second runs the sign-in through directory itself, whatever the first says.
Coherent states
| State | Who runs the sign-in | Platform token | What you get |
|---|---|---|---|
| The core | coordinator | hmac | sign-in through the organisation's provider on the coordinator's form; directory is the directory with the calendar |
| The directory's page | identity | hmac | people sign in on the directory's page: local accounts and guests with a password and a second factor, everyone else through the organisation's provider; sessions are still the coordinator's, and one switch rolls back |
| The full switch | either | identity | the directory is the issuer for every service; the console and the clients sign in through it; the coordinator keeps the fleet, roles and permissions. Runbook: Switching to sign-in through directory |
The other three switches (the service token, CalDAV and CardDAV, the messaging directory) do not depend on the first two and move as each service is ready.
Where to look next
- Products — what is in the core and in each product
- Switching to sign-in through directory — the platform token runbook
- Sign-in through the organisation's provider, ADFS
- App passwords, Access to SimpleTwo