Securing Prometheus API and UI endpoints using basic auth

Prometheus does not directly support basic authentication (aka "basic auth") for connections to the Prometheus expression browser and HTTP API. If you'd like to enforce basic auth for those connections, we recommend using Prometheus in conjunction with a reverse proxy and applying authentication at the proxy layer. You can use any reverse proxy you like with Prometheus, but in this guide we'll provide an nginx example.

NOTE: Although basic auth connections to Prometheus instances are not supported, basic auth is supported for connections from Prometheus instances to scrape targets.

nginx example

Let's say that you want to run a Prometheus instance behind an nginx server running on localhost:12321, and for all Prometheus endpoints to be available via the /prometheus endpoint. The full URL for Prometheus' /metrics endpoint would thus be:

  1. http://localhost:12321/prometheus/metrics

Let's also say that you want to require a username and password from all users accessing the Prometheus instance. For this example, use admin as the username and choose any password you'd like.

First, create a .htpasswd file to store the username/password using the htpasswd tool and store it in the /etc/nginx directory:

  1. mkdir -p /etc/nginx
  2. htpasswd -c /etc/nginx/.htpasswd admin

NOTE: This example uses /etc/nginx as the location of the nginx configuration files, including the .htpasswd file, but this will vary based on the installation. Other common nginx config directories include /usr/local/nginx/conf and /usr/local/etc/nginx.

nginx configuration

Below is an example nginx.conf configuration file (stored at /etc/nginx/.htpasswd). With this configuration, nginx will enforce basic auth for all connections to the /prometheus endpoint (which proxies to Prometheus):

  1. http {
  2.     server {
  3.         listen 12321;
  5.         location /prometheus {
  6.             auth_basic           "Prometheus";
  7.             auth_basic_user_file /etc/nginx/.htpasswd;
  9.             proxy_pass           http://localhost:9090/;
  10.         }
  11.     }
  12. }
  14. events {}

Start nginx using the configuration from above:

  1. nginx -c /etc/nginx/nginx.conf

Prometheus configuration

When running Prometheus behind the nginx proxy, you'll need to set the external URL to http://localhost:12321/prometheus and the route prefix to /:

  1. prometheus \
  2.   --config.file=/path/to/prometheus.yml \
  3.   --web.external-url=http://localhost:12321/prometheus \
  4.   --web.route-prefix="/"

Testing

You can use cURL to interact with your local nginx/Prometheus setup. Try this request:

  1. curl --head http://localhost:12321/prometheus/graph

This will return a 401 Unauthorized response because you've failed to supply a valid username and password. The response will also contain a WWW-Authenticate: Basic realm="Prometheus" header supplied by nginx, indicating that the Prometheus basic auth realm, specified by the auth_basic parameter for nginx, is enforced.

To successfully access Prometheus endpoints using basic auth, for example the /metrics endpoint, supply the proper username using the -u flag and supply the password when prompted:

  1. curl -u admin http://localhost:12321/prometheus/metrics
  2. Enter host password for user 'admin':

That should return Prometheus metrics output, which should look something like this:

  1. # HELP go_gc_duration_seconds A summary of the GC invocation durations.
  2. # TYPE go_gc_duration_seconds summary
  3. go_gc_duration_seconds{quantile="0"} 0.0001343
  4. go_gc_duration_seconds{quantile="0.25"} 0.0002032
  5. go_gc_duration_seconds{quantile="0.5"} 0.0004485
  6. ...

Summary

In this guide, you stored a username and password in a .htpasswd file, configured nginx to use the credentials in that file to authenticate users accessing Prometheus' HTTP endpoints, started up nginx, and configured Prometheus for reverse proxying.