LeoVasanko
383c9f472e
/auth/api/forward?public=1 passes requests through with a Remote-Public header (anonymous/forbidden/authenticated) instead of 401/403, so routes can allow anonymous visitors while still identifying logged-in users. Reauth (max_age) still requires the auth flow. Documented in Headers.md, api/forward.md, Integration.md and all proxy guides.
37 lines
2.9 KiB
Markdown
37 lines
2.9 KiB
Markdown
# Paskia Trusted Headers for Backend Apps
|
|
|
|
[Proxy guides](proxy/index.md) · [`/auth/api/forward`](api/forward.md)
|
|
|
|
| HTTP Header | Meaning | Example |
|
|
|---|---|---|
|
|
| Remote-User | Authenticated user UUID | **01c03276-b8f0-**… (string) |
|
|
| Remote-Name | User display name | **John Doe** |
|
|
| Remote-Org | Organization UUID | Identifier for user's org (string) |
|
|
| Remote-Org-Name | Organization display name | **The Company Ltd.** |
|
|
| Remote-Role | Role UUID | Identifier for user's role (string) |
|
|
| Remote-Role-Name | Role display name | **Employee** |
|
|
| Remote-Groups | Permissions the user has, comma separated | **auth:admin,yourapp:reports** |
|
|
| Remote-Session-Expires | Session expiry timestamp (ISO 8601 UTC) | **2030-12-31T23:59:59Z** |
|
|
| Remote-Credential | Credential UUID | Identifier for the sign-in passkey (string) |
|
|
| Remote-Public | Public-access marker, only present on routes using [`public=1`](api/forward.md#public-access) | **authenticated**, **forbidden** or **anonymous** |
|
|
|
|
### Public access
|
|
|
|
On routes configured with `public=1`, every forwarded request carries `Remote-Public` and the backend must check it before treating the request as authorized:
|
|
|
|
- `authenticated` — the user has everything the route asked for; full `Remote-*` headers.
|
|
- `forbidden` — the user is logged in but the route's `perm` check failed. Full identity headers are sent, including `Remote-Groups` — it is trustworthy, it just lacks the requested permission.
|
|
- `anonymous` — no valid session; no identity headers are sent.
|
|
|
|
Without `public=1` the header is absent and every request reaching the backend is fully authorized.
|
|
|
|
Similar headers are also used by other authentication systems like [Authelia](https://www.authelia.com/integration/trusted-header-sso/introduction/) to signal the backend application information about the signed in user.
|
|
|
|
When a request is allowed, the auth service adds these headers by the forward-auth mechanism before proxying to your app as **request headers**. Your app can use them for user context to show on UI, or for its own authentication needs (e.g. prevent different orgs messing up with each other's data, logging which user performed an action).
|
|
|
|
Only the UUID values should be used for identification needs, because they never change, even when things are renamed (display names change), and are never reused (created on authentication server). They are UUIDv7 so you can also extract the creation timestamp from them.
|
|
|
|
Any `Remote-*` headers from clients are stripped by the proxy configuration (see our [Caddy configuration](proxy/caddy.md) and [Forward-Auth Proxy Guides](proxy/index.md)) to avoid dealing with any fake headers.
|
|
|
|
Note: the headers are intended primarily for the backend, while either frontend or backend (passing the session cookie) can request `/auth/api/user-info` for more complete information, and that is the recommended way to do it in the frontend. See [integration](Integration.md) for more.
|