nginx

nginx supports forward auth through the auth_request module.

Caution

The agent ignores X-Forwarded-For / X-Forwarded-Host unless the caller’s source IP is listed in proxy.trusted_proxies. Add your nginx host’s IP (e.g. 100.64.0.1/32 or the LAN IP it binds to) before forward auth will see real client tunnel IPs.

Example configuration

# Internal auth subrequest location
location = /atreo-auth {
    internal;
    proxy_pass http://100.64.0.1:9091/auth;
    proxy_pass_request_body off;
    proxy_set_header Content-Length "";
    proxy_set_header X-Forwarded-For $remote_addr;
    proxy_set_header X-Forwarded-Host $host;
}

server {
    listen 100.64.0.1:443 ssl;
    server_name jellyfin.alice.atreo.link;

    ssl_certificate     /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    # Forward auth check
    auth_request /atreo-auth;

    # Pass auth headers to the upstream app
    auth_request_set $auth_user $upstream_http_x_auth_user;
    auth_request_set $auth_member_id $upstream_http_x_auth_member_id;
    auth_request_set $auth_role $upstream_http_x_auth_role;

    location / {
        proxy_pass http://localhost:8096;
        proxy_set_header Host $host;
        proxy_set_header X-Auth-User $auth_user;
        proxy_set_header X-Auth-Member-ID $auth_member_id;
        proxy_set_header X-Auth-Role $auth_role;
    }
}

Caution

The auth_request module is not included in all nginx builds. Verify it’s available with nginx -V 2>&1 | grep auth_request.

Wildcard server block

To handle multiple apps with a single server block using a map:

map $host $upstream {
    jellyfin.alice.atreo.link  http://localhost:8096;
    immich.alice.atreo.link    http://localhost:2283;
    default                     "";
}

server {
    listen 100.64.0.1:443 ssl;
    server_name *.alice.atreo.link;

    ssl_certificate     /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    auth_request /atreo-auth;

    location / {
        if ($upstream = "") {
            return 404;
        }
        proxy_pass $upstream;
        proxy_set_header Host $host;
    }
}

TLS certificates

If you’re using nginx as your proxy, you can either:

1. Use the certificates that atreoAGENT obtains automatically (found in /var/lib/atreoagent/certs/)
2. Obtain your own certificates through your preferred method

The agent’s certificates are wildcard certs for *.<subdomain>.<base-domain>, so they work for all your apps.