Security
Single sign on
If your organization already runs an identity provider, use it. Then the provider's lockout, its second factor and, most importantly, its leaver process actually apply here too.
Three modes, and the order matters
| Mode | What it means |
|---|---|
| Local accounts only | Usernames and passwords kept here, each with a second factor. Every install starts here and there is nothing wrong with staying. |
| Local accounts or single sign on | Both offered on the login page. Use this while you test the provider, because if the provider is wrong you still have your password. |
| Single sign on only | Local passwords stop working entirely. This is where you want to end up, because otherwise the provider's rules do not really apply. |
Why the third mode is refused until somebody has used the second
Turning local passwords off is the only setting on that page that can leave nobody able to sign in, and it fails quietly: the page saves, and the next person to open the login screen finds neither route works.
So the software wants evidence rather than intention, and the only evidence worth having is a completed login. An account gets an OIDC subject on it the first time somebody actually signs in that way, and that is what is being counted.
Groups decide the role
Name a group for admin, one for operator and one for viewer. Highest wins, so somebody in the admin group and the viewer group is an admin, which means adding a person to the admin group works without having to take them out of anything first.
Somebody in none of the three groups cannot sign in at all. That is how access is taken away: remove them at the provider and they are out of every node at once.
What you need
| Field | What to put |
|---|---|
| Discovery URL | The .well-known/openid-configuration address. Everything else is read from there rather than typed in. |
| Client id | From your provider. |
| Client secret | Encrypted at rest and never sent back to the page, so the box is always empty. Saving it empty keeps what is stored. |
| Redirect address | The outside address of this GUI including any prefix. /auth/oidc/callback is added, and that whole address has to be registered with the provider. |
| Groups claim | Which claim holds the group names. Read from the id token, and from the userinfo endpoint when the token does not carry it. |
There is a Test button for the discovery URL, and it is worth using before you rely on any of this.
The way back in
If the provider stops answering
Run ./auth-recovery.sh --allow-local from the install directory on any node in the fleet and local passwords come straight back. It needs a shell on the box, which is the point: the way back in must not depend on the thing that broke.
Where the settings live
In the database, not the environment, so a change applies at the next sign in with nothing restarted and travels to the other nodes with the config. That matters because it means the standby can sign people in on the day it is promoted, rather than needing a file edit first.
Common questions
Which providers work?
Anything that speaks OpenID Connect with PKCE. Entra ID, Okta, Keycloak, Authentik, Google Workspace and Auth0 are all standard OIDC.
Do single sign on users still need a code from an app?
That is the provider's decision, not this software's. If your provider requires a second factor, they will be asked for one there.
Can I keep one local break glass account?
The middle mode does exactly that. Whether you stay there is a judgment call: it is one more way in, which is useful in a crisis and is also one more way in.
Step by step instructions
The how to section has searchable, task shaped answers. Search it for single sign on.