Forward-Auth & Reverse Proxy Integration¶

StackPilot supports enterprise Single Sign-On (SSO) and Identity Provider integration via Forward-Authentication headers, allowing seamless pairing with Authentik, Authelia, Keycloak, or Cloudflare Access.

1. How Forward-Auth Operates¶

When placed behind a reverse proxy configured with Forward-Auth: 1. Incoming browser requests hit the reverse proxy (e.g. Traefik, Caddy, Nginx). 2. The proxy queries the identity provider (e.g. Authentik) to authenticate the session. 3. Upon successful login, the proxy forwards the request to the StackPilot Central Hub along with identity headers.

sequenceDiagram
    autonumber
    actor User as User Browser
    participant Proxy as Reverse Proxy (Traefik / Caddy)
    participant IdP as Identity Provider (Authentik / Authelia)
    participant Hub as StackPilot Hub (:8081)

    User->>Proxy: GET https://stackpilot.example.com
    Proxy->>IdP: Verify Session / Authenticate
    IdP-->>Proxy: Authenticated (User: alice, Groups: stackpilot-admins)
    Proxy->>Hub: Forward GET with Remote-User & Remote-Groups
    Note over Hub: Hub verifies Proxy IP matches STACKPILOT_FORWARD_AUTH_TRUSTED_PROXIES
    Hub->>Hub: Map "stackpilot-admins" -> "admin" Role
    Hub-->>Proxy: 200 OK (Render Admin Dashboard)
    Proxy-->>User: 200 OK

2. Supported Header Sets¶

StackPilot natively handles both standard generic headers and Authentik-specific headers:

Standard Header	Authentik Native Header	Description
`Remote-User`	`X-Authentik-Username`	Authenticated username or subject identifier
`Remote-Email`	`X-Authentik-Email`	User's verified email address
`Remote-Groups`	`X-Authentik-Groups`	Comma or pipe-separated list of user groups

3. RBAC Role Mapping¶

Groups received from the identity provider map directly to StackPilot roles:

Group Name	Mapped Role	Permissions
`stackpilot-admins`	`admin`	Full access: deployments, deletions, secret refactoring, users
`stackpilot-operators`	`operator`	Can restart services, pull images, view logs (cannot delete)
(Any other authenticated user)	`viewer`	Read-only metrics, container lists, and status

4. Trusted Proxy Verification¶

Security Requirement: Proxy CIDR Validation

To prevent attackers on your local network from spoofing Remote-User headers, StackPilot strictly verifies the connecting source IP.

Set the trusted reverse proxy IP in your environment or Quadlet:

Environment=REQUIRE_FORWARD_AUTH=true
Environment=STACKPILOT_FORWARD_AUTH_TRUSTED_PROXIES=127.0.0.1,10.0.0.5

Requests carrying forward-auth headers from unlisted IP addresses are rejected with 403 Forbidden.