Feature HTTP Basic Authentication support #226 #937 #874

New Issue

MrUnknownDE · 2026-04-05T17:54:09+02:00

MrUnknownDE commented

2026-04-05 17:54:09 +02:00

Originally created by @jln-brtn on 9/22/2025

Community Contribution License Agreement

By creating this pull request, I grant the project maintainers an unlimited, perpetual license to use, modify, and redistribute these contributions under any terms they choose, including both the AGPLv3 and the Fossorial Commercial license terms. I represent that I have the right to grant this license for all contributed content.

Description

This feature introduces support for the 'Basic' HTTP Authentication Scheme (RFC 7617) to allow access to a protected resource. As described in #226 and #937, the primary goal is to provide an alternative to Pangolin's standard SSO authentication, which requires user interaction with a graphical interface. Supporting header-based authentication enables third-party systems and headless clients to bypass the interactive login flow by providing credentials directly in the request header.

Currently, when an unauthenticated user tries to access a resource managed by Pangolin (e.g., a Jellyfin server at https://play.example.com), they are redirected to a login page. This flow is incompatible with headless clients, such as the Jellyfin mobile application, which cannot render the web login page.

The existing workaround involves creating filtering rules to allow specific URL paths to bypass authentication. This approach is insecure, as it exposes endpoints publicly, and brittle, as it requires maintaining an exhaustive list of all necessary API routes.

This feature allows users to enable Basic Authentication for a resource through the management interface. When configuring the resource, the user can add header-based authentication by specifying a username and password.

Once configured, a client can authenticate by embedding the credentials in the URL (e.g., https://user:password@play.example.com) or by providing them in the Authorization header. Pangolin will identify and validate these credentials, allowing the request to proceed to the backend resource without any GUI interaction.

How to test?

Navigate to the management UI and edit a resource.
Enable the new "Header Authentication" option.
Enter a desired username and password and save the configuration.
Send a request to the resource's URL using cURL with the correct credentials: curl -u "username:password" https://play.example.com. The request should be successful (e.g., HTTP 200 OK) and the resource content should be returned.
Send a request with incorrect credentials: curl -u "username:wrongpassword" https://play.example.com. The request should be redirected to the standard pangolin login page.
Send a request without credentials from a new browser session. The request should be redirected to the traditional pangolin login.
Remove the "Header Authentication" option and send a request with the correct credentials. The request should be redirected to the traditional pangolin login.

Points of attention

While it's my first contribution to this project, some minor point should be check :

I've modified the database by adding a table. The schema.ts have been modified, from both pg and sqlite. Anything to do for migration ? (not familiar with drizzle)
verify-session method have been modified. Have I placed it correctly in order to maintain consistency with other validations (such as rules, for example) ?
I used cache in order to speed up verification (due to the hashing function), is any security issue ? I think the cache is a major factor because a non-cached authentication took 40 ms locally, whereas with the cache it took 12 ms.

Huge thanks to @AstralDestiny which help me to set up the local development environment

*Originally created by @jln-brtn on 9/22/2025* ## Community Contribution License Agreement By creating this pull request, I grant the project maintainers an unlimited, perpetual license to use, modify, and redistribute these contributions under any terms they choose, including both the AGPLv3 and the Fossorial Commercial license terms. I represent that I have the right to grant this license for all contributed content. ## Description This feature introduces support for the 'Basic' HTTP Authentication Scheme ([RFC 7617](https://www.rfc-editor.org/rfc/rfc7617)) to allow access to a protected resource. As described in #226 and #937, the primary goal is to provide an alternative to Pangolin's standard SSO authentication, which requires user interaction with a graphical interface. Supporting header-based authentication enables third-party systems and headless clients to bypass the interactive login flow by providing credentials directly in the request header. Currently, when an unauthenticated user tries to access a resource managed by Pangolin (e.g., a Jellyfin server at https://play.example.com), they are redirected to a login page. This flow is incompatible with headless clients, such as the Jellyfin mobile application, which cannot render the web login page. The existing workaround involves creating filtering rules to allow specific URL paths to bypass authentication. This approach is insecure, as it exposes endpoints publicly, and brittle, as it requires maintaining an exhaustive list of all necessary API routes. This feature allows users to enable Basic Authentication for a resource through the management interface. When configuring the resource, the user can add header-based authentication by specifying a username and password. <img width="1522" height="818" alt="CleanShot 2025-09-22 at 17 46 55" src="https://github.com/user-attachments/assets/58a41b19-1167-4336-9ce2-1d540ecd019e" /> <img width="1522" height="818" alt="CleanShot 2025-09-22 at 17 51 52" src="https://github.com/user-attachments/assets/3893fd4f-710d-4cbe-8b44-b404634d13aa" /> Once configured, a client can authenticate by embedding the credentials in the URL (e.g., https://user:password@play.example.com) or by providing them in the Authorization header. Pangolin will identify and validate these credentials, allowing the request to proceed to the backend resource without any GUI interaction. <img width="1624" height="1091" alt="CleanShot 2025-09-22 at 17 53 15" src="https://github.com/user-attachments/assets/be0e1140-d8f6-477e-8f7e-06a83ebb4770" /> ## How to test? * Navigate to the management UI and edit a resource. * Enable the new "Header Authentication" option. * Enter a desired username and password and save the configuration. * Send a request to the resource's URL using cURL with the correct credentials: `curl -u "username:password" https://play.example.com`. The request should be successful (e.g., HTTP 200 OK) and the resource content should be returned. * Send a request with incorrect credentials: `curl -u "username:wrongpassword" https://play.example.com`. The request should be redirected to the standard pangolin login page. * Send a request without credentials from a new browser session. The request should be redirected to the traditional pangolin login. * Remove the "Header Authentication" option and send a request with the correct credentials. The request should be redirected to the traditional pangolin login. ## Points of attention While it's my first contribution to this project, some minor point should be check : * I've modified the database by adding a table. The schema.ts have been modified, from both pg and sqlite. Anything to do for migration ? (not familiar with drizzle) * verify-session method have been modified. Have I placed it correctly in order to maintain consistency with other validations (such as rules, for example) ? * I used cache in order to speed up verification (due to the hashing function), is any security issue ? I think the cache is a major factor because a non-cached authentication took 40 ms locally, whereas with the cache it took 12 ms. _Huge thanks to @AstralDestiny which help me to set up the local development environment_

MrUnknownDE closed this issue

2026-04-05 17:54:09 +02:00

Sign in to join this conversation.

Branches Tags

main

dev

dependabot/npm_and_yarn/dev-minor-updates-b4e5d6b9c5

revert-2766-feature/systemd-install-instructions

dependabot/npm_and_yarn/prod-patch-updates-05702d39f2

dependabot/npm_and_yarn/next-16.2.1

dependabot/npm_and_yarn/recharts-3.8.1

alerting-rules

private-site-ha

dependabot/docker/docker/library/node-25-slim

ssh

delete-account

msg-delivery

org-only-idp

cicd

patch

site-targets-auto-login

No Label

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: github/pangolin#874