Skip to main content
An authenticating proxy, like oauth2-proxy or Pomerium, signs people in and names them in request headers. Lumovi reads those headers on every request and acts as whoever they name, impersonating them in the cluster so their RBAC applies. Use this when you already sign people in to internal tools with a proxy, or your provider isn’t one Lumovi can talk to directly.
Lumovi trusts the proxy’s headers completely. Anyone who can reach Lumovi without going through the proxy can name themselves anyone. Make sure nothing but the proxy can reach it.

Set it up

1

Put the proxy in front of Lumovi

Point your proxy at the lumovi Service, port 80, and have it pass on who signed in, and their groups. The proxy must pass WebSockets through: each page keeps one open.With oauth2-proxy, --pass-user-headers sends the person’s email address in X-Forwarded-Email, and their groups in X-Forwarded-Groups.If the proxy sends Lumovi a different Host header than the address people open (the Service’s name, say), also set url to that address. Lumovi accepts pages’ connections only from its own origin, and url tells it which that is. See Security.
2

Configure Lumovi, and keep everything else out

values.yaml
With auth.mode: proxy, the chart always makes a NetworkPolicy that lets only networkPolicy.from reach Lumovi, whatever networkPolicy.enabled says, and from is required: name the proxy’s pods. Without it, helm install fails:
(It names the header in auth.proxy.userHeader.) A podSelector on its own matches pods in Lumovi’s namespace, so this works when the proxy runs there too; for a proxy in another namespace, see below. Leave the chart’s ingress off: your ingress sends people to the proxy, and the proxy sends them on to Lumovi.
A NetworkPolicy holds only where the cluster’s network plugin enforces them. Most do, like Calico, Cilium, and the cloud providers’ own; flannel alone doesn’t. Check that yours does: otherwise anything that reaches Lumovi can say it’s anyone. The chart’s notes, after helm install, say so too.
3

Give people roles

Bind roles to the names the proxy sends, with the prefixes you chose:

A proxy in another namespace

When the proxy runs in a namespace of its own, name that namespace and the proxy’s pods in the same entry of from. Kubernetes labels every namespace with its name, in kubernetes.io/metadata.name:
values.yaml
In one entry, both have to match: the proxy’s pods, in that namespace. As two entries (a - before each), either would do, so every pod in the proxy’s namespace could reach Lumovi.

The headers

string
default:"X-Forwarded-User"
The request header that names the person. A request without it gets a page that says Lumovi doesn’t know who you are, and asks people to have whoever runs Lumovi check the proxy.
string
default:"X-Forwarded-Groups"
The request header that lists their groups, separated by commas.
string
Where signing out of the proxy is, like https://lumovi.example.com/oauth2/sign_out. Lumovi has no session of its own behind a proxy, so signing out means signing out of the proxy.
string
default:"off"
Whether your proxy passes the browser’s Sec-Fetch-Site header through to Lumovi unchanged. On: every request must say it comes from Lumovi’s own page, and one without the header gets a page that says Lumovi refused a request from this browser, since the browser may be too old to send it, or the proxy may not pass it on. Off, the default: plugins that run code aren’t offered on this server, and Lumovi says so in its log as it starts. Turn it on only after checking that the header reaches Lumovi: a proxy that drops it locks everyone out, and one that sets it itself makes the check mean nothing. See Requests from Lumovi’s own page.For plugins that run code, the proxy must also let box-check/ below Lumovi’s address through without its own sign-in: Lumovi checks each browser there, with requests that carry no cookie of the proxy’s. See Plugins’ code.
Lumovi never acts as one of Kubernetes’ own users or groups (system:…), whatever the proxy says. It leaves out groups whose names start with system:, and refuses a user whose name does.

AI assistants

AI assistants can’t sign in to your proxy: they sign in to Lumovi, which gives them tokens of its own, and checks them itself. Let these through to Lumovi without signing in, below the base path:
  • mcp
  • oauth/register, oauth/token and oauth/revoke
  • .well-known/oauth-authorization-server, .well-known/oauth-protected-resource and .well-known/oauth-protected-resource/mcp
  • Below a base path like /lumovi, also /.well-known/oauth-authorization-server/lumovi and /.well-known/oauth-protected-resource/lumovi/mcp, at the origin’s root.
None of them takes the proxy’s headers. Keep everything else behind the proxy, authorize and api/assistants/authorize included: that’s where people allow an assistant, and Lumovi needs to know who they are. With oauth2-proxy, at its own host, with its --skip-auth-route option:
oauth2-proxy
An assistant someone allows acts as that person, as the proxy last named them: each time they open a Lumovi page, their assistants take on what the proxy says about them there, like their groups, and connect again when that changed. It lasts as long as a session would (auth.sessionHours, 12 hours unless set), from when they allowed it. Signing out of the proxy doesn’t end it: people disconnect it in Lumovi’s AI assistants dialog. To have no assistants at all, set assistants.enabled: false.

What it means for the cluster

Behind a proxy, Lumovi impersonates people, so the chart gives its service account permission to impersonate users and groups, cluster-wide. Whoever can reach Lumovi’s pod, or read its service account’s token, can act as anyone. Keep Lumovi in a namespace only cluster administrators can exec into. See Security. There are no Lumovi sessions behind a proxy: it reads the headers on every request. Restarting Lumovi doesn’t sign anyone out, and how long people stay signed in is up to the proxy. Lumovi keeps who allowed each AI assistant, and as whom: across a restart too (auth.keepSessions), so assistants carry on at once. See Across restarts. For the same reason, Lumovi’s audit log has no sign-ins or sign-outs behind a proxy: those are the proxy’s to log. Everything people do through Lumovi is recorded, as the proxy names them, with the address their requests came from and what X-Forwarded-For said.

In a fleet

A fleet behind a proxy works the same way: the proxy names people, and Lumovi impersonates them in every cluster, with the credentials it has for each. The chart lets Lumovi’s own service account impersonate only in the cluster it runs in, when that’s one of the fleet’s.
  • Prefixes: auth.usernamePrefix and auth.groupsPrefix apply in each cluster, unless the cluster has its own. Bind roles in each cluster to the names it sees.
  • A cluster’s groups decide who sees it: groups as the proxy sends them, without prefixes.
  • There are no tokens to pass on. The proxy names people, but gives Lumovi no token of theirs, so a cluster with forwardToken: true can’t be used: its card says Credentials failed, and why. For clusters that should get people’s own tokens, use single sign-on.
  • Agents come through the proxy too. Let api/agent through to Lumovi without signing in: agents can’t sign in to a proxy, and Lumovi checks their names and tokens itself. A proxy that answers 401 makes an agent stop. As only the proxy’s pods may reach Lumovi, agents can’t come in any other way. See Private clusters.

Security

Hardening Lumovi when it impersonates people.

Single sign-on

Or let Lumovi talk to your provider directly.