Loki SSO and identity integration

The tenant decision happens in the authenticating proxy, so that is where you design and test the control. When a user signs in through the proxy, the proxy reads the user's groups or claims from the identity provider's token, looks each one up in your mapping table, and sets the X-Scope-OrgID header to the tenant that the mapping returns before forwarding the request to Loki. Loki runs in multi-tenant mode when auth_enabled is true, and it uses that header on every request to choose which tenant's data to read or write. Grafana data sources must send the same header, either through a proxy route or a configured custom header. Confirm exactly how your chosen proxy (nginx, HAProxy, OAuth2 Proxy or Pomerium) exposes groups or claims to its configuration, because that determines how the lookup is written.

The proxy must overwrite or strip any X-Scope-OrgID value the client sends. Loki reads the header as given, so a user who adds their own value to a request can ask for another team's tenant if the proxy passes it through untouched. The proxy should remove the inbound header on every route, including the push endpoint, the query endpoints and any ruler or administrative paths, and then set its own value from the mapping. Network design matters as well: Loki's listening ports should accept traffic only from the proxy, so a client cannot skip the proxy and send the header directly. Test this before go-live. Send requests with a forged header for a tenant the test user is not mapped to, and confirm that the request is refused or returns only the mapped tenant's data. Repeat the test on each route.

A user who belongs to several teams needs a written rule, because the proxy must return one header value or a defined set. The first option is a single home tenant per user, chosen by a stated rule such as primary team or the team that owns the service the person supports. This keeps each query on one tenant and makes audit records easy to read. The second option is multi-tenant querying, where the proxy sends several tenants for one query. Loki supports querying multiple tenants, but the header syntax, the limits that apply and the behavior of each query path depend on the version you run, so confirm them in the Loki multi-tenancy documentation for your release before you adopt the approach. Grafana Enterprise Logs adds cross-tenant queries and label-based access control, which is a separate decision covered in the editions topic.

Loki does not check who the user is. It has no built-in authentication layer, and its documentation directs you to place an authenticating reverse proxy in front of it. Its tenant handling separates stored data by the tenant string in the header, and it accepts that string from whoever sends the request. Authorization therefore lives in the proxy, the mapping table and the network path to Loki, and each of them needs an owner. The mapping table is a control you own. Any change in team membership, offboarding or identity provider group must be reflected in it, or the former team's access continues. Set a review schedule for the table, assign the reviewer, and tie reviews to your joiner, mover and leaver process. Ask the identity team which group changes they can export so the review can compare the table with current membership.

Before any team sends production logs through the proxy, run a fixed set of tests that try to break tenant isolation and confirm that every failure closes rather than opens. The first test is the most basic: send push and query requests to every Loki path, including the write endpoint and the query endpoints used by Grafana and any direct API clients, with no credentials at all and with an expired or malformed token. Each request should be refused by the reverse proxy before it reaches Loki. Because Loki has no authentication layer of its own, the proxy configuration is the only thing standing between an anonymous caller and the data, so the test should be written to enumerate paths from the proxy's routing rules rather than from memory. Keep the results as evidence for your access control review.

The second group of tests checks that a user in one group cannot see another tenant's streams. Create at least two test users mapped to two different tenants, ingest a known marker log line into each tenant, and then query from each identity for both markers. Each user should see only their own marker and never the other one, including through label-only queries that match on broad selectors such as a common application label. Repeat the check from the Grafana side using the same identities, because a Grafana data source configured with a fixed organization identifier can silently bypass the mapping you intended. The reader should confirm how their chosen proxy sets the tenant header and whether any route permits a caller to choose a tenant by path or query parameter.

Next, test the header itself. Send a request from an authenticated test user that includes a client-supplied X-Scope-OrgID for another tenant, and confirm that the proxy overwrites or strips the value so Loki only receives the tenant derived from the identity. Run the same test on the push path, where a misconfigured shipper could otherwise write logs into another tenant's space. Then test session behavior: an expired session should stop working on the next request without a manual logout, and removing a user from the identity provider group that grants access should block access within the time window your configuration allows. Record that window explicitly, since it is the period during which a departed employee can still read logs. Finally, test failure behavior. Make the identity provider unreachable, for example by blocking its network path from the proxy in a test environment, and confirm that the proxy refuses requests rather than passing them through unauthenticated. Also confirm that Grafana logins map to the expected data sources and that users without a mapping see no data source at all.

These tests are not a one-time gate. Repeat the full set after every upgrade of the reverse proxy, Loki, or Grafana, and after any change to proxy routing, header handling, identity provider group rules, or the Helm values that control authentication. Upgrades often change default header behavior, route names, or session handling in ways that open a path nobody tested, and the Loki upgrade notes should be reviewed for any change to multi-tenancy or authentication behavior. Keep the test cases as scripts in version control with recorded expected results so a reviewer can rerun them and compare outputs. Ask your implementation partner, or your own team, to state in writing which test cases are covered by the engagement, who runs them after each change, and where the results are stored.

The first thing to watch after go-live is the authentication boundary, because Loki trusts whatever tenant the proxy sends in X-Scope-OrgID. Track proxy authentication failures, IdP outages and token validation errors, and alert on sudden spikes in 401 or 403 responses from the proxy. Decide in advance what happens to queries when the identity provider is unreachable: whether existing sessions keep working, and whether Grafana users see a clear login error. Confirm with your IdP and proxy vendor how session lifetimes and cookie settings behave during an outage, since those settings decide how far the failure spreads.

Group-to-tenant mappings change more often than anything else in this stack. Every new team, reorganization or contractor group can add or widen access, so each mapping change should go through a named approver, a ticket, and a peer review of the rule before it reaches production. Treat a wildcard or broad group match as a higher-risk change that needs a second approver. Record who can edit the mapping source and confirm that the change history is kept. Review the mapping list on a fixed cadence with the data owner of each tenant, and remove mappings whose groups no longer exist in the directory.

Stale accounts and secrets are where access quietly outlives its purpose. Schedule a review of users who have not signed in within a period your security policy sets, and disable accounts when the directory disables them, confirming that deprovisioning also ends existing proxy and Grafana sessions. Track the lifetime of the OIDC or SAML client secret, the proxy's TLS certificates, the signing keys and any Grafana service account tokens. Rotation should be rehearsed in a non-production environment first, with a plan for the overlap window during which both old and new credentials are valid.

Documentation should let someone who was not present at build time run the system safely. Keep these records current: the tenant model, showing which teams or products map to which tenant IDs and who owns each one; the mapping source and its owner; the header-handling rules, listing which headers the proxy strips from client requests, sets and forwards, and how it prevents clients from supplying their own X-Scope-OrgID; the test cases with their most recent results and dates; and a runbook for revoking a user's or group's access across the proxy, Grafana and the IdP. Test the revocation runbook at least once before anyone needs it.

Upgrades need separate checks for each component. The authenticating proxy, Loki and Grafana change behavior on their own release schedules, and a passing Loki upgrade does not prove the proxy still forwards the tenant header correctly. Promtail reached end of life on March 2, 2026, with no further updates or commercial support, and Grafana directs users to Grafana Alloy. If a shipper change is part of your plan, test the new tenant header path end to end, confirming that logs from each tenant land only in that tenant and that a query from a different tenant returns nothing.