Skip to content

Feature Guide Forward Auth

Jump to bottom
fuomag9 edited this page Jul 23, 2026 · 4 revisions

Feature Guide: Forward Auth Portal

Protect proxy hosts with CPM's built-in identity provider — no external IdP required.

Table of Contents

  1. Overview
  2. How It Works
  3. Enable Forward Auth on a Proxy Host
  4. Excluded Paths
  5. Groups
  6. Per-Host Access Control
  7. Login Methods
  8. Session Management
  9. Comparison with Authentik Integration
  10. Troubleshooting

Overview

The Forward Auth Portal turns CPM into an identity provider for your proxy hosts. Instead of deploying a separate service like Authentik or Authelia, CPM handles authentication directly:

  • Login portal with credential and OAuth support
  • User groups with membership management
  • Per-host access lists (users and/or groups)
  • Session cookies scoped per protected host

How It Works

  1. A visitor requests a forward-auth-protected proxy host.
  2. Caddy's forward_auth directive calls CPM's verify endpoint.
  3. If the visitor has a valid session cookie, the request proceeds to the upstream.
  4. If not, the visitor is redirected to CPM's login portal.
  5. After successful login, CPM issues a session cookie and redirects back.
  6. Subsequent requests include the cookie and pass verification automatically.

Enable Forward Auth on a Proxy Host

  1. Open Proxy Hosts and create or edit a host.
  2. Scroll to the Forward Auth section and enable it.
  3. Choose which users and/or groups may access the host.
  4. Optionally configure excluded paths (see below).
  5. Click Save / Create.

The host's Caddy config is regenerated with a forward_auth handler pointing to CPM's verify endpoint and a callback route for the login flow.

Excluded Paths

Both CPM's built-in forward auth and Authentik forward auth let you define paths that bypass authentication while the rest of the host stays protected.

How it works

  • Protected Paths mode (whitelist): only the listed paths require authentication.
  • Excluded Paths mode (blacklist): all paths require authentication except the listed ones.

If Protected Paths is set, it takes precedence and Excluded Paths is ignored.

Configuration

  1. Edit a proxy host with forward auth enabled.
  2. Expand the Protected Paths or Excluded Paths field, whichever mode you want.
  3. Enter comma-separated path patterns using Caddy's glob syntax, e.g. /share/*, /rest/*, /public/*.
  4. Save.

Patterns are matched literally — a trailing * is required to match everything beneath a prefix. /rest/ alone matches only that exact path, not /rest/anything.

Excluded-path routes are inserted before the catch-all auth route in the generated Caddy config so they are served without authentication.

Example for Navidrome (music server): set Excluded Paths to /share/*, /rest/* so Navidrome's sharing links and REST API (used by mobile clients) work without authentication, while the main web UI stays protected.

Groups

Groups let you manage access at scale instead of per-user.

Create a group

  1. Open Groups in the sidebar.
  2. Click New Group.
  3. Enter a name (e.g. "Engineering", "External Contractors").
  4. Add members from the user list.
  5. Click Create.

Assign a group to a proxy host

When editing a proxy host's forward auth settings, select the group in the access list. All current and future members of that group gain access automatically.

Manage membership

Add or remove members from the group page at any time. Changes take effect on the next request (no restart needed).

Per-Host Access Control

Each forward-auth-protected host maintains its own access list of allowed users and groups.

Key points:

  • Access is separate from the user's role — even admins must be explicitly added.
  • A user gains access if they are listed directly or belong to an allowed group.
  • Removing a user from all allowed groups and the direct list revokes access immediately.

Login Methods

The forward auth login portal supports:

  • Credentials — username and password (same as dashboard login)
  • OAuth — if OAuth is configured, users can sign in via the OAuth provider

Both methods create a forward auth session independent of the dashboard session.

Session Management

  • Forward auth sessions are stored server-side with a session cookie.
  • Sessions are scoped to the protected host's domain.
  • Sessions are revoked when a user's status changes away from "active".
  • Rate limiting applies to the login portal (same settings as dashboard login).

Comparison with Authentik Integration

Feature Forward Auth Portal Authentik Integration
External service required No Yes (Authentik instance)
Login portal Built into CPM Authentik's portal
User management CPM's user/group system Authentik's user system
OAuth support Via CPM's OAuth config Native to Authentik
Header forwarding Session user info Authentik identity headers
Setup complexity Low Medium-High

Use the built-in portal for simple setups. Use Authentik when you need its advanced features (SCIM, LDAP, multi-factor, etc.).

Troubleshooting

Redirect loop after login

  • Verify the proxy host's domain resolves to Caddy.
  • Check that the forward auth callback route is reachable.
  • Ensure BASE_URL is set correctly in .env.

User cannot access a protected host

  • Confirm the user is in the host's forward auth access list (directly or via group).
  • Check the user's status is "active" on the Users page.

OAuth login not available on portal

  • Ensure OAUTH_ENABLED=true and OAuth credentials are configured in .env.

Related Documentation

Need help? Open an issue with your host configuration and relevant logs.

Clone this wiki locally