paskia/docs/proxy/nginx.md

Nginx Forward-Auth

/auth/api/forward · Proxy guides

This guide uses the Nginx auth_request module to ask Paskia whether each request is allowed before proxying it to your backend.

Overview

server {
    listen 80;
    server_name app.example.com;

    # 1. Proxy /auth/ to Paskia (HTTP + WebSocket).
    location /auth/ {
        proxy_pass http://localhost:4401;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
    }

    # 2. All other paths are protected.
    location / {
        auth_request /auth-internal;

        # 3. Capture the Remote-* headers from the auth response and
        #    pass them to the backend request.
        auth_request_set $remote_user        $upstream_http_remote_user;
        auth_request_set $remote_name        $upstream_http_remote_name;
        auth_request_set $remote_groups      $upstream_http_remote_groups;
        auth_request_set $remote_org         $upstream_http_remote_org;
        auth_request_set $remote_org_name    $upstream_http_remote_org_name;
        auth_request_set $remote_role        $upstream_http_remote_role;
        auth_request_set $remote_role_name   $upstream_http_remote_role_name;
        auth_request_set $remote_session_exp $upstream_http_remote_session_expires;
        auth_request_set $remote_credential  $upstream_http_remote_credential;
        auth_request_set $remote_public      $upstream_http_remote_public;

        proxy_set_header Remote-User             $remote_user;
        proxy_set_header Remote-Name             $remote_name;
        proxy_set_header Remote-Groups           $remote_groups;
        proxy_set_header Remote-Org              $remote_org;
        proxy_set_header Remote-Org-Name         $remote_org_name;
        proxy_set_header Remote-Role             $remote_role;
        proxy_set_header Remote-Role-Name        $remote_role_name;
        proxy_set_header Remote-Session-Expires  $remote_session_exp;
        proxy_set_header Remote-Credential       $remote_credential;
        proxy_set_header Remote-Public           $remote_public;

        # 4. The proxy_set_header lines above override any client-supplied
        #    Remote-* headers, so the backend receives only the values from
        #    Paskia's auth response.

        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }

    # 5. Internal endpoint used by auth_request.
    location = /auth-internal {
        internal;
        proxy_pass http://localhost:4401/auth/api/forward?perm=myapp:login;
        proxy_http_version 1.1;
        proxy_pass_request_body off;
        proxy_set_header Content-Length "";
        proxy_set_header X-Forwarded-Method $request_method;
        proxy_set_header X-Forwarded-Uri $request_uri;
        proxy_set_header Host $host;
        proxy_set_header Cookie $http_cookie;
        proxy_set_header Accept $http_accept;
        # Drop hop-by-hop headers that must not reach the auth subrequest.
        proxy_set_header Connection "";
        proxy_set_header Upgrade "";
        proxy_set_header Transfer-Encoding "";
        proxy_set_header Keep-Alive "";
        proxy_set_header Proxy-Connection "";
        proxy_set_header TE "";
    }
}

# WebSocket upgrade map.
map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

What the configuration does

1. /auth/ is proxied straight to Paskia. The Upgrade and Connection headers are passed through so WebSocket endpoints such as /auth/ws/authenticate work.
2. / is protected by auth_request /auth-internal. Nginx makes an internal subrequest to that location before proxying the original request to the app.
3. auth_request_set captures each Remote-* header from the Paskia response. Nginx does not have wildcard capture, so every header must be listed explicitly. The captured values are then attached to the backend request with proxy_set_header.
4. The proxy_set_header lines override any Remote-* headers the client might have sent, so the backend can trust the headers that come from Paskia.
5. /auth-internal is the actual forward-auth call. It must:
   • point to /auth/api/forward,
   • not forward the request body (proxy_pass_request_body off;),
   • pass Host, Cookie, Accept, X-Forwarded-Method, and X-Forwarded-Uri,
   • strip hop-by-hop headers.

Adjusting requirements

Change the query string on the proxy_pass line inside /auth-internal to require different permissions or recent authentication:

proxy_pass http://localhost:4401/auth/api/forward?perm=myapp:login;
proxy_pass http://localhost:4401/auth/api/forward?perm=myapp:admin&max_age=5min;
proxy_pass http://localhost:4401/auth/api/forward?"";

The last form (?"") requires only authentication and no specific permission. See perm argument and max_age argument for details.

Public paths

To leave some paths unprotected (for example /.well-known/ or /static/), add location blocks before the protected location / block:

location /.well-known/ {
    root /var/www;
}

location /static/ {
    root /var/www;
}

Public access

For routes where anonymous visitors are allowed but logged-in users should still be identified, add public=1 to the auth subrequest URI inside /auth-internal:

proxy_pass http://localhost:4401/auth/api/forward?public=1;
proxy_pass http://localhost:4401/auth/api/forward?public=1&perm=myapp:reports;

The auth check then always returns 204 (except reauth with max_age, which still returns the 401 auth flow), and Remote-Public marks each request as anonymous, forbidden or authenticated. It is captured and forwarded by the auth_request_set $remote_public / proxy_set_header Remote-Public lines added in the overview above — the backend always runs and must check Remote-Public before treating the request as authorized. See public access and trusted headers.

Notes

• Nginx auth_request always makes the auth subrequest with the same HTTP method as the original request, but the body is suppressed by the configuration above. Paskia uses the X-Forwarded-Method and X-Forwarded-Uri headers for logging.
• The auth_request_set variables are empty when the auth request fails, so on 401/403 the backend is never contacted; Nginx returns Paskia's response directly.
• For HTTPS, add listen 443 ssl; and your certificate configuration as usual.