Identity sources and sign-in security

This topic is for platform administrators and unit (tenant) administrators. It covers handing sign-in to an enterprise identity source, tightening sign-in security policy, and recovering an account that has lost its authenticator device.

1. Root first sign-in

When install finishes, the installer prints the console URL, username root, and the initial password in the terminal. The initial password is stored only on the deploy host. Before it is changed, you can view it again on the deploy host:

sudo zenova root-password show

First-sign-in flow:

1. On the sign-in page enter root and the initial password.
2. The sign-in page switches to Change your initial password: set a new password that meets the rules listed on the page.
3. When the platform-scope security policy has Require two-step verification on, the sign-in page switches to Set up two-factor authentication: choose Authenticator app or Passkey. When choosing an authenticator app, scan the QR code with a phone authenticator, enter the 6-digit code, save the recovery codes the page shows, and click I have saved them. When it is off, skip this step.
4. Enter the platform admin console.

A fresh install does not require two-factor authentication at the platform scope by default, and root goes straight to the platform admin console after changing the password. When the customer's security requirements call for it, root first binds two-factor authentication under Account security in personal settings and signs in again with it, then turns on platform-scope Require two-step verification per section 4.

After the initial password is changed, zenova root-password show can no longer show the password, and the initial-password file on the deploy host is deleted at the same time.

Each step has a time limit: changing the initial password and binding two-factor authentication each 10 minutes; entering the second factor 5 minutes. After timeout the sign-in page returns to the first screen and reports that verification timed out; sign in again.

2. Root password or two-factor device lost

When root forgets the password, or root's authenticator and recovery codes are both lost, recovery is only on the deploy host. The admin console provides no entry to reset root:

sudo zenova root-password set

The command talks to the platform database directly and, in one operation:

• Generates a new 32-character random initial password and prints it in the terminal (afterwards you can also view it again with zenova root-password show);
• Requires root to change the password on the next sign-in;
• Clears root's authenticator, recovery codes, trusted devices, and passkeys;
• Invalidates every root session;
• Writes an audit record (including the hostname that ran the command).

Then sign in with the new password per section 1, change the password again; when platform-scope Require two-step verification is on, also bind two-factor authentication again. When the database is unreachable the command errors and exits.

The command reads deployment configuration from this host's install directory by default. When the install directory is not at the default location, pass --install-dir <directory> or --env-file <file>.

3. Connect an enterprise OIDC identity source

Entry: admin console Single sign-on page → choose IAM → type OpenID Connect.

1. Fill in Identity-source address (Issuer) and click Read configuration. The platform reads the identity source's discovery document (/.well-known/openid-configuration) and read-only displays the recognized sign-in URL and token URL. On a read failure, the reason is shown under the field, for example the address cannot be reached, or the returned Issuer does not match what was filled in.
2. Register the Callback URL the page shows in the identity source, then fill in Client ID, Client Secret, and Display name.
3. Fill in as needed:
   • Account-alias claim: claim name in the identity-source token used to match an existing platform account;
   • Default workspace: workspace that auto-provisioned new users join. When the unit has only one workspace, no choice is needed;
   • Allow JIT auto-provisioning: the first sign-in of a user who does not exist on the platform creates an account automatically;
   • MFA source: This platform supplies two-factor authentication (default), or Trust the identity source's MFA result — the latter requires Allowed acr values or Allowed amr values (by default mfa, otp, hwk, swk, fpt, face are accepted).
4. Click Save, then Test sign-in, and complete one sign-in with a test account in the identity source.
5. After a successful test sign-in, identity-source status shows Verified. Only then can you Enable. Saving without a completed test sign-in reports "save and finish a test sign-in before enabling this identity source".

After changing identity-source type, Issuer, Client ID, or Client Secret, Verified status is lost. A test sign-in is required again before enable. Changing default workspace, display name, and similar other fields does not affect verified status.

After save, the page shows Unit sign-in URL (looks like https://<platform-url>/login?org=<unit-slug>). Give it to employees: opening it shows this unit's sign-in methods directly.

The identity source's signing public keys and discovery document are read by the platform on save, then refreshed every hour. Employee sign-in no longer hits the identity source's discovery URL.

3.1 Allow business systems to call models with an identity-source token

In the Business-system calls block on the same page, turn the switch on and fill in Business-system client IDs (at least one, at most 32). The audience of the user token the business system obtains from the identity source must be one of them. The page also shows Business-system call URL, to give to business-system developers. How to call is in the Call models with enterprise identity topic.

3.2 Platform-level identity source

A platform administrator can configure separate SSO for platform accounts. Entry: platform-state Single sign-on page. Only OpenID Connect is provided. Configuration steps are the same as section 3, with these differences:

• No auto-provisioning: only already-created platform accounts can sign in through platform SSO;
• On first sign-in, association is automatic by the verified email the identity source returns and the platform account;
• Business-system calls and default workspace are not provided.

After save the page shows Platform sign-in URL.

4. Sign-in security policy

Entry: for unit state, Admin Console → System Settings → Global settings → Account & session security → Security policy. For platform state, Admin Console → Platform accounts & sign-in → Sign-in sessions → Security policy. Changes in platform state apply to platform accounts and root. Changes in unit state apply to this unit's members.

When opening the Security policy dialog, if identity verification of this session is older than 10 minutes, Verify identity appears first. Follow the prompt and enter a password, a verification code, use a passkey, or re-verify through the identity source.

4.1 Sign-in methods

Platform-scope Allow password sign-in is fixed on: root can only sign in with a password. Whether a platform account can only use SSO is decided by that account's sign-in method (see section 6).

Platform-scope Require two-step verification is switched on or off per the customer's security requirements, at Platform accounts & sign-in → Sign-in sessions → Security policy → Require two-step verification. It applies to root and all platform accounts:

• On: follow section 4.2; root and platform accounts that have not bound two-factor authentication must bind it at their next sign-in.
• Off: an unbound account enters right after entering the password; an account that has bound two-factor authentication still has to complete it when signing in with a password, except on a valid trusted device.

4.2 Turn on required two-factor authentication

1. Turn on Require two-step verification and save. On save the platform checks: the current administrator has already bound two-factor authentication, and this session signed in through two-factor authentication. Otherwise save fails with "bind two-factor authentication for yourself first, and sign in with two-factor authentication before turning this on".
2. After it takes effect, an unbound user on the next sign-in, after password, passkey, or SSO succeeds, enters Set up two-factor authentication and may choose an authenticator app or a passkey (a passkey appears only on HTTPS access when the browser supports it).
3. A user who is already signed in but whose current session has not passed two-factor authentication is asked to sign in again at the next session renewal (at most one access-token lifetime). The sign-in page reports that the unit has enabled two-factor authentication; sign in again and finish binding.
4. The Two-factor authentication column in the member list shows each person's binding status, so administrators can follow up unbound people.

Users who sign in through SSO: when Require two-step verification is off, no local two-factor authentication is added. When it is on, if the identity source is configured as Trust the identity source's MFA result and the token declared an acceptable acr or amr, they are treated as having completed two-factor authentication; otherwise this platform supplies two-factor authentication.

4.3 Turn off password sign-in (SSO only)

To keep everyone from being locked out after it is turned off, on save the platform checks:

After it takes effect:

• When a user of this unit enters the correct password, the page reports that their unit only allows sign-in through SSO. A wrong password still reports a unified "account or password is incorrect" and does not reveal whether the account exists;
• Sessions that signed in with a password are asked to sign in again at the next renewal;
• The self-registration entry is hidden;
• While password sign-in is off, the last enabled identity source cannot be disabled or deleted.

4.4 Password policy

Password policy applies only to passwords set afterwards. Existing passwords are not retroactively checked. Every UI that sets a password — register, forgot password, change password, administrator reset, activate account, and root first-sign-in password change — lists the current rules under the password box. After submit, rules that are not met are marked one by one.

4.5 Sign-in failure limits

After 10 consecutive failures from the same source address against the same account within 15 minutes, or 100 cumulative failures from the same source address against any account within 15 minutes, sign-in attempts from that source are temporarily refused. The limit is counted only by source address. Another person's failed attempts cannot lock an account (including root). Password, second factor, first-sign-in password change, activation, and SSO callback share the same counters.

5. Reset two-factor authentication for someone else

When a user loses the authenticator and has no recovery codes, an administrator resets:

Reset removes the other party's authenticator, recovery codes, trusted devices, and passkeys, and invalidates all of their sessions. On their next sign-in they re-bind per policy. Before the action, identity verification must have been completed within 10 minutes; otherwise Verify identity appears first. An administrator cannot reset their own two-factor authentication in the list; manage it in personal settings.

When the user still holds a recovery code, they can sign in with it at the second-factor step, then re-bind under Account security in personal settings.

6. Platform accounts and activation links

A platform account is a platform administrator's personal account, used for one-person-one-account audit and management. When no platform account is created, the platform is managed by root.

Entry: platform-state Members › Accounts → Create account. Fill in name and email, and choose a sign-in method:

• Password sign-in: after create, the dialog shows a one-time activation link, valid 24 hours. Send the link to that person: they open it and set a password; when platform-scope Require two-step verification is on, they also bind two-factor authentication.
• SSO only: selectable only when a platform-level identity source is already enabled; otherwise the option is unavailable and a reason is shown. After create there is no activation link. On first sign-in through platform SSO they are associated automatically by verified email.

Account status is Pending activation, Activated, or Disabled. After the activation link expires, opening it reports that the link is invalid. The administrator Regenerate activation link in the row actions; the old link is then void.

Other row actions include disable, enable, delete, and grant or revoke platform administrator. You cannot disable or delete yourself. root does not appear in the account list and cannot be disabled or deleted.

7. Scheduled directory sync

The Directory sync cards for DingTalk, LDAP, Feishu, and WeCom provide Automatic sync:

1. Turn on Enable automatic sync, choose 15 minutes, 1 hour, 6 hours, or daily under Sync interval, and click Save settings. After changing the interval or turning it on again, the next sync is counted from save time.
2. The card shows Last run, Next sync, and Consecutive failures. When it is off it shows Not enabled.
3. Scheduled sync and manual sync have the same result: a hit on a large-batch delete also enters pending approval. The card reports a sync waiting for approval; the administrator can approve or reject.
4. On sync failure, the card shows the last failure reason and waits for the next interval. Consecutive failures do not automatically turn automatic sync off; an administrator can turn it off by hand.

Users who entered the platform through directory sync can, after signing in once through the identity source or after association is completed by a push, call models with an enterprise-identity token (see the Call models with enterprise identity topic).

8. Authenticator-code prompts and server-time offset

An authenticator app generates a code every 30 seconds from phone time. The platform checks it against server time. When the two clocks differ:

1. When binding an authenticator, the platform recognizes the code within 5 minutes either side, remembers the offset between this authenticator and the server, and later sign-ins check against that offset. Each successful sign-in remeasures it. When the offset reaches about 1 minute, the save-recovery-codes page reports that server time differs from the authenticator by about N seconds. Binding itself has already succeeded.
2. When the offset is outside the checkable range, the page reports that the code differs from server time by about N seconds. It does not only report that the code is incorrect. First confirm the phone clock is accurate (turn on automatic time). When the phone clock is correct, deployment operations calibrate server time.
3. The same code can be used only once. Submitting it again is refused.

When server time is not synchronized with a time source, or two-factor authentication measures a server-time offset of 60 seconds, the operations-alerts page shows System time not synchronized or Two-factor authentication measured a server-time offset. Calibrate time on the server with:

sudo systemctl restart chronyd && sudo chronyc makestep && sudo chronyc waitsync 30

When the intranet has no usable NTP server, first specify a time source in /etc/chrony.conf with server <intranet-NTP-address> iburst. After calibration, already-bound authenticators do not need to be rebound.