Sign-in methods
Settings → Sign-in (organization owner only, marked Global) holds every way people sign in:
- Local passwords — accounts with a password stored in CertAutoPilot.
- LDAP — accounts checked against your directory (LDAP).
- SSO providers — any number of OpenID Connect, SAML 2.0 and GitHub providers, set up from a catalogue of provider types (SSO providers).
Each method can be turned on and off on its own. The page also holds the two-factor policy.
One account, one sign-in method
Every account signs in through exactly one method, recorded on the account: local, LDAP, or one SSO provider.
- Accounts are never merged, not by username and not by e-mail address. An SSO sign-in whose username already belongs to another account (in any letter case) is refused with username conflict; nothing is attached to the existing account.
- The password form only signs in local and LDAP accounts. An SSO account typing a password is refused with the usual "invalid username or password" (the audit entry gives the reason).
- A name that does not exist yet is tried against LDAP when LDAP is on, as before.
- Only a local account has a password and profile managed in CertAutoPilot. For LDAP and SSO accounts, password reset, password change and profile edits are refused — those live in the directory or the identity provider.
To change an account's method, an owner moves it.
Public URL
SSO addresses are built from the Public URL setting — the address people open, for example https://cap.example.com — never from the request's Host header. Set it before enabling a provider.
- It is
http(s)://host[:port]with no path. - OpenID Connect and GitHub need https; plain http is accepted only for
localhost/ a loopback address (a local test installation). - SAML always needs https: the identity provider posts the answer from its own site, so the cookie that ties the sign-in to your browser must be
SameSite=None; Secure, which browsers accept only over https.
A sign-in started at another address of the same installation — an IP address, a node port, a second DNS name — is first sent to the public URL and starts there, because the identity provider always returns to the public URL and the browser keeps the sign-in's cookie per address.
Behind a reverse proxy or load balancer:
- The browser and the identity provider must reach the API at the public URL itself. A split setup where the UI and the API are on different origins (the Helm chart's
frontend.backendUrl) does not work with SSO. - When TLS ends at a proxy in front of the bundled nginx, set
server.secure_cookies: true(see Configuration) so session cookies are marked Secure. SAML's own sign-in cookie is always Secure. - Sign-in requests are rate-limited per client address (starting a sign-in and each answer from the identity provider: 300 per minute per address, enough for an organization behind one NAT address). With a second proxy in front of the bundled one, add it to
server.trusted_proxiesand keep the header it sets inserver.remote_ip_headers, or every user shares one address and one limit.
Changing the public URL changes every address registered at your identity providers; update them there too. While a provider is enabled, the public URL cannot be cleared or set to an address that provider cannot use (http outside localhost, or http at all with a SAML provider) — disable the provider first.
Turning local and LDAP sign-in off
- Password sign-in for local accounts off: local accounts can no longer sign in — except organization owners with a local password (break-glass, so an identity-provider outage never locks you out).
- LDAP sign-in off: LDAP accounts can no longer sign in. The LDAP configuration is kept.
- An active session of an account whose method was turned off ends at its next token refresh (within 15 minutes).
- A change that would leave no active organization owner able to sign in — with a local password, or through LDAP while it is on — is refused (
NO_REACHABLE_OWNER). The same rule guards removing such an owner: demoting, deactivating, deleting or moving the last one is refused. SSO owners do not count: an identity-provider outage would lock them out. Two owners changing each other at the same moment are handled one after the other (the second sees the first's result; if they collide it is asked to try again). When no owner can sign in already, the settings stay editable so that local sign-in can be turned back on. Turning local or LDAP sign-in off and enabling an SSO provider also need every running CertAutoPilot node to be on 1.6.5 or later (CLUSTER_UPGRADE_REQUIRED), because an older node would ignore the switch.
The sign-in page
- Every enabled provider with Show a button gets a button.
- When a provider lists e-mail domains that lead here, the page offers Sign in with your work e-mail: an address in one of those domains goes straight to that provider. The page never lists the domains. One domain can lead to only one provider.
- When neither local nor LDAP sign-in is on, the username/password form is hidden behind an Owner sign-in link.
- A failed SSO sign-in comes back to the sign-in page with a short reason (expired or started in another browser, refused by a restriction, username conflict, no account, deactivated or locked account, provider turned off, answer could not be verified). Several sign-ins can run in one browser at once (two tabs, an owner's test sign-in): each has its own short-lived binding cookie (
__Host-prefixed over https, so a sibling subdomain cannot plant one; at most 5 open at a time). A test sign-in that fails before it could be recorded shows its reason on the page you land on. The details are in the audit log (AUTH_SSO_FAILED, with the reason).
What happens at an SSO sign-in
- The button opens
/api/v1/auth/sso/<slug>/start, which sends the browser to the identity provider.- OIDC and GitHub use the authorization code flow with PKCE (S256), a random
stateand (OIDC) anonce. - SAML sends a signed or unsigned AuthnRequest over the HTTP-Redirect binding.
- A short-lived browser-binding cookie of its own (
cap_sso_<hash>,__Host-cap_sso_<hash>over https) ties the answer to the browser that started it.
- OIDC and GitHub use the authorization code flow with PKCE (S256), a random
- The provider answers at the callback (OIDC, GitHub) or the assertion consumer service (SAML). The answer is checked strictly — see SSO providers → What is checked.
- The provider's restrictions are applied (allowed tenants, Google Workspace domains, GitHub organizations, verified e-mail domains).
- The account is found by the provider's stable identity (never by e-mail or a name):
- an account already linked to this identity signs in (it must be active and still use this provider);
- otherwise an account an owner moved to this provider and that is still waiting is linked — only when its username matches (ASCII letter case ignored) and the provider sends a verified e-mail address equal to the account's;
- otherwise, with Create an account at the first sign-in on, a new account is created with the username from the provider (lower-cased and Unicode-normalized; a name with invisible characters is refused) and the Role of a new account (Viewer on every project, or None — the account then has only what its groups give);
- otherwise the sign-in is refused (no account).
- E-mail and display name are updated from the provider at every sign-in. The username is never changed afterwards.
- Group memberships are synced (below).
- If the account enabled two-factor authentication, or the provider requires CertAutoPilot's two-factor authentication, the usual OTP step follows (below).
- The session starts and the browser opens the dashboard. (A link to
…/startmay carryreturn_to, a path inside CertAutoPilot to open instead; anything else is ignored.)
Open providers. At Google, GitHub, Auth0 and a multi-tenant Microsoft Entra ID, anyone with an account there can authenticate. For these, automatic account creation needs at least one restriction; saving without one is refused.
Groups
With Sync group memberships on, every sign-in reads the groups the provider sends (the groups claim or SAML attribute) and makes the account's memberships through this provider match them. Membership is defined on Settings → Groups: each group has a field per provider listing the provider's group values that lead to it.
- Members added by hand, and memberships from LDAP or another provider, are never touched.
- When the provider sends no group claim or attribute, the user is in no group there: identity providers (Entra ID, AD FS, Keycloak) leave the claim out then. The memberships this provider added are removed — leaving the last group at the IdP ends the access it gave here.
- Only when the provider says the list is incomplete (Microsoft Entra ID's group overage, past 200 groups in a token or 150 in a SAML assertion), or sends values that are not text, are the memberships left unchanged for that sign-in (a warning is logged). CertAutoPilot does not query Microsoft Graph or other directory APIs.
- Microsoft Entra ID sends group object IDs, not names — link the IDs.
Two-factor authentication
- An SSO account that enabled two-factor authentication in its profile is always asked for its code (an account moved to SSO keeps its 2FA).
- Require CertAutoPilot's two-factor authentication (per provider, default off — multi-factor authentication is normally the identity provider's job) makes the two-factor policy apply to all of that provider's accounts: with the policy Required an account without 2FA sets it up first.
- The login lockout applies to SSO accounts too: wrong codes count, and a locked account is refused at the SSO sign-in until the lockout ends.
Sessions
An SSO account gets a normal CertAutoPilot session (15-minute access tokens), but it lasts at most Session lifetime (hours) of its provider (default 12, 1–720) from the sign-in at the identity provider — refreshing does not extend it. After that the user signs in at the provider again, so a user disabled there, removed from an allowed tenant / organization / domain, or removed from a group loses the access here within that time. At each refresh the session also ends (within 15 minutes) when:
- its provider was disabled or deleted, or local / LDAP sign-in was turned off (for LDAP also by clearing its host) — turning the provider on again does not bring those sessions back;
- the provider was changed after the session's sign-in started — a change of how sign-ins are judged (restrictions, account and group settings, claims, protocol settings, the client secret, the session lifetime); a rename, the button, the e-mail routing or enabling the provider do not end sessions. A sign-in that was at the identity provider while such a change was saved is refused too (start it again).
When a session ends this way — or an owner moved the account to another sign-in method, deactivated it or reset its password — the sign-in page says so ("Your session ended: sign in again"). A short database error during the refresh check — reading the session, the account or its roles — keeps the session (the client retries) instead of signing the user out.
Local and LDAP sessions keep the 7-day refresh.
Signing out at the identity provider
Per provider, Sign out at the identity provider too (default off). After the CertAutoPilot sign-out the browser continues to the provider:
- OIDC — the provider's
end_session_endpointwith the account's last ID token asid_token_hint(stored encrypted) and<public URL>/loginas the post-logout address. Register that address at the provider. - SAML — a LogoutRequest signed with the service-provider key over the HTTP-Redirect binding, sent to the provider's single logout service (from its metadata, or the Single logout URL of a provider entered by hand). The provider answers at
<public URL>/api/v1/auth/sso/<slug>/slo, which returns to the sign-in page; this address is in the service-provider metadata while the option is on. The option needs a single logout service (HTTP-Redirect). - Not available for Google (no sign-out endpoint), Google Workspace SAML (no single logout service) and GitHub.
- The CertAutoPilot session ends first. When the provider cannot be reached within 3 seconds (its sign-out address is read from its discovery document or metadata), the browser just returns to the sign-in page.
Sign-out started at the identity provider (IdP-initiated single logout) is not supported: a LogoutRequest arriving at the single logout address is refused. The CertAutoPilot session then runs until its session lifetime ends.
Moving an account to another method
Settings → Users → Change the sign-in method (owner). Roles, resource grants and group memberships added by hand stay; group memberships the old method added are removed (below); the old password, LDAP link or SSO identity is removed and the account's sessions end.
- Local password — a new password is required.
- LDAP — the account signs in with its directory password from then on. Refused while LDAP is not configured. The directory may spell the name in another letter case (AD JSmith for jsmith): the first directory sign-in reaches the moved account and takes the directory's spelling; two moved accounts that differ only in case are refused until one is renamed.
- SSO — choose the provider. With the provider's identity (the stable ID shown by a test sign-in), the account is linked at once. Without it, the account waits up to 7 days for its first sign-in through that provider with the same username (ASCII letter case ignored) and a verified e-mail address equal to the account's — which links it, even when automatic account creation is off. The username alone is never enough, because many providers let their users choose it; an account without an e-mail address can only be linked by giving the identity. A test sign-in shows would link the waiting account when both match.
- The group memberships the old method added (LDAP, or the old provider) are removed; memberships added by hand stay. The new method adds its own at the first sign-in.
- A sign-in half-way through the account's old method (waiting for its two-factor code) cannot finish after the move, and a sign-in that was at the identity provider while the account was moved is refused.
- You cannot move your own account. Moving an organization owner away from its method is refused (
NO_REACHABLE_OWNER) when no other active owner could still sign in — with a local password, or through LDAP while it is on. A move to local, or to LDAP while LDAP is configured and on, keeps the owner able to sign in and is never refused for this. - Every move is audited (
USER_SIGN_IN_METHOD_CHANGED).
Deleting a provider
Disabling a provider is always allowed (a provider set up from a metadata URL is saved without fetching the metadata again while the URL is unchanged, so this also works while the identity provider is down). Deleting it is refused while accounts use it — linked ones and ones still waiting after a move — move or delete them first. An account bound to the provider while it was being deleted puts it back (refused, PROVIDER_IN_USE). Deleting a provider removes its group mappings and the memberships it gave.
Audit
| Action | When |
|---|---|
AUTH_LOGIN | A successful sign-in (SSO sign-ins carry the provider; account_created on a first sign-in). |
AUTH_SSO_FAILED | A refused SSO sign-in, with the reason. |
AUTH_SSO_DISCOVERED | The e-mail routing on the sign-in page found a provider. |
AUTH_REFRESH_REFUSED | A session ended at refresh because its sign-in method is no longer available. |
SIGN_IN_SETTINGS_UPDATED | The public URL or a local / LDAP switch changed. |
SIGN_IN_PROVIDER_CREATED / _UPDATED / _DELETED | Provider changes; an update records each changed setting (old → new). Secrets are never written to the audit. |
SIGN_IN_PROVIDER_TESTED / _METADATA_READ | Test connection, SAML metadata preview. |
SIGN_IN_PROVIDER_LOGIN_TEST_STARTED / _LOGIN_TESTED | A test sign-in started / finished. |
SSO_SP_CERTIFICATE_PREPARED / _SWITCHED | SAML service-provider certificate rotation. |
USER_SIGN_IN_METHOD_CHANGED | An account was moved to another method (with the previous method and provider). |
GROUP_MEMBERSHIP_SYNCED | A sign-in changed group memberships. |
SSO failures never count towards the password lockout.
Locked out
If no owner can sign in (the identity provider is down and every owner signs in through it, or an owner's password is lost), recover on the server with the command line:
cap user reset-password --username <owner> --password-stdin --make-local --enable-local-sign-in
--make-localturns an LDAP or SSO account into a local password account (its LDAP link, SSO identity and the group memberships they added are removed; roles stay; the account is re-activated).--enable-local-sign-inturns password sign-in for local accounts back on.- Every reset also ends a login lockout of the account.
Encryption
Client secrets, SAML service-provider private keys and the ID tokens kept for signing out are envelope-encrypted under your KEK and covered by key rotation and field binding.
Rolling upgrade
While any running node is older than 1.6.5, turning local or LDAP sign-in off and enabling an SSO provider are refused (CLUSTER_UPGRADE_REQUIRED): an older node behind the load balancer would ignore the switch and answer the SSO addresses with "not found". Finish the upgrade before moving accounts to an SSO provider: an older node still lets an owner set a password on such an account, and its sign-in would then skip the identity provider on that node. The checks see only nodes that are running: do not bring a 1.6.4 node back once these features are in use. While old and new nodes run side by side, a session refreshed on an old node starts its SSO session lifetime again, and an old node reports a session an owner ended as token reuse (it then ends the user's other sessions too). A two-factor code is single-use only on 1.6.5 nodes, and a session an old node refreshes is treated as a new sign-in, so it survives a later move or password reset whose session revoke failed. A KEK rotation is refused until every node is on 1.6.5 (an older node does not rotate the new encrypted collections); do not run kek remove from a 1.6.4 binary.
Going back to 1.6.4 after using these features:
- SSO accounts cannot sign in until an owner sets them a password (they then sign in as local accounts).
- Local and LDAP sign-in are on again for everyone.
- A group with an SSO mapping cannot be saved until that mapping is removed; memberships an SSO provider added stay and keep their roles.
- The LDAP bind password must be entered again.
Video tutorial
Short, hands-on videos showing this feature working for real. English audio, English and Turkish subtitles. All video tutorials →