Skip to content

Commit 9d9e3ae

Browse files
loki-gh-app[bot]JStickler
loki-gh-app[bot]
and
JStickler
authored
docs: Update Auth topic with nginx instructions (backport release-3.4.x) (#19526)
Co-authored-by: J Stickler <julie.stickler@grafana.com>
1 parent 4deeac9 commit 9d9e3ae

File tree

1 file changed

+155
-1
lines changed

1 file changed

+155
-1
lines changed

‎docs/sources/operations/authentication.md‎

Lines changed: 155 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ By default the Loki Helm chart includes a default reverse proxy configuration, u
1515
A list of open-source reverse proxies you can use:
1616

1717
- [HAProxy](https://docs.haproxy.org/ )
18-
- [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/)
18+
- [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/)
1919
- [OAuth2 proxy](https://oauth2-proxy.github.io/oauth2-proxy/)
2020
- [Pomerium](https://www.pomerium.com/docs), which has a [guide for securing Grafana](https://www.pomerium.com/docs/guides/grafana)
2121

@@ -27,3 +27,157 @@ For more information, read the [multi-tenancy](https://grafana.com/docs/loki/<LO
2727

2828
For information on authenticating Promtail, see the documentation for [how to
2929
configure Promtail](https://grafana.com/docs/loki/<LOKI_VERSION>/send-data/promtail/configuration/).
30+
31+
## Enable basic authentication for Loki using nginx
32+
33+
This section describes the process of enabling basic authentication for Loki using [nginx](https://docs.nginx.com/nginx/).
34+
35+
### Prerequisites
36+
37+
* A running Loki instance
38+
* A running nginx instance
39+
40+
### Configure nginx
41+
42+
You must create a new nginx configuration file for the Loki instance.
43+
44+
This example assumes the following:
45+
46+
* nginx is running in `/opt/homebrew`
47+
* Loki is running on port 3100 on the local machine
48+
* Your Loki tenant id is `fake`
49+
* The configuration file is named `/opt/homebrew/etc/nginx/loki.conf`
50+
51+
If you used different configuration parameters for Loki, adjust the examples to match your configuration.
52+
53+
`loki.conf` configuration:
54+
55+
```conf
56+
upstream loki {
57+
server 127.0.0.1:3100;
58+
keepalive 15;
59+
}
60+
61+
server {
62+
listen 80;
63+
server_name loki.localhost;
64+
65+
auth_basic "loki auth";
66+
auth_basic_user_file /opt/homebrew/etc/nginx/passwords;
67+
68+
location / {
69+
proxy_read_timeout 1800s;
70+
proxy_connect_timeout 1600s;
71+
proxy_pass http://loki;
72+
proxy_http_version 1.1;
73+
proxy_set_header Upgrade $http_upgrade;
74+
proxy_set_header Connection "Keep-Alive";
75+
proxy_set_header Proxy-Connection "Keep-Alive";
76+
proxy_redirect off;
77+
}
78+
79+
location /ready {
80+
proxy_pass http://loki;
81+
proxy_http_version 1.1;
82+
proxy_set_header Connection "Keep-Alive";
83+
proxy_set_header Proxy-Connection "Keep-Alive";
84+
proxy_redirect off;
85+
auth_basic "off";
86+
}
87+
}
88+
```
89+
90+
This configuration must be included in your main nginx configuration, for example, by including it in `nginx.conf` like:
91+
92+
```
93+
include /opt/homebrew/etc/nginx/loki.conf;
94+
```
95+
96+
Restart the nginx server to ensure all configuration changes are updated.
97+
98+
### Validate your nginx configuration
99+
100+
To validate the nginx configuration for Loki, you can send a `curl` request to two endpoints:
101+
102+
* The `/ready` endpoint, which is not protected by a basic authentication mechanism.
103+
104+
```curl
105+
% curl -i http://loki.localhost/ready
106+
107+
HTTP/1.1 200 OK
108+
Server: nginx/1.29.2
109+
Date: Thu, 16 Oct 2025 14:28:31 GMT
110+
Content-Type: text/plain; charset=utf-8
111+
Content-Length: 6
112+
Connection: keep-alive
113+
X-Content-Type-Options: nosniff
114+
115+
ready
116+
```
117+
118+
* The `/` endpoint, which is protected by a basic authentication mechanism.
119+
120+
```curl
121+
curl -i http://loki.localhost/
122+
123+
HTTP/1.1 401 Unauthorized
124+
Server: nginx/1.29.2
125+
Date: Thu, 16 Oct 2025 14:32:43 GMT
126+
Content-Type: text/html
127+
Content-Length: 179
128+
Connection: keep-alive
129+
WWW-Authenticate: Basic realm="loki auth"
130+
131+
<html>
132+
<head><title>401 Authorization Required</title></head>
133+
<body>
134+
<center><h1>401 Authorization Required</h1></center>
135+
<hr><center>nginx/1.29.2</center>
136+
</body>
137+
</html>
138+
```
139+
140+
### Update passwords
141+
142+
The password file can be seeded using whatever mechanism you may use for other web services.
143+
144+
In this example, `htpasswd` is utilized:
145+
146+
```
147+
% htpasswd -c /opt/homebrew/etc/nginx/passwords loki123
148+
149+
New password:
150+
Re-type new password:
151+
Adding password for user loki123
152+
```
153+
154+
Restart the nginx server to ensure all configuration changes are updated.
155+
156+
### Validate passwords
157+
158+
Enter your password into a temporary file, such as:
159+
160+
```
161+
% vi lokipw
162+
```
163+
164+
Then, store it as an environment variable::
165+
166+
```
167+
% pass=$(cat lokipw)
168+
```
169+
170+
You can validate basic authentication is then working by issuing a curl command to the protected resource:
171+
172+
```curl
173+
curl -i -u loki123:$pass -H "X-Scope-OrgID:fake" "http://loki.localhost/loki/api/v1/labels"
174+
175+
HTTP/1.1 200 OK
176+
Server: nginx/1.29.2
177+
Date: Thu, 16 Oct 2025 14:46:09 GMT
178+
Content-Type: application/json; charset=UTF-8
179+
Content-Length: 21
180+
Connection: keep-alive
181+
182+
{"status":"success"}
183+
```

0 commit comments

Comments
 (0)