Skip to content

Feature Guide Access Lists

Jump to bottom
fuomag9 edited this page Feb 27, 2026 · 2 revisions

Feature Guide: Access Lists

HTTP basic authentication for protecting services behind proxy hosts.

Table of Contents

  1. What Access Lists Do
  2. Create an Access List
  3. Manage Credentials
  4. Apply an Access List to a Proxy Host
  5. Pagination
  6. Security Notes
  7. Troubleshooting

What Access Lists Do

Access lists add browser-native HTTP basic auth in front of your upstream.

Typical use cases:

  • Protect admin dashboards
  • Gate internal/staging apps
  • Add simple auth to apps without login support

How requests flow:

  1. Client requests a protected host
  2. Browser prompts for username/password
  3. Credentials are validated against the selected access list
  4. If valid, request is proxied upstream

Create an Access List

  1. Open Access Lists from the sidebar.
  2. Scroll to Create access list.
  3. Fill in:
    • Name (required)
    • Description (optional)
    • Seed members (optional): one username:password pair per line
  4. Click Create Access List.

Example seed members:

alice:StrongPass#1
bob:AnotherStrongPass#2

The application stores hashed passwords (bcrypt), not plaintext.

Manage Credentials

Each access list supports multiple accounts.

Inside each list card you can:

  • Edit list name/description
  • Add new accounts with Username + Password
  • Remove existing accounts
  • Delete the entire list

After list changes are saved, Caddy config is reapplied automatically.

Apply an Access List to a Proxy Host

  1. Open Proxy Hosts.
  2. Create or edit a host.
  3. Set Access List to the list you want.
  4. Save.

Set Access List = None to remove HTTP basic auth from that host.

Pagination

Access Lists now use server-side pagination.

  • Default page size: 25 lists per page
  • Use the pager at the bottom to move between pages
  • URL state is preserved with ?page=N for shareable links

Note: the Create access list form remains available below the paginated list.

Security Notes

HTTP basic auth is simple and widely supported, but has limits:

  • Credentials are sent on every request (always use HTTPS)
  • Browsers cache credentials; logout UX is limited
  • No built-in MFA

Recommended practices:

  • Use long, unique passwords per account
  • Rotate credentials regularly
  • Prefer OAuth/OIDC for user SSO or stronger identity controls
  • Combine with geo blocking where appropriate

Troubleshooting

Browser keeps prompting for credentials

Possible causes:

  • Wrong username/password
  • Access list not attached to the host
  • Browser cached stale credentials

Checks:

  1. Confirm the account exists in the selected list
  2. Re-enter credentials manually (case-sensitive)
  3. Verify the proxy host has the expected access list selected
  4. Review the Audit Log for list/host updates

Auth prompt does not appear

Possible causes:

  • Host has no access list assigned
  • Host changes not saved

Checks:

  1. Edit proxy host and verify Access List is not None
  2. Save host again
  3. Confirm host is enabled

Related Documentation

Need help? Open an issue with your access list and host setup (do not include real passwords).

Clone this wiki locally