Allow to pass API token using "Authorization" HTTP header as "bearer" token

[uschindler]

This is a followup after #19234:

Currently you can only pass the token_auth parameter containing the API token with GET or POST. If you do it with GET, the token is visible in logs (on possibly both client and server). After #19234 you can enforce to pass the token in the body of a POST request. But from an REST perspective this is not "correct". GET is to query an API (like statistics/reporting), but POST should only be used to post new content (e.g., to modify it, which is not the case for reporting API). In addition, adding the token authorization to query parameters / form-parameter (in body) is not separating authorization from the API semantics.

Basically the correct way to pass authorization information in HTTP is using the Authorization header. The header is defined in HTTP/1.1 and contains 2 informations:

• authentication scheme
• auth parameters (e.g, a token)

For token based auth, the OAuth and REST standard recommend to use "Bearer" as scheme and the token itsself as parameter. See https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication#authentication_schemes about schemes and https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization for the general header syntax.

This would allow to call the API of Matomo in a standards conformant way:

• Use GET requests to query information and have all query parameters in URL
• Pass the token as Authorization header like that: Authorization: Bearer ....token...

This makes request log files not expose tokens but still allows to log everything relevant to the REST call.

Implementation in Matomo should be easy: Just read header via $_SERVER[HTTP_AUTHORIZATION],and apply a regex like ^Bearer\s+(\S+)$ and use capture group \1. According to OAuth standards the scheme "Bearer" should be written with initial uppercase letter, but most implementations in REST frameworks also accept it case insensitive, so use case insensitive regex matching.

I would also suggest to change the config setting only_allow_posted_auth_tokens introduced by #20351 to be renamed to disallow_auth_tokens_via_urlparams (or similar). Because a GET request for API is still valid and recommended , only the token_auth parameter should not be posted as URL param.

I'd like you to rethink your decissions in previous issues and for Matomo 5.0 to better propagate "correct" auth and don't force users to use POST as "workaround". Separate auth and API parameters completely!

For backwards compatibility allow to still post tokens in GET/POST parameters, but allow it to be disabled (see above) as URL parameters and disable it in 6.0 by default. In addition, update docs to help users migrate their code to either POST with form-parameters in body or (better) separate auth to Authorization header.

[michalkleiner]

Hi @uschindler and thank you for raising a new follow up enhancement issue for the authorisation header. I agree that it would be a better, more standards-conformant way. I'll assign this to the product team for prioritisation.
There might still be time to rename the config param for Matomo 5.

[jorgeuos]

I was also trying to use a Bearer Token because I created a Secure Token. And to my surprise it didn't work. So I will follow this thread for updates.