Directory sign-in

How people sign in

Cenovel offers three ways to sign in, in this order:

1. Directory sign-in, the default: people type their Active Directory username and password. Cenovel checks them against a domain controller over LDAPS or StartTLS, never plain LDAP, and never stores or logs the password.
2. Sign in with Microsoft, an optional button below the form when Microsoft Entra ID is configured in the deployment.
3. The local recovery account from first boot. It always works, including when the directory is not answering Cenovel, and it never contacts the directory.

Before you start

• A domain controller name that its certificate names, such as dc1.district.org, reachable from the appliance on port 636 (LDAPS) or 389 (StartTLS).
• The PEM certificate of the authority that signed the domain controller’s certificate. Only this authority is trusted, and the check cannot be turned off.
• A service account with read access only. Cenovel uses it to find the person and read their groups.
• One directory group for each tier you want to grant. Nested groups count.

The service account’s password is a file on the server, not a setting. Save it in the deployment’s secrets folder as ldaps_service_password and give it to the console (by default at /run/secrets/ldaps_service_password, or wherever CENOVEL_LDAPS_SERVICE_PASSWORD_FILE points). Cenovel reads it each time it is used, so changing the file needs no restart. It is never shown in the console.

Set it up

1. Sign in as an Administrator EX and open Settings › Access, then Sign-in methods.
2. Fill in the domain controller, the encryption (LDAPS or StartTLS), the port, the base DN (such as DC=district,DC=org), the CA bundle and the service account. The default user filter finds a username or an email-style sign-in name.
3. Under Groups and tiers, give each tier its group’s distinguished name. Someone in several groups gets the highest tier. Someone in none of them cannot sign in; there is no default tier.
4. Choose Test connection. It says whether the certificate was trusted, the service account signed in, and every mapped group was found.
5. Turn directory sign-in on and save. Then sign out, and sign in with a directory account to check.

Departments still come from Settings › People and departments, not from directory groups. While someone is signed in, Cenovel checks their groups again every 5 minutes, so removing them from a group ends their access within minutes.

Authenticator codes

Turn on Require an authenticator code to ask for a 6-digit code after the password. At their first sign-in, each person scans a QR code with an authenticator app and receives ten single-use recovery codes. A code that was used cannot be used again. The authenticator secrets are stored encrypted with the deployment’s settings key, so the option needs that key.

For a lost phone, an Administrator EX types the person’s username under Reset a person’s authenticator; they set up a new one at their next sign-in.

When sign-in is refused

• Every refusal shows the same message, so it never reveals whether an account exists. The audit log records the actual reason.
• After 5 failed attempts for one account within 15 minutes, that account is paused, at first for one minute and then longer. Keep this below the district’s own Active Directory lockout threshold.
• If the directory is not answering Cenovel, directory accounts cannot sign in, and the recovery account still can.

Microsoft sign-in alongside

Microsoft Entra ID sign-in is set in the deployment, not in the console. AZURE_TENANT_ID takes the directory (tenant) ID or one of the tenant’s verified domain names, such as district.org. The multi-tenant names common, organizations and consumers are refused. Each sign-in’s ID token is checked against the tenant’s published keys before anything else is read.

Upgrades and rollback

Directory sign-in arrives with Agate 1.1. Its schema change only adds, so an Agate 1.0.1 image still starts on it until someone signs in through the directory. After that, roll back by restoring the backup taken before the upgrade, which is the standard rollback.

See also: Permissions and departments · Security & data · Upgrades & rollback