- It impersonates them (the default). Its service account sends their user name and groups in impersonation headers, and the API server applies their RBAC. This works with any cluster.
- It passes their own token on, when the API server already trusts your provider. Its service account then needs no permissions, and the cluster’s audit log names each person directly. See When the API server trusts the provider.


Signing in with single sign-on.
Set it up
You need Lumovi at an address of its own (see Give Lumovi an address): the provider sends people back there after they sign in.1
Register Lumovi with your provider
Add Lumovi as a web application (an OpenID Connect client using the authorization code flow), with this redirect URI:That’s the origin of your
url (its scheme and host), then basePath, then auth/callback. A path in url itself isn’t used, so below a path, with basePath: /lumovi, it’s https://tools.example.com/lumovi/auth/callback.Note the client ID and, if the provider gives one, the client secret. Lumovi uses PKCE, so a public client without a secret works too. With a secret, Lumovi sends it to the provider’s token endpoint with HTTP Basic authentication (client_secret_basic), or in the request body (client_secret_post) when the provider’s discovery document lists the methods it takes and Basic isn’t one of them.Make sure the ID token carries the person’s email address and their groups. Many providers include groups only when asked: with a groups scope, or a setting on the client.2
Store the client secret
Put the secret in a Secret, under the key Or set
client-secret, in Lumovi’s namespace:auth.oidc.clientSecret, and the chart makes that Secret for you. It names it after the release, with -oidc at the end: lumovi-oidc here. So don’t give a Secret of your own that name: if you switch to clientSecret later, the upgrade fails, as the chart can’t make its Secret under a name that’s taken. Leave both empty for a public client.3
Configure Lumovi
values.yaml
issuer is the provider’s issuer URL, where /.well-known/openid-configuration is. Then upgrade the chart with these values.4
Give people roles
People are named by the ID token’s
email claim, and their groups come from its groups claim. Bind roles to those names, with the prefixes you chose:5
Sign in
Open Lumovi and choose Sign in with Dex (or your provider’s name). After signing in at the provider, you’re back where you started, seeing what your own access allows.
Who people are
Prefixes keep your provider’s names apart from the cluster’s own. Without one, a provider group with the same name as one of your groups would get its permissions.
Lumovi never acts as one of Kubernetes’ own users or groups (
system:…), whatever the provider says. It leaves out groups whose names start with system:, and refuses a user whose name does, with Lumovi won’t act as this account: names starting with system: are Kubernetes’ own.
Groups that follow the provider
Addoffline_access to the scopes (most providers give a refresh token only then), and people’s groups stay as the provider says they are, for as long as they’re signed in:
values.yaml
- Asked again before each ID token expires. A minute before, Lumovi asks the provider again with the person’s refresh token, and checks the new ID token as it did at sign-in: signed by the provider, for Lumovi, in date, and about the same person, under the same name. Their groups are read from it by the same rules, and apply from their next request.
- A change is recorded. Groups added or taken away are in the audit log, as Groups changed, and in Lumovi’s log:
alice@example.com’s groups changed as the provider renewed their sign-in: +platform, −on-call. - Someone the provider won’t renew is signed out at once: disabled, removed, or signed out at the provider. So is a renewal that doesn’t check out.
- A provider that can’t be reached is asked again, more slowly each time, up to once a minute. If it hasn’t answered by the time the last ID token expires, the session ends.
- A provider that renews without a new ID token (some never send one then) says nothing new of anyone’s groups. They hold until the last ID token expires, and then the session ends, and Lumovi’s log says so once.
- After a restart, a session whose last ID token expired while Lumovi was stopped has no groups until the provider answers, and it’s asked at once.
- Signing out lets go of the refresh token at the provider, where its discovery document has a
revocation_endpoint. That’s never waited for, and a failure is only logged.
auth.sessionHours).
The refresh token is kept as the person’s own token is: in memory, and sealed for a restart, with a key only their browser’s cookie gives. Lumovi sends it only to the token endpoint and revocation endpoint the issuer’s discovery document names, over HTTPS when the issuer is, and never logs it, nor what the provider says back beyond its status and error code.
Microsoft Entra ID and many groups
When someone is in more than 200 groups, Microsoft Entra ID puts none in their ID token, only a mark that there are too many to list. Lumovi then reads them from Microsoft Graph, as that person, at sign-in and at each renewal:- Grant User.Read. Give Lumovi’s app registration Microsoft Graph’s delegated User.Read permission, and add
User.Readto the scopes. It’s the least Graph needs to list someone’s own memberships, and reads nobody else’s. - Security groups, by ID. Graph gives the security groups the person is in, directly or through other groups, by object ID, as the ID token names them. Microsoft 365 groups aren’t among them. Bind roles to those IDs.
- Their own token. Lumovi asks Graph with the access token the person signed in with. Where that token is for something else, like the cluster, it asks the provider for one for Graph, with their refresh token.
- Only Microsoft Graph. Lumovi reads groups there for Entra ID’s global issuers (
login.microsoftonline.comandsts.windows.net). For a national cloud, set Graph’s address withauth.oidc.graphUrl(LUMOVI_OIDC_GRAPH_URL), likehttps://graph.microsoft.us. With any other issuer, unlessauth.oidc.graphUrlis set, groups put outside the ID token aren’t read: those people have none, and the log says why. Lumovi never follows an address the token itself gives. - None, rather than old ones. Where Graph can’t be read, the person has no groups, not the ones they had. Their account menu says “Lumovi couldn’t read your groups, so you’re signed in without them and may be able to do less than usual. If this stays, ask whoever runs Lumovi: its server’s log says why.” The log says why.
Impersonation
When Lumovi impersonates people, the chart gives its service account permission to impersonate users and groups, cluster-wide: a ClusterRole withimpersonate on users and groups, bound to it. That’s a powerful permission. Read Security before you turn this on, and keep Lumovi in a namespace only cluster administrators can exec into.
If you’d rather manage that RBAC yourself, set rbac.create: false and bind the service account an equivalent role.
When the API server trusts the provider
If the API server already accepts your provider’s tokens (through its--oidc-* flags, a structured authentication configuration, or a managed equivalent such as EKS’s OIDC identity providers), Lumovi can pass each person’s own token on instead of impersonating them.
values.yaml
- No impersonation. Lumovi’s service account needs no permissions in the cluster, and the chart gives it none: only
getandpatchon a few objects of its own in its namespace, like the Secret that keeps sessions across restarts. - The token must be a JWT that says when it expires, in its
expclaim, so Lumovi knows when to renew it. ID tokens always are. Some providers’ access tokens aren’t: with one of those, signing in ends with Signing in didn’t work. The Lumovi server’s log says why. Useidinstead. - Names in RBAC come from the API server. The cluster checks the token itself, so the names and groups it applies RBAC to, and their prefixes, come from the API server’s own settings, not Lumovi’s. Bind roles to the names the cluster sees.
- Some things still come from Lumovi’s settings. The ID token still has to carry the
auth.oidc.usernameClaimclaim. Lumovi shows that name, and the groups inauth.oidc.groupsClaim, in its account menu and its log. And it still refuses a name that starts withsystem:onceauth.usernamePrefixis put before it. - Tokens are renewed. Lumovi renews each person’s token a minute before it expires, with the refresh token the provider gives it, as it renews their groups. Most providers give one only when
offline_accessis among the scopes. Without one, the session ends when the cluster stops accepting the token, and people sign in again. A provider that refuses ends the session at once, and so does a renewal with no access token in it. One that can’t be reached is asked again until the token expires. Either way, a session lasts no longer thanauth.sessionHours. - A restart signs nobody out. Lumovi keeps each person’s token and refresh token sealed, with a key only their browser’s cookie gives, and unseals them when the browser next asks for something; it renews the token from then on. Their AI assistants wait for that. If Lumovi was down for longer than a token lasts, the first page someone opens can fail once while it’s renewed: reload it. There’s one exception, with a provider that gives a new refresh token at each renewal and refuses the old one: a token renewed in the moment Lumovi stops, or just before it dies, can be lost before it’s kept, and that person signs in again after the restart. See Across restarts.
- The audit log names people directly, instead of Lumovi’s service account acting as them.
In a fleet
A fleet signs people in the same way, once, for all its clusters. Set it up as above, then:- Lumovi impersonates people in each cluster, with the credentials it has for that cluster. The chart lets its own service account impersonate only in the cluster it runs in, when that’s one of the fleet’s.
- Each cluster where Lumovi impersonates people sees the same names, from
auth.oidc.usernameClaimandauth.oidc.groupsClaim, withauth.usernamePrefixandauth.groupsPrefixbefore them, unless the cluster has its own. Bind roles in each cluster to the names it sees. - Tokens are passed on cluster by cluster. With
auth.oidc.forwardToken, Lumovi keeps each person’s token and renews it, but passes it on only to clusters withforwardToken: true, which name people by their API server’s own settings. It impersonates people in the others, and always in the cluster it runs in. - A cluster that refuses the token says Unauthorized on its card, and the session goes on: the other clusters still work. It ends when the provider won’t renew the token, or can’t be reached before it expires, or after
auth.sessionHours. - A cluster’s
groupsdecide who sees it: groups as the ID token has them, without prefixes.
When signing in doesn’t work
The sign-in page says what happened. The details go to Lumovi’s log (kubectl logs --namespace lumovi deployment/lumovi).
Signed in, two more things can happen:
Security
What impersonation means, and how to keep Lumovi contained.
Helm values
Every sign-in setting.