Skip to main content
With single sign-on, people sign in with your OpenID Connect provider, and Lumovi acts as them in the cluster. It does that in one of two ways:
  • 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.
The Lumovi sign-in page with one button, Sign in with single sign-on, which names your provider when you give its name.The Lumovi sign-in page with one button, Sign in with single sign-on, which names your provider when you give its name.

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 client-secret, in Lumovi’s namespace:
Or set 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.
Lumovi drops any slash at the end of issuer, and the ID token’s iss claim must then match it exactly. A provider whose issuer ends in a slash (the issuer in its discovery document, like https://login.example.com/) can’t sign people in to Lumovi. Signing in ends with Signing in didn’t work. The Lumovi server’s log says why., and the log says which issuer the ID token is from.
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

Add offline_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.
Without a refresh token, people’s groups stay as they were when they signed in, until the session ends (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.Read to 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.com and sts.windows.net). For a national cloud, set Graph’s address with auth.oidc.graphUrl (LUMOVI_OIDC_GRAPH_URL), like https://graph.microsoft.us. With any other issuer, unless auth.oidc.graphUrl is 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.
This has been tried against a stand-in for Graph, not yet against an Entra ID tenant.

Impersonation

When Lumovi impersonates people, the chart gives its service account permission to impersonate users and groups, cluster-wide: a ClusterRole with impersonate 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 get and patch on 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 exp claim, 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. Use id instead.
  • 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.usernameClaim claim. Lumovi shows that name, and the groups in auth.oidc.groupsClaim, in its account menu and its log. And it still refuses a name that starts with system: once auth.usernamePrefix is 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_access is 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 than auth.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.usernameClaim and auth.oidc.groupsClaim, with auth.usernamePrefix and auth.groupsPrefix before 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 with forwardToken: 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 groups decide 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.