[GH-ISSUE #1642] SSO via proxy auth header

kerem commented

2026-02-26 02:34:33 +03:00

Owner

Originally created by @HannesJo0139 on GitHub (Dec 27, 2022).
Original GitHub issue: https://github.com/koel/koel/issues/1642

I'm using single-sign-on and I noticed that some years ago you stated that you would not want to implement and support stuff like OAUTH. I understand that OAUTH, OpenID, etc. are complex to implement and support, but would you consider implementing authorization via proxy-auth header? The login process would remain the same, except that the credentials are provided by the reverse proxy via header.

Originally created by @HannesJo0139 on GitHub (Dec 27, 2022). Original GitHub issue: https://github.com/koel/koel/issues/1642 I'm using single-sign-on and I noticed that some years ago you stated that you would not want to implement and support stuff like OAUTH. I understand that OAUTH, OpenID, etc. are complex to implement and support, but would you consider implementing authorization via proxy-auth header? The login process would remain the same, except that the credentials are provided by the reverse proxy via header.

kerem closed this issue

2026-02-26 02:34:33 +03:00

kerem commented

2026-02-26 02:34:33 +03:00

Author

Owner

@TheRealGramdalf commented on GitHub (Dec 22, 2023):

@phanan I'm curious to know what your stance is on this - is it out of scope, or is it on the roadmap?

Koel looks like an awesome functional music server, and SSO via auth headers would make it that much more viable for many people, myself included. I would recommend this being an opt-in feature; with a warning that this could prove a security risk if configured incorrectly - as I expand on later, I would be happy to create said documentation, along with some recommendations for a secure implementations.

Though I'm no expert with header auth, it seems to usually consist of a couple things:

Use an HTTP header (typically remote-user) to determine whether a user is authenticated or not. If supplied, it is assumed that the user has authenticated themselves already, and koel allows access (without showing the login screen)
Optional: Allow auto creation of users that do not exist. As discussed in Navidrome, user registration should be a concious act - but in this case, it is assumed that user registration is managed externally. See the link above for a better explanation.
Optional: Add display names. Most SSO solutions allow users to change their username at any time, and users are instead referred to by a UUID. Since this isn't super human readable, it would make sense to allow setting a display name - and optionally, passing this through via a header (e.g. remote-preferred-name).

If you (or a contributor) were to implement the functionality, I would be happy to write documentation for it's general usage, including a starting point for making sure it is deployed at least semi-securely.

@TheRealGramdalf commented on GitHub (Dec 22, 2023): @phanan I'm curious to know what your stance is on this - is it out of scope, or is it on the roadmap? Koel looks like an awesome functional music server, and SSO via auth headers would make it that much more viable for many people, myself included. I would recommend this being an opt-in feature; with a warning that this could prove a security risk if configured incorrectly - as I expand on later, I would be happy to create said documentation, along with some recommendations for a secure implementations. Though I'm no expert with header auth, it seems to usually consist of a couple things: - Use an HTTP header (typically `remote-user`) to determine whether a user is authenticated or not. If supplied, it is assumed that the user has authenticated themselves already, and koel allows access (without showing the login screen) - Optional: Allow auto creation of users that do not exist. As discussed in [Navidrome](https://github.com/navidrome/navidrome/pull/1152#issuecomment-940575315), user registration should be a concious act - but in this case, it is assumed that user registration is managed externally. See the link above for a better explanation. - Optional: Add display names. Most SSO solutions allow users to change their username at any time, and users are instead referred to by a UUID. Since this isn't super human readable, it would make sense to allow setting a display name - and optionally, passing this through via a header (e.g. `remote-preferred-name`). If you (or a contributor) were to implement the functionality, I would be happy to write documentation for it's general usage, including a starting point for making sure it is deployed at least semi-securely.

kerem commented

2026-02-26 02:34:33 +03:00

Author

Owner

@phanan commented on GitHub (Dec 22, 2023):

This looks interesting and I can imagine some users can find it useful. The
implementation isn’t too straightforward though, as I can already imagine:

Several more configs would have to be added and implemented (enabling,
header name, proxy IP masks)
Add/Edit User forms will have to cater for remote authenticated users
e.g., via a checkbox.
API token management flow would have to adapt somehow. Since the
traditional login flow can be skipped altogether, I imagine Koel would have
to always look for the remote user header AND the token, and create the
latter on the fly if missing.
This wouldn’t work with the mobile app I’d presume.

And of course, maintenance and documentation will be a burden.

On Fri, Dec 22, 2023 at 03:34 TheRealGramdalf @.***>
wrote:

@phanan https://github.com/phanan I'm curious to know what your stance
is on this - is it out of scope, or is it on the roadmap?

Koel looks like an awesome functional music server, and SSO via auth
headers would make it that much more viable for many people, myself
included. I would recommend this being an opt-in feature; with a warning
that this could prove a security risk if configured incorrectly - as I
expand on later, I would be happy to create said documentation, along with
some recommendations for a secure implementations.

Though I'm no expert with header auth, it seems to usually consist of a
couple things:

Use an HTTP header (typically remote-user) to determine whether a
user is authenticated or not. If supplied, it is assumed that the user has
authenticated themselves already, and koel allows access (without showing
the login screen)

Optional: Allow auto creation of users that do not exist. As
discussed in Navidrome
https://github.com/navidrome/navidrome/pull/1152#issuecomment-940575315,
user registration should be a concious act - but in this case, it is
assumed that user registration is managed externally. See the link above
for a better explanation.

Optional: Add display names. Most SSO solutions allow users to
change their username at any time, and users are instead referred to by a
UUID. Since this isn't super human readable, it would make sense to allow
setting a display name - and optionally, passing this through via a header
(e.g. remote-preferred-name).

If you (or a contributor) were to implement the functionality, I would be
happy to write documentation for it's general usage, including a starting
point for making sure it is deployed at least semi-securely.

—
Reply to this email directly, view it on GitHub
https://github.com/koel/koel/issues/1642#issuecomment-1867156608, or
unsubscribe
https://github.com/notifications/unsubscribe-auth/AB5O3UXLOE2PX55FDDW4J7TYKTWR5AVCNFSM6AAAAAATKN2SD2VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMYTQNRXGE2TMNRQHA
.
You are receiving this because you were mentioned.Message ID:
@.***>

@phanan commented on GitHub (Dec 22, 2023): This looks interesting and I can imagine some users can find it useful. The implementation isn’t too straightforward though, as I can already imagine: - Several more configs would have to be added and implemented (enabling, header name, proxy IP masks) - Add/Edit User forms will have to cater for remote authenticated users e.g., via a checkbox. - API token management flow would have to adapt somehow. Since the traditional login flow can be skipped altogether, I imagine Koel would have to always look for the remote user header AND the token, and create the latter on the fly if missing. - This wouldn’t work with the mobile app I’d presume. And of course, maintenance and documentation will be a burden. On Fri, Dec 22, 2023 at 03:34 TheRealGramdalf ***@***.***> wrote: > @phanan <https://github.com/phanan> I'm curious to know what your stance > is on this - is it out of scope, or is it on the roadmap? > > Koel looks like an awesome functional music server, and SSO via auth > headers would make it that much more viable for many people, myself > included. I would recommend this being an opt-in feature; with a warning > that this could prove a security risk if configured incorrectly - as I > expand on later, I would be happy to create said documentation, along with > some recommendations for a secure implementations. > > Though I'm no expert with header auth, it seems to usually consist of a > couple things: > > - Use an HTTP header (typically remote-user) to determine whether a > user is authenticated or not. If supplied, it is assumed that the user has > authenticated themselves already, and koel allows access (without showing > the login screen) > - Optional: Allow auto creation of users that do not exist. As > discussed in Navidrome > <https://github.com/navidrome/navidrome/pull/1152#issuecomment-940575315>, > user registration should be a concious act - but in this case, it is > assumed that user registration is managed externally. See the link above > for a better explanation. > - Optional: Add display names. Most SSO solutions allow users to > change their username at any time, and users are instead referred to by a > UUID. Since this isn't super human readable, it would make sense to allow > setting a display name - and optionally, passing this through via a header > (e.g. remote-preferred-name). > > If you (or a contributor) were to implement the functionality, I would be > happy to write documentation for it's general usage, including a starting > point for making sure it is deployed at least semi-securely. > > — > Reply to this email directly, view it on GitHub > <https://github.com/koel/koel/issues/1642#issuecomment-1867156608>, or > unsubscribe > <https://github.com/notifications/unsubscribe-auth/AB5O3UXLOE2PX55FDDW4J7TYKTWR5AVCNFSM6AAAAAATKN2SD2VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMYTQNRXGE2TMNRQHA> > . > You are receiving this because you were mentioned.Message ID: > ***@***.***> >

kerem commented

2026-02-26 02:34:33 +03:00

Author

Owner

@phanan commented on GitHub (Mar 30, 2024):

@TheRealGramdalf Since I'm not familiar with the topic, what's typically the value of REMOTE_USER? If it's not an email address, we'll have some troubles, as Koel uses email addresses for authentication.

@phanan commented on GitHub (Mar 30, 2024): @TheRealGramdalf Since I'm not familiar with the topic, what's typically the value of `REMOTE_USER`? If it's not an email address, we'll have some troubles, as Koel uses email addresses for authentication.

kerem commented

2026-02-26 02:34:33 +03:00

Author

Owner

@TheRealGramdalf commented on GitHub (Mar 30, 2024):

It can be set to one of a couple values; in the context of OIDC it's typically name (username), sub (a UUID), or email (email address). sub is ideal, since it's guaranteed to be unique - you don't want a situation in which the remote user changes their email address/username (which can typically happen at any time, and koel wouldn't necessarily be notified of the change) and gets logged in to a completely new account, or an account that used to belong to someone else. The username/email is typically set by remote-preferred-name, which is then used in the UI instead of the UUID.

@TheRealGramdalf commented on GitHub (Mar 30, 2024): It can be set to one of a couple values; in the context of OIDC it's typically `name` (username), `sub` (a UUID), or `email` (email address). `sub` is ideal, since it's guaranteed to be unique - you don't want a situation in which the remote user changes their email address/username (which can typically happen at any time, and koel wouldn't necessarily be notified of the change) and gets logged in to a completely new account, or an account that used to belong to someone else. The username/email is typically set by `remote-preferred-name`, which is then used in the UI instead of the UUID.

kerem commented

2026-02-26 02:34:33 +03:00

Author

Owner

@phanan commented on GitHub (Mar 30, 2024):

Hmm, in such a case I wonder what the email value is supposed to be. Any
suggestion?

On Sat, Mar 30, 2024 at 18:37 TheRealGramdalf @.***>
wrote:

It can be set to one of a couple values; in the context of OIDC it's
typically name (username), sub (a UUID), or email (email address). sub is
ideal, since it's guaranteed to be unique - you don't want a situation in
which the remote user changes their email address/username (which can
typically happen at any time, and koel wouldn't necessarily be notified of
the change) and gets logged in to a completely new account, or an account
that used to belong to someone else. The username/email is typically set by
remote-preferred-name, which is then used in the UI instead of the UUID.

—
Reply to this email directly, view it on GitHub
https://github.com/koel/koel/issues/1642#issuecomment-2028352280, or
unsubscribe
https://github.com/notifications/unsubscribe-auth/AB5O3UXDGAAC7YDWMNBRDJLY23Z4BAVCNFSM6AAAAAATKN2SD2VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDAMRYGM2TEMRYGA
.
You are receiving this because you were mentioned.Message ID:
@.***>

@phanan commented on GitHub (Mar 30, 2024): Hmm, in such a case I wonder what the email value is supposed to be. Any suggestion? On Sat, Mar 30, 2024 at 18:37 TheRealGramdalf ***@***.***> wrote: > It can be set to one of a couple values; in the context of OIDC it's > typically name (username), sub (a UUID), or email (email address). sub is > ideal, since it's guaranteed to be unique - you don't want a situation in > which the remote user changes their email address/username (which can > typically happen at any time, and koel wouldn't necessarily be notified of > the change) and gets logged in to a completely new account, or an account > that used to belong to someone else. The username/email is typically set by > remote-preferred-name, which is then used in the UI instead of the UUID. > > — > Reply to this email directly, view it on GitHub > <https://github.com/koel/koel/issues/1642#issuecomment-2028352280>, or > unsubscribe > <https://github.com/notifications/unsubscribe-auth/AB5O3UXDGAAC7YDWMNBRDJLY23Z4BAVCNFSM6AAAAAATKN2SD2VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDAMRYGM2TEMRYGA> > . > You are receiving this because you were mentioned.Message ID: > ***@***.***> >

kerem commented

2026-02-26 02:34:33 +03:00

Author

Owner

@TheRealGramdalf commented on GitHub (Mar 30, 2024):

Speaking generally, it's possible to set remote-user to any of the three (sub, name, email), the same can be said for remote-preferred-name. This leaves it up to the administrator to decide which one is used as a UUID, and which one is used as the displayname.

@TheRealGramdalf commented on GitHub (Mar 30, 2024): Speaking generally, it's possible to set `remote-user` to any of the three (`sub`, `name`, `email`), the same can be said for `remote-preferred-name`. This leaves it up to the administrator to decide which one is used as a UUID, and which one is used as the displayname.

kerem commented

2026-02-26 02:34:33 +03:00

Author

Owner

@phanan commented on GitHub (Mar 30, 2024):

We’d want the users to be able to use the mobile app as well, which
requires an email/password pair. To achieve this, we can force the user to
set an email and password upon the first login. Subsequent logins via web
will just work seamlessly using the remote_user header, and the user can
use the email/password credentials for the mobile app. Wdyt?

On Sat, Mar 30, 2024 at 19:07 TheRealGramdalf @.***>
wrote:

Speaking generally, it's possible to set remote-user to any of the three (
sub, name, email), the same can be said for remote-preferred-name. This
leaves it up to the administrator to decide which one is used as a UUID,
and which one is used as the displayname.

—
Reply to this email directly, view it on GitHub
https://github.com/koel/koel/issues/1642#issuecomment-2028401760, or
unsubscribe
https://github.com/notifications/unsubscribe-auth/AB5O3URBNHHNZHV73WZBALTY235OHAVCNFSM6AAAAAATKN2SD2VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDAMRYGQYDCNZWGA
.
You are receiving this because you were mentioned.Message ID:
@.***>

@phanan commented on GitHub (Mar 30, 2024): We’d want the users to be able to use the mobile app as well, which requires an email/password pair. To achieve this, we can force the user to set an email and password upon the first login. Subsequent logins via web will just work seamlessly using the remote_user header, and the user can use the email/password credentials for the mobile app. Wdyt? On Sat, Mar 30, 2024 at 19:07 TheRealGramdalf ***@***.***> wrote: > Speaking generally, it's possible to set remote-user to any of the three ( > sub, name, email), the same can be said for remote-preferred-name. This > leaves it up to the administrator to decide which one is used as a UUID, > and which one is used as the displayname. > > — > Reply to this email directly, view it on GitHub > <https://github.com/koel/koel/issues/1642#issuecomment-2028401760>, or > unsubscribe > <https://github.com/notifications/unsubscribe-auth/AB5O3URBNHHNZHV73WZBALTY235OHAVCNFSM6AAAAAATKN2SD2VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDAMRYGQYDCNZWGA> > . > You are receiving this because you were mentioned.Message ID: > ***@***.***> >

kerem commented

2026-02-26 02:34:33 +03:00

Author

Owner

@TheRealGramdalf commented on GitHub (Mar 30, 2024):

That should technically work, but in some cases that kind of defeats the point of SSO. I would take a look at https://github.com/paulgessinger/swift-paperless/issues/50 for reference, they're going through a very similar process

@TheRealGramdalf commented on GitHub (Mar 30, 2024): That should technically work, but in some cases that kind of defeats the point of SSO. I would take a look at https://github.com/paulgessinger/swift-paperless/issues/50 for reference, they're going through a very similar process

kerem commented

2026-02-26 02:34:33 +03:00

Author

Owner

@phanan commented on GitHub (Mar 30, 2024):

I agree that the idea of using email/password defeats the point of SSO, but
I’d still think it’s a fair tradeoff to support two (very different
platforms) considering the maintenance effort. Furthermore, the mobile app
authentication typically must be done only once, as the token is
long-lived. Thoughts?

On Sat, Mar 30, 2024 at 19:31 TheRealGramdalf @.***>
wrote:

That should technically work, but in some cases that kind of defeats the
point of SSO. I would take a look at paulgessinger/swift-paperless#50
https://github.com/paulgessinger/swift-paperless/issues/50 for
reference, they're going through a very similar process

—
Reply to this email directly, view it on GitHub
https://github.com/koel/koel/issues/1642#issuecomment-2028435694, or
unsubscribe
https://github.com/notifications/unsubscribe-auth/AB5O3UUJ3SLYU3X5MGURA7DY24AGXAVCNFSM6AAAAAATKN2SD2VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDAMRYGQZTKNRZGQ
.
You are receiving this because you were mentioned.Message ID:
@.***>

@phanan commented on GitHub (Mar 30, 2024): I agree that the idea of using email/password defeats the point of SSO, but I’d still think it’s a fair tradeoff to support two (very different platforms) considering the maintenance effort. Furthermore, the mobile app authentication typically must be done only once, as the token is long-lived. Thoughts? On Sat, Mar 30, 2024 at 19:31 TheRealGramdalf ***@***.***> wrote: > That should technically work, but in some cases that kind of defeats the > point of SSO. I would take a look at paulgessinger/swift-paperless#50 > <https://github.com/paulgessinger/swift-paperless/issues/50> for > reference, they're going through a very similar process > > — > Reply to this email directly, view it on GitHub > <https://github.com/koel/koel/issues/1642#issuecomment-2028435694>, or > unsubscribe > <https://github.com/notifications/unsubscribe-auth/AB5O3UUJ3SLYU3X5MGURA7DY24AGXAVCNFSM6AAAAAATKN2SD2VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDAMRYGQZTKNRZGQ> > . > You are receiving this because you were mentioned.Message ID: > ***@***.***> >

kerem commented

2026-02-26 02:34:33 +03:00

Author

Owner

@TheRealGramdalf commented on GitHub (Mar 30, 2024):

This may be more work, but you could also employ the use of an API token directly - log in to the the WebUI in a browser, and it gives you a QR code/access token. Scanning the QR code/inputting the access token (which could be short lived, like a TOTP) in the koel app would contact the server, and it could issue a proper long-lived API token. This would require changes in the mobile app, but would be relatively simple compared to implementing native SSO - it would mostly be a re-use of the password feature (I would just forget about usernames here, since the access token is already tied to the account, and that would simplify things in terms of mapping an email/displayname to a UUID).
This would be similar to how Jellyfin does quick connect - which is how 9p4/jellyfin-sso supports mobile apps currently (native SSO support is on the official roadmap in the future).

@TheRealGramdalf commented on GitHub (Mar 30, 2024): This may be more work, but you could also employ the use of an API token directly - log in to the the WebUI in a browser, and it gives you a QR code/access token. Scanning the QR code/inputting the access token (which could be short lived, like a TOTP) in the koel app would contact the server, and it could issue a proper long-lived API token. This would require changes in the mobile app, but would be relatively simple compared to implementing native SSO - it would mostly be a re-use of the password feature (I would just forget about usernames here, since the access token is already tied to the account, and that would simplify things in terms of mapping an email/displayname to a UUID). This would be similar to how Jellyfin does quick connect - which is how 9p4/jellyfin-sso supports mobile apps currently (native SSO support is on the official roadmap in the future).

kerem commented

2026-02-26 02:34:33 +03:00

Author

Owner

@phanan commented on GitHub (Mar 30, 2024):

That’s a great idea! I will investigate more into the direction, thank you.

On Sat, Mar 30, 2024 at 19:57 TheRealGramdalf @.***>
wrote:

This may be more work, but you could also employ the use of an API token
directly - log in to the the WebUI in a browser, and it gives you a QR
code/access token. Scanning the QR code/inputting the access token (which
could be short lived, like a TOTP) in the koel app would contact the
server, and it could issue a proper long-lived API token. This would
require changes in the mobile app, but would be relatively simple compared
to implementing native SSO - it would mostly be a re-use of the password
feature (I would just forget about usernames here, since the access token
is already tied to the account, and that would simplify things in terms of
mapping an email/displayname to a UUID).
This would be similar to how Jellyfin does quick connect - which is how
9p4/jellyfin-sso supports mobile apps currently (native SSO support is on
the official roadmap in the future).

—
Reply to this email directly, view it on GitHub
https://github.com/koel/koel/issues/1642#issuecomment-2028442126, or
unsubscribe
https://github.com/notifications/unsubscribe-auth/AB5O3UVC36CIMEBEPBPNQATY24DKBAVCNFSM6AAAAAATKN2SD2VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDAMRYGQ2DEMJSGY
.
You are receiving this because you were mentioned.Message ID:
@.***>

@phanan commented on GitHub (Mar 30, 2024): That’s a great idea! I will investigate more into the direction, thank you. On Sat, Mar 30, 2024 at 19:57 TheRealGramdalf ***@***.***> wrote: > This may be more work, but you could also employ the use of an API token > directly - log in to the the WebUI in a browser, and it gives you a QR > code/access token. Scanning the QR code/inputting the access token (which > could be short lived, like a TOTP) in the koel app would contact the > server, and it could issue a proper long-lived API token. This would > require changes in the mobile app, but would be relatively simple compared > to implementing native SSO - it would mostly be a re-use of the password > feature (I would just forget about usernames here, since the access token > is already tied to the account, and that would simplify things in terms of > mapping an email/displayname to a UUID). > This would be similar to how Jellyfin does quick connect - which is how > 9p4/jellyfin-sso supports mobile apps currently (native SSO support is on > the official roadmap in the future). > > — > Reply to this email directly, view it on GitHub > <https://github.com/koel/koel/issues/1642#issuecomment-2028442126>, or > unsubscribe > <https://github.com/notifications/unsubscribe-auth/AB5O3UVC36CIMEBEPBPNQATY24DKBAVCNFSM6AAAAAATKN2SD2VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDAMRYGQ2DEMJSGY> > . > You are receiving this because you were mentioned.Message ID: > ***@***.***> >

kerem commented

2026-02-26 02:34:33 +03:00

Author

Owner

@phanan commented on GitHub (Mar 31, 2024):

@TheRealGramdalf Can you do me a favor and reach out to me@phanan.net? I'd like to discuss a bit further on this topic.

@phanan commented on GitHub (Mar 31, 2024): @TheRealGramdalf Can you do me a favor and reach out to me@phanan.net? I'd like to discuss a bit further on this topic.

kerem commented

2026-02-26 02:34:33 +03:00

Author

Owner

@phanan commented on GitHub (Jul 10, 2024):

Implemented as beta in v7 Plus.

@phanan commented on GitHub (Jul 10, 2024): Implemented as beta in v7 Plus.

kerem referenced this issue

2026-02-26 03:30:58 +03:00

[PR #895] [MERGED] Bump phpunit/phpunit from 7.5.1 to 7.5.2 #1426

Rows
Columns

[GH-ISSUE #1642] SSO via proxy auth header #895