Custom HTTP Authorization Header

Question

I was wondering if it's acceptable to put custom data in an HTTP authorization header. We're designing a RESTful API and we may need a way to specify a custom method of authorization. As an example, let's call it FIRE-TOKEN authentication.

Would something like this be valid and allowed according to the spec: Authorization: FIRE-TOKEN 0PN5J17HBGZHT7JJ3X82:frJIUN8DYpKDtOLCwo//yllqDzg=

The first part of the second string (before the ':') is the API key, the second part is a hash of query string.

Solution 1

The format defined in RFC2617 is credentials = auth-scheme #auth-param. So, in agreeing with fumanchu, I think the corrected authorization scheme would look like

Authorization: FIRE-TOKEN apikey="0PN5J17HBGZHT7JJ3X82", hash="frJIUN8DYpKDtOLCwo//yllqDzg="

Where FIRE-TOKEN is the scheme and the two key-value pairs are the auth parameters. Though I believe the quotes are optional (from Apendix B of p7-auth-19)...

auth-param = token BWS "=" BWS ( token / quoted-string )

I believe this fits the latest standards, is already in use (see below), and provides a key-value format for simple extension (if you need additional parameters).

Some examples of this auth-param syntax can be seen here...

https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-p7-auth-19#section-4.4

https://developers.google.com/youtube/2.0/developers_guide_protocol_clientlogin

https://developers.google.com/accounts/docs/AuthSub#WorkingAuthSub

Solution 2

Put it in a separate, custom header.

Overloading the standard HTTP headers is probably going to cause more confusion than it's worth, and will violate the principle of least surprise. It might also lead to interoperability problems for your API client programmers who want to use off-the-shelf tool kits that can only deal with the standard form of typical HTTP headers (such as Authorization).

Solution 3

No, that is not a valid production according to the "credentials" definition in RFC 2617. You give a valid auth-scheme, but auth-param values must be of the form token "=" ( token | quoted-string ) (see section 1.2), and your example doesn't use "=" that way.

Solution 4

Old question I know, but for the curious:

Believe it or not, this issue was solved ~2 decades ago with HTTP BASIC, which passes the value as base64 encoded username:password. (See http://en.wikipedia.org/wiki/Basic_access_authentication#Client_side)

You could do the same, so that the example above would become:

Authorization: FIRE-TOKEN MFBONUoxN0hCR1pIVDdKSjNYODI6ZnJKSVVOOERZcEtEdE9MQ3dvLy95bGxxRHpnPQ==

View more solutions

Comments

[NRaf]

That's not correct. See page 5 of the document for an example format: Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

[fumanchu]

That's true. But as tools.ietf.org/html/draft-ietf-httpbis-p7-auth-16#section-2.‌​3.1 says, "The "b64token" notation was introduced for compatibility with existing authentication schemes and can only be used once per challenge/credentials. New schemes thus ought to use the "auth-param" syntax instead, because otherwise future extensions will be impossible." See also the cache discussion there regarding doing auth in custom headers.

[Jon-Eric]

This might be harder to get right than it appears. The link that fumanchu provides (in a comment to his answer) explains why introducing a custom header adds the additional burden of now having to manually set the Cache-Control correctly.

[Wil Moore III]

Also, if you are making an cross-origin request via the browser, you are now in pre-flight territory just because of the custom header where you otherwise could have avoided it. For certain applications, these requests add up.

[bishop]

Amazon's simple storage API offers another example.

[Les Hazlewood]

Huge no to custom authentication headers. The spec-standard Authorization header with your own custom scheme should be more than sufficient. Plus you avoid pre-flight Origin requests as @wilmoore indicates. Custom schemes do not interfere with any reasonably modern HTTP server that I know of, plus if you use your own scheme, you'll have to parse it yourself - no library should conflict (otherwise the library is written poorly).

[Whymarrh]

I would advise against this answer, as, per a comment on another answer here, the notation used here is for compatibility with existing schemes and is not recommended for new extensions.

[Eron Wright]

A good reason to transmit credentials in the Authorization header, rather than in a custom header, is that proxies and loggers know to treat the information as being sensitive.