Setting up authentication

Setting up filters

TLDR: Setting up basic authentication with TLS encryption.

Sometimes you need to restrict access to exposed metrics, for example in case of public or untrusted networks. In such cases, /metrics endpoint could be protected with basic authentication with TLS encryption.

Note: It's strongly recommended to use basic authentication and TLS encryption together. Basic authentication credentials without TLS could be easily intercepted.

To enable authentication and encryption you can use YAML configuration or environment variables.

1. To enable authentication you need to specify username and password in authentication section. For TLS you need key and certificate in PEM format. For testing purposes you can use mkcert utility and create a local CA and issue certificates.

   Paths to key and certificate should be specified in keyfile and certfile of authentication section.

authentication:
  username: monitoring
  password: supersecret
  keyfile: /path/to/certs/localhost-key.pem
  certfile: /path/to/certs/localhost.pem

2. After editing configuration, restart the service.

systemctl restart pgscv

3. Test connection with curl and without username and password. The response should be "Unauthorized".

$ curl -i https://127.0.0.1:9890/metrics
HTTP/2 401 
content-type: text/plain; charset=utf-8
www-authenticate: Basic realm="restricted", charset="UTF-8"
x-content-type-options: nosniff
content-length: 13
date: Thu, 08 Feb 2024 12:07:13 GMT

Unauthorized

Add username and password, the answer should be a valid response with metrics:

$ curl -i -u monitoring:supersecret https://127.0.0.1:9890/metrics
HTTP/2 200 
content-type: text/plain; version=0.0.4; charset=utf-8
date: Thu, 08 Feb 2024 12:07:50 GMT

# HELP go_gc_duration_seconds A summary of the pause duration of garbage collection cycles.
# TYPE go_gc_duration_seconds summary
go_gc_duration_seconds{quantile="0"} 2.0322e-05
go_gc_duration_seconds{quantile="0.25"} 2.0322e-05
go_gc_duration_seconds{quantile="0.5"} 2.7742e-05
go_gc_duration_seconds{quantile="0.75"} 3.3271e-05
go_gc_duration_seconds{quantile="1"} 3.3271e-05
go_gc_duration_seconds_sum 8.1335e-05
go_gc_duration_seconds_count 3
# HELP go_goroutines Number of goroutines that currently exist.
# TYPE go_goroutines gauge
go_goroutines 13
# HELP go_info Information about the Go environment.
# TYPE go_info gauge
go_info{version="go1.22.0"} 1
... the rest of output omitted

Note: you also can specify auth parameter using the following environment variables: PGSCV_AUTH_USERNAME, PGSCV_AUTH_PASSWORD, PGSCV_AUTH_KEYFILE and PGSCV_AUTH_CERTFILE.