Skip to main content

v26.3.15

v26.3.15​

Oathkeeper adopts shared HTTP metrics and adds per-rule access decisions​

Oathkeeper uses the shared Ory HTTP metric schema. It also exposes ory_oathkeeper_access_decisions_total, which reports allowed requests, authentication failures, authorization failures, and pipeline errors by rule ID. Access decisions are independent of login redirects and upstream response codes.

Breaking changes​

For Oathkeeper dashboards and alerts, replace service with app and status_code with code. The request label is replaced by endpoint, which contains API router patterns such as /rules/{param} and /decisions/ and is empty for proxy traffic. The app values remain oathkeeper-api and oathkeeper-proxy. HTTP metrics also include version, hash, and buildTime. Metric names retain the configured prefix. Health requests are now included.

serve.prometheus.hide_request_paths and serve.prometheus.collapse_request_paths are deprecated and have no effect. Update path filters to use router patterns or the new per-rule counter.

In Oathkeeper, Kratos, Hydra, and Keto, the requests_statuses_total metric's method labels now follow the same normalization as other shared HTTP metrics: recognized methods use lowercase values, and other methods use other. Oathkeeper applies this normalization to all HTTP metrics.

Unsupported methods use other instead of unknown across all shared HTTP metrics. Update queries that filter on the previous method label.

Keto can serve its APIs over HTTPS​

Every Keto endpoint - read, write, OPL syntax and metrics - can now terminate TLS itself. Point Keto at a certificate and key, either as file paths or as base64-encoded PEM:

serve:
  read:
    tls:
      cert:
        path: /etc/keto/tls/tls.crt
      key:
        path: /etc/keto/tls/tls.key

Configuring a certificate is what turns TLS on for an endpoint. If the TLS configuration is incomplete or incorrect, Keto fails to start instead of silently falling back to insecure HTTP.

When you configure the certificate through path, Keto reloads it automatically as it changes on disk, so certificate rotation needs no restart. gRPC and HTTP clients keep working over the TLS port.

TLS is off by default and the listen addresses are unchanged, so existing deployments continue to serve plain HTTP.

Listening on a unix socket​

Every endpoint can also listen on a unix socket instead of a TCP port. Set the host to a unix: path and control who may connect through the file permissions:

serve:
  read:
    host: unix:/var/run/keto/read.sock
    socket:
      owner: keto
      group: keto
      mode: 384 # 0600

Connecting to a unix socket requires write permission on the socket file, so mode is the access control for the endpoint. It defaults to 493 (0755), which lets only the owner connect. Keto removes the socket file when it shuts down.

A unix socket endpoint cannot terminate TLS, because the socket permissions are the access control and there is no host name for a client to verify. Configuring both is rejected at startup rather than silently serving one of them.

Configuration that is now rejected​

Two configurations that Keto used to accept and silently ignore are now rejected at startup: a write_listen_file without the file:// scheme, and a tls.cert or tls.key that sets both path and base64. Neither ever took effect, so correct the value and Keto starts as before.

TLS configuration and unix socket recovery in Hydra, Keto and Kratos​

A configured certificate is now the only switch for TLS in all three services. serve.<endpoint>.tls.enabled is deprecated but still accepted so that an existing configuration keeps loading, but it has no effect. Each service logs a warning at startup naming the key to remove. To serve plain HTTP behind a proxy that terminates TLS, remove the certificate rather than the flag.

Hydra and Kratos also pick up two fixes from the shared serve configuration:

  1. configuring only one half of a certificate pair is now a startup error instead of a listener that silently falls back to plain HTTP
  2. a unix socket left behind by an unclean shutdown is replaced instead of blocking the next start.

Because the three services now configure their endpoints identically, the documentation for it is one page: Serving the APIs. It replaces the separate Hydra and Kratos HTTPS pages, which now redirect to it.