Some may say this is unnecessary (and not too long ago I would have agreed) but these days, with so many auth protocols, if we use the
Authorization header to pass an API key, it is worth informing the type too because API keys are not self-descriptive per se 1.
Why do I think it is worth it? Because nowadays supporting different authentication or/and authorization protocols has become a must-have. If we plan to use the
Authorization header for all these protocols, we have to make our auth service consistent. The way to communicate what kind of token we send and what authorization protocol should be applied should go in the header too.
Authorization: Basic XXXX
Authorization: Digest XXXX
Authorization: Bearer XXXX
Authorization: ApiKey-v1 XXXX
Authorization: ApiKey-v2 XXXX
I used to don't care about this, but after working with mobile clients or sensors, in which updates were not guaranteed, I started to. I started to be more consistent in the way I implement security so that I can keep backwards compatibility. With the token's type informed I can invalidate requests from a specific set of clients (the outdated ones), add new schemes and differentiate old clients from new ones and change auth validations for one or another scheme without causing breaking changes. I also can apply specific rules in the API Gateways based on the authorization scheme. For example, I can redirect old schemes to specific versions of my web APIs which are deployed apart from the main ones.
The problems I faced implementing my own schemes have been similar to the one commented.
On the other hand, I found a consideration that a custom Authorization
scheme can be unexpected and unsupported by some clients and leads to custom code anyway
Say clients, say libraries, frameworks, reverse proxies. A custom header can be rejected or ignored. In the worse of the cases, it can also collide.
Collisions can be problematic, but all other issues are likely to be solved by tackling configurations.
One important advantage is cache. Shared caches won't cache the header (and that's good of course) unless you say otherwise.
So Authorization or custom header?
In my experience, both take me almost the same work and time to implement, with a slight difference. I had more room for design when I implemented custom headers. However, more room for design also meant more chances to overcomplicate things or reinvent the wheel.
Technically, there could be very little or no difference between the two, but I have found the consistency to be a good feature. It provides me with clearness and understanding. In my case, adding new schemes was reduced to adding 2 new abstractions (implemented by the same concrete class): TokenHandler and TokenValidator. The
Handler only checks whether the request header
Authorization informs the supported scheme. The
Validator is anything I need to validate the token. Altogether working from a single request filter instead of a chain of filters or a big ball of mud.
1: I find this answer to be very clear regarding API Keys