The first step in implementing an authentication module for IIS/ASP.NET is to understand the authentication protocol (doh ;)

It turns out the Basic Authentication is quite simple. Whenever the server wants to start the authentication handshake, he sends a 401 HTTP status code with a special HTTP header named WWW-Authenticate e.g.

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Basic realm=”leastprivilege”

When a browser receives such an HTTP response, he typically opens a logon dialog box. The realm is some extra parameter that can be used by the client.

After the user has entered his credentials, these are sent back to the server as a base64 encoded HTTP header named Authorization:

GET /default.aspx HTTP/1.1
Authorization: Basic YWxpY2U6Z29vZHdvcmtub3d5b3VjYW5zZWVteXBhc3N3b3Jk

The server then grabs the authorization header, decodes it, and verifies the credentials against some back end store. Very simple. After that the server either grants access or returns an HTTP 403 (forbidden).

Some notes

• the value of the Authorization header is using the iso-8859-1 character set.
• the credentials are only base64 encoded. This means they are sent in clear text. You should only use Basic Authentication when you layer SSL on top of it.
• IIS forces authentication when Basic Authentication is the only selected authentication method.
• When anonymous access is allowed too, IIS only starts the authentication handshake when it sees a 401 status code coming back (e.g. from ASP.NET’s URL authorization)
• IIS uses the username/password values to call Win32 LogonUser. The result is a Windows token.
• the Authorization header is sent to the server on every request after the user entered credentials. That means the server has to somehow verify the credentials on each request.
• IIS caches the Windows token – by default for 15 minutes. This can be configured in HKLMSystemCurrentControlSetServicesInetInfoParametersUserTokenTTL

OK – now we understand how the protocol works. In the next post I will show you how to use the HTTP pipeline to implement the authentication module.