LeoVasanko/paskia
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

Update API and proxy docs

Browse Source
This commit is contained in:
LeoVasanko
2026-08-10 21:35:46 +00:00
parent 6f5287e070
commit 00ef0ae2e7
15 changed files with 1107 additions and 123 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/proxy/apisix.md
+163
View File
@@ -0,0 +1,163 @@
# Apache APISIX Forward-Auth
[`/auth/api/forward`](../api/forward.md) · [Proxy guides](index.md)
This guide uses the Apache APISIX [`forward-auth`](https://apisix.apache.org/docs/apisix/plugins/forward-auth/) plugin to ask Paskia whether each request is allowed.
## Overview
APISIX adds the standard `X-Forwarded-*` headers automatically, but we still tell the plugin to forward `Host`, `Cookie`, and `Accept` from the client request. On a `204` response from Paskia we copy the `Remote-*` headers to the backend request.
## Admin API example
```sh
# Route that proxies /auth/ to Paskia without forward-auth.
curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
-H "X-API-KEY: ${admin_key}" \
-H 'Content-Type: application/json' \
-d '{
"id": "paskia-auth-ui",
"uri": "/auth/*",
"upstream": {
"nodes": { "localhost:4401": 1 },
"type": "roundrobin"
}
}'
# Protected route that uses Paskia forward-auth.
curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
-H "X-API-KEY: ${admin_key}" \
-H 'Content-Type: application/json' \
-d '{
"id": "app-protected",
"uri": "/*",
"priority": 10,
"plugins": {
"forward-auth": {
"uri": "http://localhost:4401/auth/api/forward?perm=myapp:login",
"request_headers": [
"Host",
"Cookie",
"Accept",
"X-Forwarded-Method",
"X-Forwarded-Uri",
"X-Forwarded-Host",
"X-Forwarded-Proto",
"X-Forwarded-For"
],
"upstream_headers": [
"Remote-User",
"Remote-Name",
"Remote-Groups",
"Remote-Org",
"Remote-Org-Name",
"Remote-Role",
"Remote-Role-Name",
"Remote-Session-Expires",
"Remote-Credential"
]
}
},
"upstream": {
"nodes": { "localhost:3000": 1 },
"type": "roundrobin"
}
}'
```
The `paskia-auth-ui` route has a higher priority (`priority` defaults to the same value for both routes; you can also rely on the more specific `/auth/*` URI matching first). Because it does not use the `forward-auth` plugin, users can reach the login/profile pages without already being authenticated.
## ADC / declarative example
```yaml
services:
- name: paskia-auth-ui
routes:
- name: auth-route
uris:
- /auth/*
upstream:
type: roundrobin
nodes:
- host: localhost
port: 4401
weight: 1
- name: app-protected
routes:
- name: app-route
uris:
- /*
plugins:
forward-auth:
uri: http://localhost:4401/auth/api/forward?perm=myapp:login
request_headers:
- Host
- Cookie
- Accept
- X-Forwarded-Method
- X-Forwarded-Uri
- X-Forwarded-Host
- X-Forwarded-Proto
- X-Forwarded-For
upstream_headers:
- Remote-User
- Remote-Name
- Remote-Groups
- Remote-Org
- Remote-Org-Name
- Remote-Role
- Remote-Role-Name
- Remote-Session-Expires
- Remote-Credential
upstream:
type: roundrobin
nodes:
- host: localhost
port: 3000
weight: 1
```
Apply it with:
```sh
adc sync -f paskia.yaml
```
## What APISIX sends to Paskia
APISIX automatically adds these headers to the auth request:
| Header | Value |
|---|---|
| `X-Forwarded-Method` | Original HTTP method |
| `X-Forwarded-Proto` | Request scheme (`http`/`https`) |
| `X-Forwarded-Host` | Original host |
| `X-Forwarded-Uri` | Original request URI |
| `X-Forwarded-For` | Client IP address |
We list them again in `request_headers` to make sure they are not accidentally filtered out when the list is explicit.
## Response headers
`upstream_headers` lists the `Remote-*` headers that APISIX copies from the auth response to the backend request. The plugin does not support a wildcard here, so each header must be named.
If you want Paskia's failure-response headers (such as `Content-Type` or `Set-Cookie`) to reach the client, list them in `client_headers`. For Paskia this is usually not needed; the response body already contains the JSON auth URL or the HTML login page.
## Adjusting requirements
Change the `uri` query string to require different permissions or recent authentication:
```yaml
uri: http://localhost:4401/auth/api/forward?perm=myapp:login
uri: http://localhost:4401/auth/api/forward?perm=myapp:admin&max_age=5min
uri: http://localhost:4401/auth/api/forward
```
The last form requires only authentication. See [perm argument](../api/perm.md) and [max_age argument](../api/max-age.md).
## Notes
- The auth request is `GET` by default. Since the `forward-auth` plugin does not forward the request body unless `request_method` is set to `POST`, the default `GET` is the right choice for Paskia.
- Hop-by-hop headers are handled by APISIX when it builds the auth request, so no extra configuration is needed for `Connection`/`Upgrade`.
- If Paskia is running on a different host, replace `localhost:4401` with the Paskia service address. For a dedicated authentication host (`--auth-host`), route `auth.example.com` to Paskia instead of `/auth/`.
docs/proxy/caddy.md
+81
View File
@@ -0,0 +1,81 @@
# Paskia Caddy Configuration
[`/auth/api/forward`](../api/forward.md) · [Proxy guides](index.md)
[Caddy](https://caddyserver.com/) is a modern web server that makes setting up web services easy. We provide a few Caddy snippets that make the configuration even easier, although the `forward_auth` directive of Caddy can be used directly as well. Place the [auth folder](../../caddy/auth) with the snippets `require` and `setup` where your config file is (e.g. `/etc/caddy/auth`)
What these snippets do
- `setup`: Mount the auth UI at `/auth/` proxying to `:4401`
- `require`: Use `/auth/api/forward` for access control
- Render a login page or a permission denied page if needed (without changing URL)
Your backend may not use authentication at all, or it can make use of the user information passed via `Remote-*` headers by the authentication system, see [trusted headers](../Headers.md) for details.
We assume the normal unprotected **Caddyfile** for your site looks like this:
```caddyfile
app.example.com {
@public path /.well-known/* /favicon.ico
handle @public {
root * /var/www/
file_server
}
handle {
reverse_proxy :3000 # Your app backend
}
}
```
Note: We use the `handle @name` approach rather than `handle_path` to keep the path unaltered. Unlike bare directives, these blocks will be tried in sequence and each can contain what you'd typically put in your site definition (by default `reverse_proxy` takes precedence and nothing reaches the static files).
We will adapt from this to protect your app.
### Protect your site (auth/setup, auth/require)
```caddyfile
app.example.com {
import auth/setup
@public path /.well-known/* /favicon.ico
handle @public {
root * /var/www/
file_server
}
@reports path /reports
handle @reports {
import auth/require perm=myapp:reports
reverse_proxy :3000
}
handle {
import auth/require max-age=12h
reverse_proxy :3000
}
}
```
The above setup allows unauthenticated access to certain files, then implements two different access controls for your backend app depending on which path is accessed. Note that the perm and max-age options may be combined, e.g. `perm=myapp:admin&max-age=5min` on a very sensitive endpoint. This will require additional authentication if the passkey hasn't been used in the last 5 minutes (automatic session renewals don't affect this). Use `""` if you only want the user to be authenticated with no time or perm requirements.
### Dedicated Authentication Site
When you setup a separate subdomain for the authentication site, just add to your config another section for the auth host:
```caddyfile
auth.example.com {
reverse_proxy :4401
}
```
Remember to specify `paskia serve --auth-host auth.example.com` to restrict the authentication services to this domain.
Note that we still reserve `/auth/` on each site for logout page and any APIs your application may require, while full user profile and global options are only available on the auth host.
Paskia does not require CORS configuration, but it can access the authentication and registration of auth host WS API from the other sites as WebSockets don't require any CORS.
### Override the paskia backend address (AUTH_UPSTREAM)
By default, the auth service is contacted at localhost port 4401. You can point Caddy to a different address by setting the `AUTH_UPSTREAM` environment variable for Caddy.
If unset, the snippets use `:4401` by default.
docs/proxy/envoy.md
+170
View File
@@ -0,0 +1,170 @@
# Envoy External Authorization (ext_authz)
[`/auth/api/forward`](../api/forward.md) · [Proxy guides](index.md)
This guide uses Envoy's [external authorization filter](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/ext_authz_filter) (`ext_authz`) to ask Paskia whether each request is allowed.
## Overview
Envoy's `ext_authz` HTTP filter calls an external HTTP service before forwarding a request to the upstream. The filter needs to know which headers from the original request to send to Paskia, and which headers from Paskia's response to add to the upstream request or to the client response.
A minimal static configuration looks like this:
```yaml
static_resources:
listeners:
- name: app_listener
address:
socket_address:
address: 0.0.0.0
port_value: 8080
filter_chains:
- filters:
- name: envoy.filters.network.http_connection_manager
typed_config:
"@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
stat_prefix: ingress_http
use_remote_address: true
route_config:
name: local_route
virtual_hosts:
- name: app
domains: ["*"]
routes:
# Pass /auth/ straight to Paskia, bypassing ext_authz.
- match:
prefix: "/auth/"
route:
cluster: paskia
typed_per_filter_config:
envoy.filters.http.ext_authz:
"@type": type.googleapis.com/envoy.extensions.filters.http.ext_authz.v3.ExtAuthzPerRoute
disabled: true
# Protect everything else.
- match:
prefix: "/"
route:
cluster: app_backend
http_filters:
- name: envoy.filters.http.ext_authz
typed_config:
"@type": type.googleapis.com/envoy.extensions.filters.http.ext_authz.v3.ExtAuthz
transport_api_version: v3
http_service:
server_uri:
uri: localhost:4401
cluster: paskia
timeout: 0.5s
# Send every auth check to /auth/api/forward with the
# required permission, regardless of the original path.
path_override: "/auth/api/forward?perm=myapp:login"
authorization_request:
allowed_headers:
patterns:
- exact: Host
- exact: Cookie
- exact: Accept
# Add the headers Paskia logs / expects.
headers_to_add:
- key: X-Forwarded-Method
value: "%REQ(:METHOD)%"
- key: X-Forwarded-Uri
value: "%REQ(:PATH)%"
- key: X-Forwarded-Proto
value: "%REQ(:SCHEME)%"
- key: X-Forwarded-For
value: "%REQ(X-Forwarded-For)%"
authorization_response:
# Forward every Remote-* header to the backend.
allowed_upstream_headers:
patterns:
- prefix: Remote-
# Forward the response Content-Type to the client on 401/403.
allowed_client_headers:
patterns:
- exact: Content-Type
failure_mode_allow: false
- name: envoy.filters.http.router
typed_config:
"@type": type.googleapis.com/envoy.extensions.filters.http.router.v3.Router
clusters:
- name: app_backend
connect_timeout: 0.25s
type: logical_dns
lb_policy: round_robin
load_assignment:
cluster_name: app_backend
endpoints:
- lb_endpoints:
- endpoint:
address:
socket_address:
address: localhost
port_value: 3000
- name: paskia
connect_timeout: 0.25s
type: logical_dns
lb_policy: round_robin
load_assignment:
cluster_name: paskia
endpoints:
- lb_endpoints:
- endpoint:
address:
socket_address:
address: localhost
port_value: 4401
```
## Important configuration details
- **`path_override`** — the auth request always goes to `/auth/api/forward?perm=myapp:login`, no matter which path the client requested. The original path is sent in `X-Forwarded-Uri` for Paskia to log.
- **`authorization_request.allowed_headers`** — Envoy only forwards the headers you explicitly allow. We allow `Host`, `Cookie`, and `Accept`. The `X-Forwarded-*` headers are added via `headers_to_add` so they are based on Envoy's view of the request, not spoofed client values.
- **`headers_to_add`** — Envoy supports substitution format strings such as `%REQ(:METHOD)%` and `%REQ(:PATH)%`. These set the headers Paskia uses for logging and host validation.
- **`authorization_response.allowed_upstream_headers`** — `prefix: Remote-` tells Envoy to copy every response header starting with `Remote-` to the upstream request. This also removes any client-supplied `Remote-*` headers, so the backend can trust them.
- **`authorization_response.allowed_client_headers`** — on a 401/403 response, Envoy forwards only the allowed response headers to the client. Paskia returns HTML or JSON with a `Content-Type` header, so we allow that. (Paskia does not set cookies on the forward-auth response.)
- **`typed_per_filter_config`** on the `/auth/` route disables `ext_authz` so users can reach the login/profile pages without already being authenticated.
## Per-route requirements
Different routes often need different permissions or `max_age` values. Use `typed_per_filter_config` on each route to override the `http_service.path_override`:
```yaml
routes:
- match:
prefix: "/reports"
route:
cluster: app_backend
typed_per_filter_config:
envoy.filters.http.ext_authz:
"@type": type.googleapis.com/envoy.extensions.filters.http.ext_authz.v3.ExtAuthzPerRoute
check_settings:
http_service:
path_override: "/auth/api/forward?perm=myapp:reports&max_age=5min"
- match:
prefix: "/"
route:
cluster: app_backend
typed_per_filter_config:
envoy.filters.http.ext_authz:
"@type": type.googleapis.com/envoy.extensions.filters.http.ext_authz.v3.ExtAuthzPerRoute
check_settings:
http_service:
path_override: "/auth/api/forward?perm=myapp:login"
```
See [perm argument](../api/perm.md) and [max_age argument](../api/max-age.md) for query parameter syntax.
## WebSocket support for `/auth/`
If you use a dedicated authentication host (`--auth-host`), route `auth.example.com` to the Paskia cluster and you do not need the `/auth/` bypass above. Otherwise, make sure the `/auth/` route keeps the `Upgrade` and `Connection` headers so passkey WebSocket endpoints work. The default Envoy router handles `Upgrade` headers when the client requests them.
## Notes
- Envoy's `ext_authz` filter does not send the request body to the auth server by default. For Paskia this is fine.
- If Paskia is running behind TLS, use `https://` in `server_uri.uri` and configure the cluster's transport socket.
- The `failure_mode_allow: false` setting means that if Paskia cannot be reached, Envoy will reject the request. In testing you may prefer `true`, but use `false` in production so a failed auth service cannot accidentally allow traffic.
docs/proxy/haproxy.md
+114
View File
@@ -0,0 +1,114 @@
# HAProxy Forward-Auth
[`/auth/api/forward`](../api/forward.md) · [Proxy guides](index.md)
HAProxy does not have a built-in forward-auth primitive, but the community [`haproxy-auth-request`](https://github.com/TimWolla/haproxy-auth-request) Lua script provides an `auth-intercept` action that works very similarly to Nginx's `auth_request`. It makes an internal HTTP request to Paskia and copies the response headers to the backend request.
## Requirements
- HAProxy 2.2 or newer (2.0+ may work but 2.2+ supports all features shown here).
- Compiled with `USE_LUA=1`.
- The [`haproxy-auth-request`](https://github.com/TimWolla/haproxy-auth-request) Lua script loaded.
- The [`haproxy-lua-http`](https://github.com/haproxytech/haproxy-lua-http) dependency in the Lua path.
## Overview
```haproxy
global
lua-load /usr/share/haproxy/auth-request.lua
defaults
mode http
timeout connect 5s
timeout client 30s
timeout server 30s
# Backend that runs the Paskia auth check.
backend paskia_auth
server paskia 127.0.0.1:4401
# Backend that runs the Paskia UI / WebSocket / API.
backend paskia_ui
server paskia 127.0.0.1:4401
# Your protected application.
backend app_backend
server app 127.0.0.1:3000
frontend app
bind *:80
# 1. Route /auth/ straight to Paskia, bypassing the auth check.
acl is_auth path_beg /auth/
use_backend paskia_ui if is_auth
# 2. Add the headers Paskia logs / expects. These are then copied to the
# auth subrequest by auth-intercept.
http-request set-header X-Forwarded-Method %[method]
http-request set-header X-Forwarded-Uri %[url]
# 3. Run the auth check. The parameters are:
# backend path method
# req-headers success-headers failure-headers
#
# - req-headers: headers copied from client to Paskia.
# - success-headers: headers copied from Paskia response to backend request.
# - failure-headers: headers copied from Paskia response to client response.
http-request lua.auth-intercept paskia_auth /auth/api/forward?perm=myapp:login GET Host,Cookie,Accept,X-Forwarded-Method,X-Forwarded-Uri Remote-* *
# 4. If the subrequest was not successful, deny the request.
http-request deny if ! { var(txn.auth_response_successful) -m bool }
default_backend app_backend
```
## What the configuration does
1. **Route `/auth/` to Paskia** — users must be able to reach the login/profile UI without already being authenticated. HAProxy will proxy WebSocket upgrade headers automatically for this backend when the client requests them.
2. **Set `X-Forwarded-Method` and `X-Forwarded-Uri`** — HAProxy adds these headers to the incoming request so the Lua script can copy them to the auth subrequest. `%[method]` returns the HTTP method and `%[url]` returns the path and query string.
3. **`lua.auth-intercept`** — sends a `GET` request to `/auth/api/forward?perm=myapp:login` on the `paskia_auth` backend. It copies the listed request headers (including the dynamic ones we just set) to the auth subrequest.
4. **On success (`2xx`)** — copies every response header matching `Remote-*` from Paskia to the backend request. This overrides any client-supplied `Remote-*` headers, so the backend can trust them.
5. **On failure (`4xx`)** — copies all response headers (`*`) to the client response and uses Paskia's response body, so the browser gets the login HTML or the JSON auth URL.
6. **Deny if auth failed** — the final `http-request deny` rule is a safety net. In practice, `auth-intercept` with `*` as the failure-headers already terminates the transaction with Paskia's response.
## Backend definition for the auth subrequest
The `paskia_auth` backend can be the same physical server as `paskia_ui`, but using a separate backend is convenient because the Lua script will use the first available server in the backend. The auth subrequest is a plain HTTP request, so no special WebSocket options are needed here.
```haproxy
backend paskia_auth
server paskia 127.0.0.1:4401
```
## Per-route permissions
You can run different auth checks for different paths by using HAProxy ACLs. Place the more specific rules before the generic one:
```haproxy
frontend app
bind *:80
acl is_auth path_beg /auth/
use_backend paskia_ui if is_auth
acl is_reports path_beg /reports
http-request set-header X-Forwarded-Method %[method] if is_reports
http-request set-header X-Forwarded-Uri %[url] if is_reports
http-request lua.auth-intercept paskia_auth /auth/api/forward?perm=myapp:reports&max_age=5min GET Host,Cookie,Accept,X-Forwarded-Method,X-Forwarded-Uri Remote-* * if is_reports
http-request set-header X-Forwarded-Method %[method]
http-request set-header X-Forwarded-Uri %[url]
http-request lua.auth-intercept paskia_auth /auth/api/forward?perm=myapp:login GET Host,Cookie,Accept,X-Forwarded-Method,X-Forwarded-Uri Remote-* *
http-request deny if ! { var(txn.auth_response_successful) -m bool }
default_backend app_backend
```
See [perm argument](../api/perm.md) and [max_age argument](../api/max-age.md) for query parameter syntax.
## Notes
- The Lua script strips the request body from the auth subrequest, so Paskia's `/auth/api/forward` will only see the headers.
- HAProxy variables are limited to alphanumeric characters, dots, and underscores, but the script already normalizes header names for you (e.g. `Remote-User` becomes `req.auth_response_header.remote_user`). The `Remote-*` glob pattern in the success-headers argument handles this automatically.
- The auth backend must be reachable without TLS. If you need TLS to Paskia, run a local TCP forwarder or use HAProxy's Lua HTTP support directly (not covered by this script).
- If you use a dedicated authentication host (`--auth-host`), route `auth.example.com` to the Paskia backend and start Paskia with `--auth-host auth.example.com` instead of exposing `/auth/` on every site.
docs/proxy/index.md
+47
View File
@@ -0,0 +1,47 @@
# Forward-Auth Proxy Guides
[`/auth/api/forward`](../api/forward.md) · [Trusted headers](../Headers.md)
These guides show how to protect a backend application with Paskia using the forward-auth (also called "external authentication") mechanism. The reverse proxy asks Paskia whether a request is allowed before forwarding it to the protected service.
For details about the endpoint the proxy calls, see [`/auth/api/forward`](../api/forward.md). For the headers your backend receives on successful requests, see [Trusted Headers](../Headers.md).
## Available guides
- [Caddy](caddy.md) — fully supported with ready-to-use snippets (`auth/setup` and `auth/require`).
- [Nginx](nginx.md) — using the `auth_request` module.
- [Traefik](traefik.md) — using the `ForwardAuth` middleware.
- [Apache APISIX](apisix.md) — using the `forward-auth` plugin.
- [Envoy](envoy.md) — using the `ext_authz` HTTP filter.
- [HAProxy](haproxy.md) — using a Lua auth request.
## Common requirements
No matter which proxy you use, the auth subrequest must:
1. Be sent to `GET /auth/api/forward` on the Paskia backend. By default Paskia listens on `localhost:4401`; set the `AUTH_UPSTREAM` environment variable in our Caddy snippets, or point your proxy at wherever Paskia is running.
2. Include the query parameters Paskia needs for access control:
- `perm` — required permission scope, repeatable (e.g. `perm=myapp:login`). See [perm argument](../api/perm.md).
- `max_age` — how recently the user must have authenticated (e.g. `max_age=5min`). See [max_age argument](../api/max-age.md).
3. Forward these request headers from the original client request:
- `Host` — the site the user is visiting.
- `Cookie` — the session cookie, normally `__Host-paskia`.
- `X-Forwarded-Method` — the original HTTP method (e.g. `GET`, `POST`).
- `X-Forwarded-Uri` — the original path and query string (e.g. `/reports?foo=bar`).
- `Accept` — decides whether a 401/403 response should be HTML (browser) or JSON (API/fetch).
4. Strip hop-by-hop headers (`Connection`, `Upgrade`, `Transfer-Encoding`, `Keep-Alive`, `Proxy-Connection`, `TE`) from the auth subrequest. The auth check is a plain HTTP request and must not carry WebSocket/body framing headers.
5. On a `204 No Content` response, copy the `Remote-*` response headers to the request that is forwarded to the protected backend. The headers are the whole point of the auth check.
6. On a 401/403 response, send Paskia's response back to the client without contacting the protected backend.
7. Also proxy the `/auth/` path prefix to Paskia so the login/profile UI, API endpoints, and WebSockets are reachable. Paskia's WebSocket endpoints need `Upgrade` and `Connection` headers passed through for that path.
## Backend usage
After the proxy forwards the request, your backend can read the trusted headers. For example, in Python/FastAPI:
```python
user_id = request.headers.get("Remote-User")
org_id = request.headers.get("Remote-Org")
permissions = request.headers.get("Remote-Groups", "").split(",")
```
Only trust headers that come from the proxy; never trust `Remote-*` headers that arrive directly from the internet. Your proxy configuration should strip any client-supplied `Remote-*` headers before the auth check.
docs/proxy/nginx.md
+130
View File
@@ -0,0 +1,130 @@
# Nginx Forward-Auth
[`/auth/api/forward`](../api/forward.md) · [Proxy guides](index.md)
This guide uses the [Nginx `auth_request`](http://nginx.org/en/docs/http/ngx_http_auth_request_module.html) module to ask Paskia whether each request is allowed before proxying it to your backend.
## Overview
```nginx
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;
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;
# 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:
```nginx
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](../api/perm.md) and [max_age argument](../api/max-age.md) for details.
## Public paths
To leave some paths unprotected (for example `/.well-known/` or `/static/`), add `location` blocks before the protected `location /` block:
```nginx
location /.well-known/ {
root /var/www;
}
location /static/ {
root /var/www;
}
```
## 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.
docs/proxy/traefik.md
+126
View File
@@ -0,0 +1,126 @@
# Traefik ForwardAuth
[`/auth/api/forward`](../api/forward.md) · [Proxy guides](index.md)
This guide uses Traefik's [ForwardAuth middleware](https://doc.traefik.io/traefik/reference/routing-configuration/http/middlewares/forwardauth/) to ask Paskia whether each request is allowed.
## Overview
A typical dynamic (YAML) configuration looks like this:
```yaml
http:
routers:
app:
rule: "Host(`app.example.com`)"
service: app-backend
middlewares:
- paskia-auth
# Route /auth/ straight to Paskia, bypassing the auth middleware.
auth:
rule: "Host(`app.example.com`) && PathPrefix(`/auth/`)"
service: paskia
middlewares: []
middlewares:
paskia-auth:
forwardAuth:
address: "http://localhost:4401/auth/api/forward?perm=myapp:login"
# Forward every Remote-* header from the auth response to the backend.
authResponseHeadersRegex: "^Remote-"
# Explicitly pass the headers Paskia needs. If left empty, all headers
# are forwarded; being explicit avoids accidentally leaking hop-by-hop
# headers to the auth server.
authRequestHeaders:
- Host
- Cookie
- Accept
- X-Forwarded-Method
- X-Forwarded-Uri
- X-Forwarded-Host
- X-Forwarded-Proto
- X-Forwarded-For
services:
app-backend:
loadBalancer:
servers:
- url: "http://localhost:3000"
paskia:
loadBalancer:
servers:
- url: "http://localhost:4401"
```
## What Traefik sends automatically
Traefik's ForwardAuth middleware sends the auth request to the configured `address` and includes the following headers derived from the original request:
| Header | Value |
|---|---|
| `X-Forwarded-Method` | Original HTTP method |
| `X-Forwarded-Proto` | Original protocol (`http`/`https`) |
| `X-Forwarded-Host` | Original host |
| `X-Forwarded-Uri` | Original request URI (path and query) |
| `X-Forwarded-For` | Client IP address |
These are exactly the headers Paskia logs. You should still include them in `authRequestHeaders` if you set that list explicitly, to make sure they are not filtered out.
## Response headers
`authResponseHeadersRegex: "^Remote-"` tells Traefik to copy every response header starting with `Remote-` from Paskia's `204` response and add it to the request that is forwarded to your backend. It also strips any `Remote-*` headers that the client may have sent, so the backend can trust the values.
For stricter control, you can list the headers explicitly instead of using the regex:
```yaml
authResponseHeaders:
- Remote-User
- Remote-Name
- Remote-Groups
- Remote-Org
- Remote-Org-Name
- Remote-Role
- Remote-Role-Name
- Remote-Session-Expires
- Remote-Credential
```
## Proxying `/auth/` to Paskia
The `/auth/` router above forwards all authentication UI, API, and WebSocket traffic to Paskia. Because this router does **not** use the `paskia-auth` middleware, users can reach the login page and profile UI without being authenticated first. Traefik handles WebSocket upgrades automatically when the client requests them.
If you are using a dedicated authentication host instead of `/auth/`, create a separate router for `auth.example.com` pointing to the Paskia service and start Paskia with `--auth-host auth.example.com`.
## Adjusting requirements
Change the `address` query string to require different permissions or recent authentication:
```yaml
address: "http://localhost:4401/auth/api/forward?perm=myapp:login"
address: "http://localhost:4401/auth/api/forward?perm=myapp:admin&max_age=5min"
address: "http://localhost:4401/auth/api/forward"
```
The last form requires only authentication, no specific permission. See [perm argument](../api/perm.md) and [max_age argument](../api/max-age.md).
## Docker labels example
When using Traefik with Docker Compose, you can define the middleware with labels:
```yaml
labels:
- "traefik.enable=true"
- "traefik.http.routers.myapp.rule=Host(`app.example.com`)"
- "traefik.http.routers.myapp.middlewares=paskia-auth"
- "traefik.http.middlewares.paskia-auth.forwardauth.address=http://localhost:4401/auth/api/forward?perm=myapp:login"
- "traefik.http.middlewares.paskia-auth.forwardauth.authResponseHeadersRegex=^Remote-"
- "traefik.http.middlewares.paskia-auth.forwardauth.authRequestHeaders=Host,Cookie,Accept,X-Forwarded-Method,X-Forwarded-Uri"
```
## Notes
- By default ForwardAuth sends a request without the original body. If you need to forward the body for logging/validation, set `forwardBody: true` and a sensible `maxBodySize`, but for Paskia this is not required.
- Paskia does not set cookies on the forward-auth response; it only returns `Remote-*` headers. Use the JavaScript helpers from the [paskia](https://www.npmjs.com/package/paskia) package for session renewal in the frontend.
- For HTTPS, use `https://` in the `address` and configure TLS options (`tls.insecureSkipVerify: true` only for testing).