[API Request] New proper secure authentification

[Tolriq]

Type of change

API extension

Proposal description

This is again a template issue to gather feedback and ideas from clients and servers.

Current v1.13 authentification system is a mess as force servers to store the credential in clear.

The need is to offer a new authentication system that allows servers to properly store hashed passwords, and probably also support some kind of revokable API keys to allows users to disable app access without having to change their main password.

Backward compatibility impact

No response

Backward compatibility

• No backward compatibility impact.

API details

TBD

Security impacts

No response

Potential issues

No response

Alternative solutions

No response

[spl0k]

Just an idea: a revokable key could be used without changing anything on the API if you feed it on the p parameter instead of the actual password. You'd need a way to issue and revoke them though. That may be not practical from a user standpoint but it could be done through the server's UI. I wouldn't be surprised if some servers already did this.

[Tolriq]

This works as a possible solution, but still needs to be handled as an extension, by default most servers are API 1.16.1 so should support the new auth that is a little more secure from the client side. So should be preferred over something that sends the password in clear.
Most users don't understand HTTPS so we need to assume the data pass in clear.

[tamland]

I think servers should at least support passing auth info in the Authorization header instead of the URL as this will prevent common leakage issues with browser clients.

However, the main blocker currently is that streaming URLs and image URL must be constructed by the client and include auth parameters. These will be have to be returned by the server instead such that they can be loaded directly by the browser.

After this, extending support for e.g. OIDC should be possible

[Tolriq]

That's why you would use an opaque URL return by the server for media streams and images.

As explained earlier not really, this is bad for anything that sync and cache things. The auth part must be clearly identified and be able to be handled on client side as not part of the cache.
This is a given to allow any image / media cache working on the client side. Including handling all of the parameters like transcoding or image resizing.

Now if that auth part is to be regenerated at each access by requesting a temporary token for each access this creates a tons of burden and unnecessary requests and load and should be avoided at all cost.

The new auth can totally generate tokens with only a given duration that needs to be refreshed like oauth with x hours validity. But requesting token for everything does not make sense in this case, as it does not bring any more security.

If the new auth system works with refreshable tokens we address your concern. Even if we only decide to go with app tokens, they would be easily revocable on server side and mostly fit your concerns too as not leaking the actual account or auth.

[acroyear]

So really what we're looking for is rather than a universal and permanent T+S*, we look at an auth mechanism that is more secure, which returns a token (maybe a JWT, maybe something smaller) that has an expiration to it.

mind you, there's a lot of demand for oauth in order to support voice recognition services like Amazon's. Those apps require oauth sessions. I could have implemented an oauth wrapper but I couldn't see a way that didn't require giving my service total access to the username/passwords (or a T+S combo) in order to then return the underlying url.

[Tolriq]

The main issue is that the current token + salt is absurd in the term of data storing on server side. The servers must store the password in plain text and this is not secure. So some servers do not want to implement this.

OOauth or JWT would be nice, but any solution that improve security while allowing servers to store hashes will be good too.

[tamland]

Servers can still require clients passing clear password which will allow secure storage. T+S does not work with LDAP users so clients already needs to fallback to password to work reliably for all servers/users.

Does the md5 scheme even add anything at this point beyond obfuscation?

[Tolriq]

We can only suppose at this point, but the md5 solution with salt was a common solution to not store password in plain text on server database back then.
This was strangely applied to the auth API here in a way that quite defeat the purpose as while the password does not travel in clear, it must be stored in clear on server side.
LDAP forwarding does not require the server to store the password in clear, just to forward it. So behind https it's not an issue by itself. If people are able to use an ldap server for auth they should understand https and clear text passwords.

[Tolriq]

So since there's movement, let's restart the discussion about this major difficulty for OpenSubsonic.

This is the most complex change but it's wanted and welcome by many, so let's try to figure out a solution that covers most case and solve current issues.

[dweymouth]

The only request I have for this right now is that whatever scheme we choose must be able to pass the auth token as a URL param and not require the Authorization header, since some clients use a 3rd party library (like libmpv) that actually handles the HTTP request to stream the file, and we can only pass it the URL, not headers.

[sentriz]

using HTTP headers for 90% of requests + having endpoints like stream.view and getCover.view be "open" (no authorization required) feels like a reasonable tradeoff to me

since for those two,

• browsers need to render covers with just a <img />, only a URL no headers
• MPV, Sonos, Chromecast, browser <audio /> tags, etc - all expect simple URLs too

maybe these should be public, and use HTTP basic auth everywhere else (DSub supports this)

[Tolriq]

Let's try to be secure and avoid public data and images, this is problematic because it can expose copyrighted data, have huge performance issue if starting tons of transcoding sessions and some servers have well known predictable ids.

[Tolriq]

Another bump, this is not something I will design on my own, security is complex, different servers may have different needs and requirements, I'm not expert enough in this field to be able to recommend something that I know will be the best solution that covers all the needs.

[tamland]

Quick (not extremely well thought out) suggestion based on oauth:

1. Server/Client uses OIDC Discovery protocol to announce/discover OAuth2 endpoints.
2. Client uses Password grant type to obtain an access token: https://datatracker.ietf.org/doc/html/rfc6749#section-4.3
3. Client passes the access token to the server as query string as access_token, deprecating u, p, t, s

This is the simplest solution I can think of and shouldn't be hard for severs that already support login to implement. This can later be extended with Authorization Code grant, passing access token i header etc. Using OIDC Discovery also allows servers optionally to delegate authorization to a different server entirely.

[tamland]

Another possibility: https://indieauth.net/

[epoupon]

@Tolriq what are the authentication methods of the other servers you support?

[Tolriq]

Well many different things :) Kodi is Basic auth, Plex and Emby use access_token with a few different ways for each to get one. When the token expires returns 401 and you auth again.

[crazygolem]

Hello,

I want to add a perspective to the discussion: as developer of neither a subsonic client nor server, I recently wrote a Traefik plugin to convert the subsonicauth parameter to a basicauth header, with the goal of being able to transparently delegate authentication to a 3rd-party (at the reverse proxy level) and ultimately get rid of the need for reversibly encrypted credentials in my Subsonic backend.

Following this, here are my thoughts on the integration issue (I have additional remarks on the security/confidentiality aspects, but they might be the topic of a separate comment).

The subsonicauth scheme expects proper subsonic responses in case of authentication failures, and specifically a response with an HTTP 200 status and a subonsic-response/error in the body, in XML or JSON depending on the f parameter. This required for me to rewrite responses from the 3rd-party authentication service, as it does not (and is not expected to) know anything about subsonic authentication.

This means in turn that I had to add some required/expected fields in the response, that make the process not entirely transparent to the client, and leads to ambiguity about how to properly handle the Subsonic/OpenSubsonic protocol. In particular:

• I only support simple subsonicauth, with u and p parameters. Should the version field reflect the version supported by the backend Subsonic server (1.16.1), or match the API level for only the authentication part (< 1.13.0)? The question is similar for the openSubsonic field: return what the backend supports (true), or what my authentication layer supports (not relevant)? I decided to match my current backend, because I don't know how clients handle this information, and I think they are the most likely to have dedicated code paths that kick in in case of error, and should not really impact authentication anyway, but this means I have to closely track updates to my backend in order to update the rewrite filter accordingly.
• The type and serverVersion fields are also required by OpenSubsonic, and expose the same ambiguity. I decided to not match my backend, because I think they are the least likely to have problematic dedicated code paths, and if they do, I probably want to disable all non-standard handling from clients as far as authentication is concerned. The backend's values are returned anyway in case of authentication success, but it might still be an issue if the values are cached by clients on errors.

The issues are compounded if you want to host several Subsonic servers behind the same reverse proxy (not my case, and it would be kind of insane anyway).

And for clients that already support alternative authentication schemes, like Symfonium and DSub that support basicauth, it is not entirely clear whether they expect a subsonic or a protocol-approriate response in case of authentication error with the alternative scheme.

Ideally, from an integration perspective and specifically to simplify delegating authentication to specialized services, alternative authentication schemes should be decoupled a bit from the rest of the OpenSubsonic API:

1. Protocol-appropriate response handling from clients (since some clients support basicauth already, we might need to carve out an exception, but IMO either way it has to be specified fast to avoid further issues in the long term).
2. In case of subsonicauth, clarification of how required metadata in the response should be handled by clients in case of authentication errors; ideally they should be optional in this case, as it simplifies integration a lot and reduces information disclosure to potentially malicious clients.
3. If a public metadata endpoint is needed, one should be dedicated to authentication metadata (Symfonium uses the Subsonic ping endpoint as a makeshift metadata endpoint with its pre-auth test requests), and should not need to contain data about the Subsonic server.

Additionally, from my perspective as an integrator, I see authentication as mostly a client issue: If a subsonic server does not support any authentication scheme, but does support a way provide the information about which user has made the request, I can work with it by implementing the authentication myself. On the other hand, if the server supports only specific authentication schemes (that require the server to handle user credentials), I'm screwed, and most likely will need to resort to hacks to make it work (like a hardcoded dummy credential for all users, which can be forwarded from my reverse proxy after the user has been properly authenticated).

I hope this helps =)

[Tolriq]

Well yes the global idea will be mostly to something to get a token via a way :)

Then pass the token in all calls and expect error 401 when token invalid or expired.

[lachlan-00]

For Ampache passwords the hash is sha256. i don't really care what is chosen but at a minimum a hash of at least sha256 would be a start. (I'll just add a column for additional implementations.)

So if we set a standard hash then the token auth will be able to use a hashed password.

For alternative auth. Ampache uses a Bearer Authorization token which allows removing the auth parameter from the url
https://ampache.org/api/#http-header-authentication

Setting a standard hash and then allowing for a token in the header would solve a lot of the problems with auth.

For additional token/app access for individual clients, a separate column (or table for multiple entries) following the same encryption/header style. Ampache only has a single api key field for users but could be expanded into per-client tokens.

but that's what i'd do, header auth and a standard hash encryption

[lachlan-00]

definitely optional. parameter auth isn't going away so setting a standard hash will also help

[Tolriq]

Standard hash does not solve the issue about servers doing the authentification externally like ldap or other trust sources. At some point in the authentification process the servers will need a way to have the info or a way to forward it to something else. And hashes (not encryption) do not work for that.

[lachlan-00]

ldap passwords aren't stored on the server though so db and external auth aren't the same thing

[Tolriq]

That's the whole point of the authentification issue, the legacy one send the password in clear and it's bad for non https stuff. But it allows servers to authenticate to other sources without having to store the password in clear in db.
The new auth uses hashes and salt so the password is not sent in clear, but to be able to decode on the server side it requires the password to be stored in clear, that is a big security issue.
So the new solution should allow external auth but still allow the server to NOT store the password in plain text.

The main goal being that the password should be sent at most once if needed then a token is used to avoid password leak.

[perillamint]

The "new auth" should be deprecated in Open Subsonic specification for the following reasons:

• Nowadays, TLS is ubiquitous thanks to hard effort of ISRG people (Let's Encrypt)
• MD5 is broken decades ago.
• Securing the inner tunnel with any hashing algorithm prevents usage of more secure password hash in the future, and current auth scheme forces server implementations to store the password in weak MD5 format.

However, in "legacy" auth

• Server can store the password in a much more secure manner and validate it against the given password.
• Server can decide to transport cryptographically signed API token using "legacy" auth, because it delivers "password" as-is.

I think, at least, the spec should recommend the old "legacy" way with TLS setup. This will simplify lots of things for now.

[Dracyr]

Hey! I was reading through this thread, and having implemented a few auth solutions at $DAY_JOB I thought I could maybe help out with some ideas, also summarizing some ideas from earlier in the thread.

To reiterate from what I've read: There are two main security issues we would like to resolve with an iteration on the authentication.

• Credentials are passed through the URL
• Plaintext password storage

We also have the following client types (or let me know if I missed something)

• Web browsers
  • Server Side Rendered, browser -> webserver -> subsonic server
  • Single Page App, browser -> subsonic server
• Mobile apps
• Chromecast, UPnP/DLNA clients
  • Triggered by an already authenticated app
  • These have the additional constraint that credentials would have to be passed via the URL

Proposal

sequenceDiagram

Client->>Server: POST /login
Server->>Client: {"token": "<token>"}
Client->>Server: GET /stream
Note left of Server: Authorization: Bearer <token>
Server->>Client: 200 OK
Client->>Server: POST /playbackToken
Server->>Client: {"playbackToken": "<playback-token>", "expiresIn": 600 }
Client->>Device: Play media at /stream?t=<playback-token>
Device->>Server: GET /stream?t=<playback-token>
Server->>Device: 200 OK

In brief:

• Adds a /login endpoint to exchange a username+password for a long-lived API Token
  • The token grants access to the full API
  • The token must be passed through an Authorization header
  • Servers must return an unauthorized error if it is passed as a query parameter
• Adds a /playbackToken endpoint returning a short-lived playback token for devices that cannot pass a token via headers
  • The Playback Token is only valid for stream/image endpoints
  • The Playback Token is passed as a query parameter ?t=<playback-token> in the URL
  • Other possible names: device-token, stream-token, cast-token
• Add a /logout endpoint that invalidates the API Token

This solves the plaintext password issue for servers, and additionally allows them to delegate login, for example to LDAP or other solutions to not have to store credentials.
For the most part it mitigates issues with credentials in the url, setting a short expiry on the playback token and restricting its usage to certain endpoints.

I would deliberately leave the format of the token opaque in the protocol, leaving it up to server implementations to decide based on their needs and be flexible for the future.
It might make sense to define a somewhat sane minimum length though. I quite like the overview of different tokens in API Tokens: A Tedious Survey.

For clients that don't implement Casting/DLNA, they also won't need to take on the extra complexity of managing multiple tokens and the whole flow is kept rather simple.

A possible downside is confusion around "which token to use where", so naming and documentation is quite important. And I'm not sure if this would be an issue in practice, but servers could try to skip implementing the endpoint and token handling.

There is another step for the clients and servers to implement, and browser based clients need to be careful with token storage to prevent XSS vulnerabilities. But overall the user flow remains the same, and implementation is simple.

Alternatives

A1. Refresh Token

This is alternative is a variation of the proposal, where the core flow is the same and it still uses two tokens, but differently.

• A successful login returns both a long lived Refresh Token, and a short lived App token
• The App token grants access to the entire API and is passed in the Authorization header
• For Streaming/Image endpoint, the App token can also be passed in a ?t=<token> URL query parameter
• The Refresh Token is only used for fetching an App token, and clients periodically refresh their App token using the Refresh token

sequenceDiagram

Client->>Server: POST /login
Server->>Client: {"token": "<token>", "expiresIn": 600, "refreshToken": "<refresh-token>"}
Client->>Server: GET /stream
Note left of Server: Authorization: Bearer <token>
Server->>Client: 200 OK
Client->>Device: Play media at /stream?t=<token>
Device->>Server: GET /stream?t=<token>
Server->>Device: 200 OK

Note right of Client: Time passes
Client->>Server: POST /refreshToken
Server->>Client: {"token": "<token>", "expiresIn": 600}

This approach mainly mitigates server API fragmentation, since authentication for all endpoints are the same. Passing the token as a query parameter could still be restricted to the stream/image endpoints to make it more secure. In that case servers need special handling of the tokens for those endpoints anyway, and the clients need logic to pass a token to the device anyway, so implementation effort would be roughly the same.
Plausibly this solution could be more performant for servers as well, since if tokens are short-lived servers could choose to issue JWTs or other signed tokens that don't require a lookup in a session store or db to check validity. Based on my experience it could still be a wash due to the increased crypto operations, wouldn't make that a large consideration.
In case of accidental exposure of the app token, it would allow access to all endpoints during its validity however, compared to the playback token which is more restricted.

A1. OAuth2/OIDC

Auth0: Authentication Code Flow (PKCE)

Using OAuth2/OIDC would allow servers to completely delegate authentication to a third party, and a lot of self-hosters are already running a Identity Provider with support for those protocols.

Using OAuth2 between the client and server directly, without a third party makes less sense to me. That is what those protocols are designed for after all, and in other cases add a lot of complexity without clear advantages.

I see a few reasons why I would caution against this:

• Implementation effort for both clients and servers is higher, and the flows harder to understand, making it more likely that there is more fragmentation in support
• Would user+password authentication still need to be supported or is it dropped?
  • If dropped this also forces users to figure out which authentication solutions to add to their stack.
  • And the user+password authentication still need to be rethought.
• How to handle casting URLs would still need to be defined exactly.
• Many Auth Providers also provide LDAP(S) support, or it can be added, so centralized authentication is still possible without OAuth2.
• The protocol would be locked into the OAuth2 ecosystem, making it harder to evolve the authentication further in the future.

Overall, I'd be the most worried about the change-management of clients/severs/users upgrading though, as while it's more complicated there are plenty of examples and libraries. Defining a protocol extension for OAuth2 authentication could be a nice middle ground as it would be very useful to have.