Identity header


On each request from a signed-in person, LocalCan Access sends your app a short-lived signed token that says who they are. An app that checks it can sign the person in with no second login.

The token is a JWT in the LC-Access-Jwt-Assertion request header, signed with RS256 by a key that belongs to your team. Grafana reads it with its built-in JWT sign-in. Your own app can check it with a JWT library in a few lines.

Apps that don't read the header, such as Metabase, Umami and n8n, keep their own login behind LocalCan Access.

What it contains

A decoded token looks like this:

Text
{
  "alg": "RS256",
  "kid": "2bVQ0H8m3hXk...",
  "typ": "JWT"
}
{
  "iss": "https://access.localcan.com/t/team_xxxxxxxxxxxx",
  "aud": "app_xxxxxxxxxxxx",
  "sub": "8f6c2a51-0d3e-4b7a-9e1f-5a2b7c9d4e60",
  "sid": "1d2e3f40-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
  "jti": "Qm9h2kX7vT1sYw8rL3nP0a",
  "iat": 1793800000,
  "nbf": 1793799970,
  "exp": 1793800600,
  "idp": "google",
  "email": "viewer@example.com",
  "email_verified": true,
  "name": "Example Viewer"
}
ClaimMeaning
issYour team's issuer. The app's Identity header section in the dashboard shows it.
audThe app. Check it, so a token for another app of the team is refused.
subThe person's ID in your team, the same at every sign-in with the same method. The same person signing in with another method, or in another team, has another sub.
email, email_verifiedOnly when the sign-in method gave an address LocalCan counts (see Sign-in methods), and then email_verified is always true.
nameThe name the sign-in method gave, when there is one.
idpHow the person signed in: google, microsoft, github, or oidc: and your connection's ID.
groupsGroups from your own identity provider, lowercase and sorted. Left out whole, never cut, when there are more than 50 or the token would pass 4 KB.
sid, jtiThe session's ID and the token's own ID.
iat, nbf, expIssued at, valid from (30 seconds earlier, for clock skew), and expiry: 10 minutes at most, and never after the session ends. LocalCan refreshes the token while the person is active. If LocalCan's servers can't be reached, the header stops once the token expires, even while the session goes on.

When the app gets it

  • On every request that a signed-in person's session lets through, including a WebSocket upgrade.
  • Never on a public path or a request with a service token.
  • Not on a request other than GET, HEAD or OPTIONS when the browser says it comes from another site (Sec-Fetch-Site: same-site or cross-site), and not on a WebSocket opened from a page on another origin. This stops a page on a sibling subdomain from acting as the person.

LocalCan removes every LC-Access-* header a client sends before the request reaches your app, so the header your app reads is always LocalCan's.

Sign people in only from this header, after checking it. LocalCan doesn't set or remove the identity headers other sign-in proxies use, such as Remote-User, X-WEBAUTH-USER, X-Auth-Request-*, Cf-Access-*, X-Goog-Authenticated-User-*, X-Amzn-Oidc-*, X-Ms-Client-Principal-* or X-Pomerium-Jwt-Assertion, so any of them can come straight from a person's browser or script. Turn off every setting in your app that trusts one, such as Grafana's [auth.proxy].

Every app behind LocalCan Access receives the header, including those that ignore it. A token is at most 4 KB. Metabase accepts up to 8,192 bytes of request headers by default (MB_JETTY_REQUEST_HEADER_SIZE), so the token leaves it about half of that for cookies and other headers.

Check it in your app

Check the signature against your team's public keys, then the issuer, the audience and the expiry. The keys are published at the issuer followed by /.well-known/jwks.json. Copy the issuer, audience and JWKS URL from the app's Identity header section.

Node.js, with jose↗:

JS
import { createRemoteJWKSet, jwtVerify } from 'jose'

const issuer = 'https://access.localcan.com/t/team_xxxxxxxxxxxx'
const audience = 'app_xxxxxxxxxxxx'
const jwks = createRemoteJWKSet(new URL(`${issuer}/.well-known/jwks.json`))

// The signed-in person, or null when the request has no identity header.
export async function viewer(request) {
  const token = request.headers.get('lc-access-jwt-assertion')
  if (!token) return null
  const { payload } = await jwtVerify(token, jwks, { issuer, audience, algorithms: ['RS256'] })
  return payload
}

Python, with PyJWT↗ (pip install "pyjwt[crypto]"):

Python
import jwt

ISSUER = "https://access.localcan.com/t/team_xxxxxxxxxxxx"
AUDIENCE = "app_xxxxxxxxxxxx"
jwks = jwt.PyJWKClient(f"{ISSUER}/.well-known/jwks.json")


def viewer(headers):
    """The signed-in person, or None when the request has no identity header."""
    token = headers.get("LC-Access-Jwt-Assertion")
    if not token:
        return None
    key = jwks.get_signing_key_from_jwt(token)
    return jwt.decode(token, key.key, algorithms=["RS256"], audience=AUDIENCE, issuer=ISSUER)

Both raise an error for a token that fails any check. Answer that request with 401, never with the person signed in.

Both libraries cache the keys and fetch them again when a token names a key they don't have. LocalCan publishes a new key at least a day before it signs with it, and keeps a retired key published for 7 days.

Grafana

Grafana signs people in from the header with its JWT authentication. Add this to grafana.ini, with your app's values from the Identity header section:

INI
[server]
root_url = https://grafana.example.com/

[auth.jwt]
enabled = true
header_name = LC-Access-Jwt-Assertion
jwk_set_url = https://access.localcan.com/t/team_xxxxxxxxxxxx/.well-known/jwks.json
cache_ttl = 5m
expect_claims = {"iss": "https://access.localcan.com/t/team_xxxxxxxxxxxx", "aud": "app_xxxxxxxxxxxx"}
username_claim = sub
email_claim = email
auto_sign_up = true
skip_org_role_sync = true

[users]
auto_assign_org_role = Viewer
  • The root_url setting must be the app's address. Grafana Live accepts a WebSocket only from that origin, and dashboards stop updating without it.
  • Each new person joins as a Viewer. Change roles in Grafana. The skip_org_role_sync setting keeps your changes at the next sign-in.
  • Groups arrive in lowercase, so match them in lowercase in any Grafana role mapping.
  • Grafana keeps the keys for cache_ttl and does not fetch them again for an unknown key. If LocalCan ever has to replace your team's keys at once, Grafana accepts the new key within 5 minutes.

© 2026 LocalCan™. All rights reserved.