diff --git a/docs/sources/operations/authentication.md b/docs/sources/operations/authentication.md index 9244773adb..679bf0037a 100644 --- a/docs/sources/operations/authentication.md +++ b/docs/sources/operations/authentication.md @@ -15,7 +15,7 @@ By default the Loki Helm chart includes a default reverse proxy configuration, u A list of open-source reverse proxies you can use: - [HAProxy](https://docs.haproxy.org/ ) -- [NGINX](https://docs.nginx.com/nginx/) using their [guide on restricting access with HTTP basic authentication](https://docs.nginx.com/nginx/admin-guide/security-controls/configuring-http-basic-authentication/) +- [nginx](https://docs.nginx.com/nginx/) using their [guide on restricting access with HTTP basic authentication](https://docs.nginx.com/nginx/admin-guide/security-controls/configuring-http-basic-authentication/) - [OAuth2 proxy](https://oauth2-proxy.github.io/oauth2-proxy/) - [Pomerium](https://www.pomerium.com/docs), which has a [guide for securing Grafana](https://www.pomerium.com/docs/guides/grafana) @@ -27,3 +27,157 @@ For more information, read the [multi-tenancy](https://grafana.com/docs/loki//send-data/promtail/configuration/). + +## Enable basic authentication for Loki using nginx + +This section describes the process of enabling basic authentication for Loki using [nginx](https://docs.nginx.com/nginx/). + +### Prerequisites + +* A running Loki instance +* A running nginx instance + +### Configure nginx + +You must create a new nginx configuration file for the Loki instance. + +This example assumes the following: + +* nginx is running in `/opt/homebrew` +* Loki is running on port 3100 on the local machine +* Your Loki tenant id is `fake` +* The configuration file is named `/opt/homebrew/etc/nginx/loki.conf` + +If you used different configuration parameters for Loki, adjust the examples to match your configuration. + +`loki.conf` configuration: + +```conf +upstream loki { + server 127.0.0.1:3100; + keepalive 15; +} + +server { + listen 80; + server_name loki.localhost; + + auth_basic "loki auth"; + auth_basic_user_file /opt/homebrew/etc/nginx/passwords; + + location / { + proxy_read_timeout 1800s; + proxy_connect_timeout 1600s; + proxy_pass http://loki; + proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection "Keep-Alive"; + proxy_set_header Proxy-Connection "Keep-Alive"; + proxy_redirect off; + } + + location /ready { + proxy_pass http://loki; + proxy_http_version 1.1; + proxy_set_header Connection "Keep-Alive"; + proxy_set_header Proxy-Connection "Keep-Alive"; + proxy_redirect off; + auth_basic "off"; + } +} +``` + +This configuration must be included in your main nginx configuration, for example, by including it in `nginx.conf` like: + +``` +include /opt/homebrew/etc/nginx/loki.conf; +``` + +Restart the nginx server to ensure all configuration changes are updated. + +### Validate your nginx configuration + +To validate the nginx configuration for Loki, you can send a `curl` request to two endpoints: + +* The `/ready` endpoint, which is not protected by a basic authentication mechanism. + +```curl +% curl -i http://loki.localhost/ready + +HTTP/1.1 200 OK +Server: nginx/1.29.2 +Date: Thu, 16 Oct 2025 14:28:31 GMT +Content-Type: text/plain; charset=utf-8 +Content-Length: 6 +Connection: keep-alive +X-Content-Type-Options: nosniff + +ready +``` + +* The `/` endpoint, which is protected by a basic authentication mechanism. + +```curl +curl -i http://loki.localhost/ + +HTTP/1.1 401 Unauthorized +Server: nginx/1.29.2 +Date: Thu, 16 Oct 2025 14:32:43 GMT +Content-Type: text/html +Content-Length: 179 +Connection: keep-alive +WWW-Authenticate: Basic realm="loki auth" + + +401 Authorization Required + +

401 Authorization Required

+
nginx/1.29.2
+ + +``` + +### Update passwords + +The password file can be seeded using whatever mechanism you may use for other web services. + +In this example, `htpasswd` is utilized: + +``` +% htpasswd -c /opt/homebrew/etc/nginx/passwords loki123 + +New password: +Re-type new password: +Adding password for user loki123 +``` + +Restart the nginx server to ensure all configuration changes are updated. + +### Validate passwords + +Enter your password into a temporary file, such as: + +``` +% vi lokipw +``` + +Then, store it as an environment variable:: + +``` +% pass=$(cat lokipw) +``` + +You can validate basic authentication is then working by issuing a curl command to the protected resource: + +```curl +curl -i -u loki123:$pass -H "X-Scope-OrgID:fake" "http://loki.localhost/loki/api/v1/labels" + +HTTP/1.1 200 OK +Server: nginx/1.29.2 +Date: Thu, 16 Oct 2025 14:46:09 GMT +Content-Type: application/json; charset=UTF-8 +Content-Length: 21 +Connection: keep-alive + +{"status":"success"} +```