Skip to content

Authentication

Finch uses two distinct authentication mechanisms depending on who is connecting. See Security for the full layered model.

finchctl → Finch (mTLS)

Every finchctl command that talks to the Finch gRPC service presents a client certificate during the TLS handshake with Traefik.

Flow:

  1. Traefik's middleware extracts the presented client certificate PEM and forwards it as the X-Forwarded-Tls-Client-Cert HTTP header.
  2. The Finch gRPC server reads the header and validates the certificate against the registered finchctl client CA file.
  3. Validation checks x509 extension key usage and the current wall clock. If the CA does not exist or match, the request is rejected as unauthorized.

Client certificates are valid for 90 days. Rotate with service rotate-certificate.

Alloy agents → Finch (JWT ForwardAuth)

Agents authenticate using Bearer JWT sent with every write request to the data endpoints (/loki, /mimir, /pyroscope).

Flow:

  1. Traefik's middleware intercepts the request and performs a forward authentication call to finch's auth server.
  2. The Finch auth server extracts the Authorization: Bearer <token> header and calls checks:
  3. HMAC-SHA256 signature (using the stack signing secret)
  4. iss = finch, sub = agent
  5. Token not expired (exp claim)
  6. RID exists in the agent database
  7. HTTP 200 → Traefik forwards the request to the backend. HTTP 401 → write is rejected.

Agent tokens are valid for 365 days. Renew with agent config + agent deploy.

Dashboard access uses a short-lived JWT issued by finchctl service dashboard and passed as a parameter to login.

  1. The token is valitated.
  2. On success, the token is stored in an HttpOnly, SameSite-Strict cookie (dashboard_token).
  3. The Finch HTTP server on subsequent requests reads the cookie and validates the token on every request. An expired token is rejected and the user is redirected to the login page with an expired session message.
  4. The WebSocket additionally validates the token on a 30-second ticker, and if the session expires mid-connection, the WebSocket is closed with a normal closure.
  5. The cookie is cleared on logout or expiration.

Dashboard tokens are valid for the configured session timeout (default 1800 seconds).