docs/sources/operations/authentication.md
Grafana Loki does not come with any included authentication layer. You must run an authenticating reverse proxy in front of your services.
The simple scalable and microservices deployment modes require a reverse proxy to be deployed in front of Loki, to direct client API requests to the various components.
By default the Loki Helm chart includes a default reverse proxy configuration, using an nginx container to handle routing traffic and authorization.
A list of open-source reverse proxies you can use:
{{< admonition type="note" >}}
When using Loki in multi-tenant mode, Loki requires the HTTP header
X-Scope-OrgID to be set to a string identifying the tenant; the responsibility
of populating this value should be handled by the authenticating reverse proxy.
For more information, read the multi-tenancy documentation.{{< /admonition >}}
For information on configuring authentication for your log shipping agent, see the Grafana Alloy documentation.
This section describes the process of enabling basic authentication for Loki using nginx.
You must create a new nginx configuration file for the Loki instance.
This example assumes the following:
/opt/homebrewfake/opt/homebrew/etc/nginx/loki.confIf you used different configuration parameters for Loki, adjust the examples to match your configuration.
loki.conf configuration:
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.
To validate the nginx configuration for Loki, you can send a curl request to two endpoints:
/ready endpoint, which is not protected by a basic authentication mechanism.% 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
/ endpoint, which is protected by a basic authentication mechanism.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"
<html>
<head><title>401 Authorization Required</title></head>
<body>
<center><h1>401 Authorization Required</h1></center>
<hr><center>nginx/1.29.2</center>
</body>
</html>
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.
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 -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"}