Securing Prometheus API and UI endpoints using basic auth

Prometheus supports basic authentication (aka “basic auth”) for connections to the Prometheus expression browser and HTTP API.

NOTE: This tutorial covers basic auth connections to Prometheus instances. Basic auth is also supported for connections from Prometheus instances to scrape targets.

Hashing a password

Let’s 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, generate a bcrypt hash of the password. To generate a hashed password, we will use python3-bcrypt.

Let’s install it by running apt install python3-bcrypt, assuming you are running a debian-like distribution. Other alternatives exist to generate hashed passwords; for testing you can also use bcrypt generators on the web.

Here is a python script which uses python3-bcrypt to prompt for a password and hash it:

import getpass
import bcrypt
password = getpass.getpass("password: ")
hashed_password = bcrypt.hashpw(password.encode("utf-8"), bcrypt.gensalt())
print(hashed_password.decode())

Save that script as gen-pass.py and run it:

$ python3 gen-pass.py

That should prompt you for a password:

password:
$2b$12$hNf2lSsxfm0.i4a.1kVpSOVyBCfIB51VRjgBUyv6kdnyTlgWj81Ay

In this example, I used “test” as password.

Save that password somewhere, we will use it in the next steps!

Creating web.yml

Let’s create a web.yml file (documentation), with the following content:

basic_auth_users:
    admin: $2b$12$hNf2lSsxfm0.i4a.1kVpSOVyBCfIB51VRjgBUyv6kdnyTlgWj81Ay

You can validate that file with promtool check web-config web.yml

$ promtool check web-config web.yml
web.yml SUCCESS

You can add multiple users to the file.

Launching Prometheus

You can launch prometheus with the web configuration file as follows:

$ prometheus --web.config.file=web.yml

Testing

You can use cURL to interact with your setup. Try this request:

curl --head http://localhost:9090/graph

This will return a 401 Unauthorized response because you’ve failed to supply a valid username and password.

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:

curl -u admin http://localhost:9090/metrics
Enter host password for user 'admin':

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

# HELP go_gc_duration_seconds A summary of the GC invocation durations.
# TYPE go_gc_duration_seconds summary
go_gc_duration_seconds{quantile="0"} 0.0001343
go_gc_duration_seconds{quantile="0.25"} 0.0002032
go_gc_duration_seconds{quantile="0.5"} 0.0004485
...

Summary

In this guide, you stored a username and a hashed password in a web.yml file, launched prometheus with the parameter required to use the credentials in that file to authenticate users accessing Prometheus’ HTTP endpoints.

This documentation is open-source. Please help improve it by filing issues or pull requests.