Authorization Headers, Windows and HTTP 2

Putting this out there for Google if anyone else runs into the same weird problem that we did.

TL;DR — The HTTP 2 stack that ships with Windows (and therefore, IIS) terminates requests if your Authorization header does these 2 things:

  1. Doesn’t follow the <scheme> <token> format. ie, if you just stuff a token in there without some scheme and a space character before it
  2. The token contains special characters (like : or /)

If you’re designing a custom authentication mechanism (ie, an API Key or Session Token mechanism) for your web service API, you probably want to use the Authorization header to pass credentials along. Its more secure than sending it as a query string and the body of the request is ideally only allocated for the payload of your API.

You should also make sure you follow the proper format for the contents of the header.

Basically, you should use something like:

Authorization: <my-scheme> <api-key>

<my-scheme> should be something related to your app — it could be your app name. What it shouldn’t be is:

  • Basic — This is reserved for basic authentication
  • Bearer — This is reserved for OAuth2
  • A whole bunch of others
  • Nothing

That last point is what tripped us up.

Our default authentication mechanism involves just stuffing an api key into the Authorization header.

Furthermore, the api key had special characters in it.

Example: Authorization: AP/C332DF98DDF

If you try sending this to IIS, you will find that your request gets terminated. Browsers don’t print any response — no header, no body, nothing.

The solution is to disable HTTP 2.

Or, if its possible, change the format of your Authorization header.

Like what you read? Give Haran Shivanan a round of applause.

From a quick cheer to a standing ovation, clap to show how much you enjoyed this story.