How do you set up single sign-on for self-hosted AI agents?
An OIDC app, a DNS proof for the e-mail domain, binding existing accounts, and what happens to passwords once an organisation requires single sign-on.
A company's staff sign in to Keycloak, in the realm acme. Nobody there wants to keep a second password just for the AI agents. Getting there means creating an OIDC app at the provider, registering a redirect address with it, copying the app's values into the platform and deciding which role a person gets on their first sign-in. That leaves the harder part: which addresses the provider may speak for, and what happens to the passwords that already exist.
In covey, the organisation's org admin sets this up. Password sign-in is built in, using JWT and Argon2id. Single sign-on is added as an OIDC connection in which covey is the client and the provider is the server: Keycloak, Entra ID, Google or Okta, for example.
Three values and a redirect address make the connection
The org admin first enters the issuer URL, in the example https://login.example.org/realms/acme. Then come the app's client ID and client secret, and the role for new people. On saving, covey fetches the issuer's discovery document, so a wrong issuer fails right there with the provider's reason. The secret is stored encrypted in the database. When the settings are changed later, its field can stay empty and covey keeps the stored value, as long as the client ID stays the same.
The settings page shows the redirect address to register with the provider. It is the installation's site address plus the path /api/sso/callback, so it needs COVEY_SITE_URL or the site.url setting to be set. If the provider reports an error on the way back, or redeeming the code, checking the ID token or matching the account fails after that, the last error and its time appear on the same page, because the server log is out of the org admin's reach. If the provider cannot be reached when the sign-in starts, the flow cookie is missing or the state does not match, the error goes to the server log only.
The provider speaks only for verified domains
A configured provider signs nobody in yet. The organisation also claims its e-mail domain, example.org in the example, and covey hands out a token starting with covey-. That token goes into DNS as a TXT record at _covey-challenge.example.org, and covey looks it up when asked to check. A domain another organisation has already claimed is refused.
This check protects the accounts of other organisations on the same installation. If the provider signs in an address outside the verified domains, covey aborts the sign-in, so no organisation's provider can take over accounts in somebody else's domain. Where the DNS record is slow to arrive, only a system admin of the installation may confirm the domain by hand, and covey records that it happened and who did it.
The first sign-in binds an existing account
The sign-in page asks for the e-mail address first and offers single sign-on to every address in example.org. The round trip to the provider uses PKCE, a nonce and a sealed cookie that binds the callback to the same browser and expires after ten minutes. covey reads the address from the ID token. If the provider states outright that it has not verified the address, covey refuses the sign-in.
If j.berg@example.org already has an account with a password, covey binds that account to the provider identity on the first sign-in, meaning issuer and subject. Later sign-ins find the account through that binding, even if the address has since changed at the provider. Someone without an account gets one with no password, plus a seat in the organisation with the configured role.
Requiring single sign-on deletes those accounts' passwords
As long as single sign-on is only offered, everyone can still sign in with their password. The org admin can require it only once the acting account has itself signed in through the provider, since otherwise nobody knows the route works. The switch asks for confirmation and then reports how many accounts were converted, if there were any.
Turning it on removes the covey password from every account in the verified domains. Reset links already mailed stop working, and open sessions end, except the acting admin's. covey then refuses password sign-in, reset and change for those addresses. The installation's system admins keep their passwords, so access to the installation stays open through those accounts even when the provider is down.
The interface states the cost itself: whoever loses the company account loses access to covey too.
That is the intended effect when someone leaves, but it also ties sign-in for everyone at example.org to the provider being reachable. If the requirement is switched off later, nobody gets their old password back; each person has to request a new one through a reset.