Implementing Authentication

1. Configuring Basic Authentication

Configuration Option	Description	Default Value	Notes
basic_auth.username	Username for basic authentication	`admin`	Must be set for basic auth to function
basic_auth.password	Password for basic authentication	`secret`	Must be set for basic auth to function

Example: Basic Auth Configuration

basic_auth:
  username: "admin"
  password: "secret"

Note: Basic authentication is not recommended for production environments without additional security measures like HTTPS.

2. Using Bearer Token Authentication

Configuration Option	Description	Default Value	Notes
bearer_token	Path to a file containing the bearer token	None	Must be readable by the Prometheus process
bearer_token_file	Path to a file containing the bearer token	None	Alternative to `bearer_token`

Example: Configuring Bearer Token Authentication

remote_write:
  - url: https://prometheus.example.com/api/v1/write
    bearer_token_file: /etc/prometheus/bearer_token.txt

Note: The bearer token must be provided as a single line in the file specified by bearer_token_file.

Warning: Ensure that the file containing the bearer token is securely stored and has appropriate permissions to prevent unauthorized access.

3. Setting Up TLS Encryption

Configuration Option	Description	Default Value	Example
tls.cert_file	Path to the certificate file for TLS	None	`/etc/prometheus/certs/server.crt`
tls.key_file	Path to the private key file for TLS	None	`/etc/prometheus/certs/server.key`
tls.client_ca_file	Path to the CA file for client certificate verification	None	`/etc/prometheus/certs/ca.crt`

Example: Prometheus TLS Configuration

tls:
  cert_file: /etc/prometheus/certs/server.crt
  key_file: /etc/prometheus/certs/server.key
  client_ca_file: /etc/prometheus/certs/ca.crt

Note: Ensure that the certificate and key files are accessible by the Prometheus process and have appropriate permissions to prevent unauthorized access.

4. Configuring Client Certificates

Property	Description	Default Value	Notes
tls.client.ca-file	Path to the CA certificate file used to verify client certificates.	None	Required if client certificate authentication is enabled.
tls.client.cert-file	Path to the client certificate file.	None	Must be provided if client certificate authentication is enabled.
tls.client.key-file	Path to the client private key file.	None	Must be provided if client certificate authentication is enabled.

Example: Prometheus Configuration with Client Certificates

tls_config:
  ca_file: /etc/prometheus/client-ca.crt
  cert_file: /etc/prometheus/client.crt
  key_file: /etc/prometheus/client.key

Note: Ensure that the CA certificate, client certificate, and private key files are readable by the Prometheus process.

5. Setting CA Certificate

Property	Description	Default Value	Notes
ca_file	Path to the CA certificate file used for verifying the server's certificate.	`none`	Required if using TLS with custom CA.
ca_path	Path to a directory containing CA certificates.	`none`	Alternative to `ca_file`, useful for multiple certificates.

Example: Configuring CA Certificate for TLS

tls_config:
  ca_file: /etc/ssl/certs/ca-certificates.crt
  cert_file: /etc/ssl/certs/server.crt
  key_file: /etc/ssl/private/server.key

Note: Ensure the CA certificate file is readable by the Prometheus process and contains valid PEM-encoded certificates.

6. Implementing Server Name Verification

Property	Description	Default	Notes
tls.server.name	Server name for TLS verification	None	Required when using TLS with server certificate validation
tls.insecure.skip.verify	Disable TLS certificate verification	false	Not recommended for production environments

Example: Configuring Server Name Verification

tls:
  server:
    name: "prometheus.example.com"
  insecure:
    skip:
      verify: false

Note: The server.name must match the Common Name (CN) or Subject Alternative Name (SAN) in the server certificate.

7. Using OAuth2 Authentication

Property	Description	Example
oauth2.client_id	Client ID for OAuth2 provider	`my-client-id`
oauth2.client_secret	Client secret for OAuth2 provider	`my-client-secret`
oauth2.scopes	Scopes to request from OAuth2 provider	`read:metrics`
oauth2.redirect_uri	Redirect URI for OAuth2 callback	`https://prometheus.example.com/oauth/callback`
oauth2.provider	OAuth2 provider (e.g., Google, GitHub)	`github`

Example: OAuth2 Configuration

oauth2:
  client_id: "my-client-id"
  client_secret: "my-client-secret"
  scopes:
    - read:metrics
  redirect_uri: "https://prometheus.example.com/oauth/callback"
  provider: "github"

Note: Ensure that the OAuth2 provider supports the requested scopes and that the redirect URI matches exactly what is configured in the provider.

8. Configuring Web Authentication

Property	Values	Description
web.auth.config	`auth.yml`	Path to the authentication configuration file.
web.auth.password-file	`passwords.txt`	Path to a file containing user credentials (username:hashed-password).
web.auth.bearer-token	`token`	Bearer token for authentication (used with `--web.auth.bearer-token-file`).
web.auth.bearer-token-file	`token.txt`	Path to a file containing the bearer token.
web.auth.disable-router	`false`	Disables the router's authentication checks (not recommended for production).

Example: Basic Web Authentication Setup

# auth.yml
basic_auth:
  username: "admin"
  password_hash: "$2b$10$examplehash"

bearer_token:
  token: "secret-token"

Example: Using Password File

# passwords.txt
admin:$2b$10$examplehash
user1:$2b$10$anotherhash

Note: The password_hash should be generated using a secure hashing algorithm like bcrypt.

Warning: Never commit auth.yml or passwords.txt to version control.

9. Setting Up User Credentials

Property	Description	Default Value	Notes
prometheus.config.users	List of user credentials to be configured	None	Each user requires a username and password
prometheus.config.user.password	Password for the user (hashed)	None	Must be hashed using bcrypt or similar

Example: Configuring User Credentials

users:
  - name: "admin"
    password_hash: "$2b$10$example_hashed_password"
  - name: "viewer"
    password_hash: "$2b$10$another_hashed_password"

Note: Passwords must be securely hashed before being added to the configuration file.

Warning: Never store plain-text passwords in configuration files.

10. Using Service Account Tokens

Property	Description	Default	Notes
bearer_token	Bearer token for authentication	None	Used to authenticate requests to the Prometheus server
bearer_token_file	Path to a file containing a bearer token	None	File must contain only the token, with no extra whitespace or newlines

Example: Configuring bearer token in Prometheus config

remote_write:
  - url: http://prometheus.example.com/api/v1/write
    bearer_token: "your-bearer-token-here"

Example: Using bearer token file

remote_write:
  - url: http://prometheus.example.com/api/v1/write
    bearer_token_file: /path/to/bearer/token/file

Note: The bearer_token and bearer_token_file options are mutually exclusive. If both are specified, the bearer_token takes precedence.

11. Securing Remote Write

Configuration	Description	Default
remote_write	URL of the remote write endpoint	None
remote_write.basic_auth	Basic authentication credentials	None
remote_write.bearer_token	Bearer token for authentication	None
remote_write.tls_config	Configuration for TLS connection	None

Example: Basic Auth for Remote Write

remote_write:
  - url: https://prometheus-remote.example.com/api/v1/write
    basic_auth:
      username: "prometheus"
      password: "secret123"

Example: Bearer Token for Remote Write

remote_write:
  - url: https://prometheus-remote.example.com/api/v1/write
    bearer_token: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Note: Ensure the remote endpoint supports the authentication method you configure. TLS should be enabled for production use.

12. Implementing API Security

Feature	Description	Implementation
Authentication	Ensures only authorized users can access the API	Use OAuth2 or JWT tokens for authentication
Authorization	Controls what actions authenticated users can perform	Implement role-based access control (RBAC)
Rate Limiting	Prevents abuse by limiting API requests per user	Use Prometheus's built-in rate-limiting or external middleware

Example: Setting up JWT Authentication

// Sample JWT setup for Prometheus API
const jwt = require('jsonwebtoken');
const secretKey = 'your-secret-key';

function generateToken(user) {
  return jwt.sign({ id: user.id, role: user.role }, secretKey, { expiresIn: '1h' });
}

function verifyToken(token) {
  return jwt.verify(token, secretKey);
}

Note: Ensure tokens are securely stored and transmitted over HTTPS.

Warning: Never expose secret keys in client-side code or logs.