Skip to main content
Version: 10.0

Metrics Authentication

The metrics endpoint requires authentication by default to protect internal server metrics. Access is controlled by a security filter which supports two authentication methods.

Endpoint URL​

The metrics endpoint is available at:

GET http://PORTAL_URL/webPDF/metrics
Context Path

The endpoint URL includes the context path (default: webPDF). If you have changed the context path, adjust the URL accordingly:

GET http://PORTAL_URL/<your-context-path>/metrics

Authentication Methods​

Standard HTTP Basic Authentication with username and password.

GET http://PORTAL_URL/webPDF/metrics
Authorization: Basic <base64(username:password)>

Configuration​

Environment Settings:

WEBPDF_METRICS_AUTH_USERNAME=prometheus
WEBPDF_METRICS_AUTH_PASSWORD=your-secure-password
note

These are webPDF-specific environment settings using the WEBPDF_METRICS_ prefix.

Example Usage​

curl:

curl -u prometheus:your-secure-password http://localhost:8080/webPDF/metrics

wget:

wget --user=prometheus --password=your-secure-password http://localhost:8080/webPDF/metrics

2. Bearer Token Authentication​

API token-based authentication for programmatic access.

GET http://PORTAL_URL/webPDF/metrics
Authorization: Bearer <your-api-token>

Configuration​

Environment Settings:

WEBPDF_METRICS_AUTH_TOKEN=your-secure-api-token

Example Usage​

curl:

curl -H "Authorization: Bearer your-secure-api-token" http://localhost:8080/webPDF/metrics

Python:

import requests

headers = {
    'Authorization': 'Bearer your-secure-api-token'
}
response = requests.get('http://localhost:8080/webPDF/metrics', headers=headers)
print(response.text)

Configuration Priority​

The authentication filter follows this priority order when loading credentials:

  1. Environment Settings (highest priority)

    • WEBPDF_METRICS_AUTH_USERNAME / WEBPDF_METRICS_AUTH_PASSWORD
    • WEBPDF_METRICS_AUTH_TOKEN

  2. XML Configuration (conf/application.xml)

  3. Default Values (lowest priority)

    • Username: prometheus (only if password is set)
    • Password: none
    • Token: none
Both Methods Supported

If both Basic Auth credentials and a Bearer Token are configured, clients can use either method. The filter will accept both.

Disabling Authentication​

Development Only

Disabling authentication exposes internal server metrics publicly. Only disable in development or trusted network environments.

To disable authentication requirement, configure in conf/application.xml:

<application>
  <metrics enabled="true">
    <auth enabled="false" />
  </metrics>
</application>

When authentication is disabled:

  • No Authorization header is required
  • The endpoint is publicly accessible
  • A warning is logged at server startup

Error Responses​

401 Unauthorized​

Missing or invalid credentials:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Basic realm="Metrics", Bearer
Content-Type: text/plain

Unauthorized: Invalid credentials

The WWW-Authenticate header indicates which authentication methods are supported:

  • Basic realm="Metrics" - Basic Authentication is configured
  • Bearer - Bearer Token authentication is configured
  • Both listed - Client can use either method

404 Not Found​

Metrics endpoint is disabled:

HTTP/1.1 404 Not Found

Check configuration: <application endpointEnabled="true" /> inside the <metrics> element.

503 Service Unavailable​

Metrics manager not initialized:

HTTP/1.1 503 Service Unavailable

Check that metrics are globally enabled: <metrics enabled="true">

Security Best Practices​

Production Deployments​

  1. Use Strong Credentials

    • Generate cryptographically secure passwords (min. 32 characters)
    • Use random tokens (e.g., UUID or base64-encoded random bytes)

  2. Store Credentials Securely

    • Use environment variables, not hardcoded values
    • Consider secrets management systems (HashiCorp Vault, AWS Secrets Manager)
    • Restrict file permissions on credential files

  3. Enable TLS

    • Always use HTTPS for metrics endpoint in production
    • Configure TLS before exposing metrics
    • Credentials transmitted over HTTP are visible in network traffic

  4. Rotate Credentials Regularly

    • Change passwords/tokens periodically (quarterly recommended)
    • Update Prometheus configuration after rotation

Network Security​

  1. Firewall Rules

    • Restrict metrics endpoint to monitoring servers only
    • Block external access if not needed

  2. Reverse Proxy

    • Consider placing metrics behind reverse proxy
    • Additional authentication layer possible

  3. IP Whitelisting

    • Configure firewall to allow only Prometheus server IPs

Troubleshooting​

Credentials Not Working​

  1. Check Environment Settings:

    # Linux/Mac
    echo $WEBPDF_METRICS_AUTH_USERNAME
    echo $WEBPDF_METRICS_AUTH_PASSWORD
    echo $WEBPDF_METRICS_AUTH_TOKEN

    # Windows
    echo %WEBPDF_METRICS_AUTH_USERNAME%
    echo %WEBPDF_METRICS_AUTH_PASSWORD%
    echo %WEBPDF_METRICS_AUTH_TOKEN%

  2. Check Server Logs:

    Metrics authentication enabled: Basic Auth (username=prometheus)
    Metrics authentication enabled: Bearer Token

No Credentials Configured Warning​

If you see this warning:

Metrics authentication is required but no credentials configured!

The filter falls back to unauthenticated access (fail-open) for development convenience. Configure credentials before production deployment.

Wrong Authentication Method​

If Prometheus uses Bearer Token but only Basic Auth is configured (or vice versa), you'll get 401 Unauthorized. Check the WWW-Authenticate header to see which methods are available.

See Also​