CustomAuth Overview

Since there is already an excellent overview for the original CustomAuth, I’m not going to re-invent the wheel. However, that overview is in a help file for CustomAuth on Windows Server 2003 and I could not find it anywhere on the web. So for the purpose of sharing that useful information to as many people as possible, I have taken that overview and put it into a word doc. This information will be skipping ahead of what I’m going to discuss in this post, but most of it is relevant.

CustomAuth Documentation

So after reading the initial documentation above, you should have a general understanding of the original purpose of the original CustomAuth.

The way CustomAuth works is based on denied permissions to access a file on a web server. When someone that is not authenticated tries to access a webpage, they access the page’s physical file using the anonymous user account (IUSR_*). This authentication method denies access to that page for the anonymous user, thus throwing a 401 denied access error response. Since CustomAuth is actually two parts, an ISAPI Filter and an ISAPI Extension, the filter portion is what catches this 401. The filter sees that this error was thrown and replaces that response to the user with a 302 redirection response to the login page, which is set in the CustomAuth.ini file.

One of the modifications added to the CustomAuth filter is the ability for redirection back to the original page trying to be accessed. This is done by adding the original url as a querystring variable added on to the login page url. So instead of just redirection to www.domain.com, we instead redirect to www.domain.com?url=www.domain.com/stuff/page.aspx. Then the login page can take that url and redirect to it instead of the normal login success url defined in the CustomAuth.ini file.

So the filter portion has redirected the user to the login page. The login page will take the user’s credentials and put them into a cookie. Normally the credentials would be in cleartext and each time the server reads the cookie it would be in cleartext. Using SSL is suggested, which with CustomAuth, SSL can be used while giving the functionality of Basic authentication. I suggest using some form of encryption along with SSL, which will provide more security, however you will need encryption that can be decrypted inside the filter which is written in C++.

Once the user logs in and the cookie is created, the ISAPI extension checks for the cookie and pulls the credentials from it. It then attempts to log the user into the server with those credentials. If the login fails, the user is redirected back to the login page. If the login was successful, the user is redirected to the login success page or the original page they were trying to access. Now any file the user has ACL read access to can be viewed, since they are no longer using the anonymous user credentials but their own ACL permissions. Additional permission restrictions can be applied to the user inside the website code as well, so instead of permission being granted or denied based on ACL permissions, they are instead given or denied based on a user group or database entry.

Since the credentials are stored in a cookie, the user will no longer need to login as long as that cookie persists. Also, if the cookie is setup with a specified domain, such as .domain.com, any subdomain that has the CustomAuth filter installed on it will automatically log the user in as well. So if two websites have the filter installed, books.domain.com and cooking.domain.com, if the user logs into one of the sites, they will automatically be logged into the other if they visit it.

Now the user can also log out of the server with CustomAuth. A simple link needs to be provided that the user can click and log off. When the user logs off, they will be redirected to a specified log off page set in the CustomAuth.ini file.

This was a very basic overview of CustomAuth and the modified CustomAuth on the flow of how it works. There is alot missing here, but hopefully it will give an idea of the general steps involved in this authentication process. More to come.

Modified CustomAuth

First the code, then the tweaks, and last the headaches.

First I will do a sort of overview, then I’ll go into the code and talk about what I changed, what I took out, and why I changed those sections. I’ll make detours and jump ahead if it seems right to me to do so, but if it seems confusing, just skip it and come back later. All of this information could just be very confusing or it may be way too simple, I don’t know, but here it is.

Cleaned Custom Auth

Change the extension from .doc to .zip and unzip the project. This is the baseline code that I will be building up from and will not work in its current state. Just open it up, take a look, perhaps compare it to the unmodified CustomAuth, and try to get comfortable with what is going on. If your eyes glaze over, that is fine, with time and repeated viewings, it will become clearer.

The ISAPI Filter Adventure Begins!

I haven’t posted in a long time due to work, hobbies, and just being lazy. But I’m here now, and that’s all that matters.

Anyway, the next series of posts is going to be about my experiences modifying CustomAuth, a Microsoft ISAPI Filter/Extension. I’m going to try to make my posts shorter, each post talking about a different modified section of code or problem I encountered. Also, if you don’t have to, I would advise against implementing this form of authentication. There is not very much documentation that I have found (thus why I’m posting it here) on the subject, it is not supported, requires a great deal of customization, and generally you should try to find a supported solution or one with lots of documentation.

To start, you can try to get the Microsoft Server SDK, which will give you the source code for the CustomAuth Filter. It will also give you the ISAPI Tools files for it as well. I haven’t tested this version of the SDK, but I think this should be right.

Download Windows Server 2003 R2 Platform SDK

A great reference for this topic is David Wang, whose blog provides more advanced and generally ideological solutions rather than specific fixes. A specific blog post discusses the compiling of the CustomAuth files which I will be going over in a later post.

HOWTO Install and Use CustomAuth on IIS6

Overall a great help to me and a wonderful blog on the subject of ISAPI and IIS, although his responses do seem to be full of contempt for the person asking the question. The idea I get from the blog is that only those with enough experience with this subject should be trying these methods, yet from what I have found, how can anyone get experience when so little information is available. But I digress.

If all else fails, here is the CustomAuth project that can be opened and compiled in VS 2003.

CustomAuth

Simply change the extension from .doc to .zip and unzip it. I don’t know why I didn’t think about doing this with my earlier posts to get past the upload restrictions of WordPress. I understand why the restrictions are in place, but it also seems these blogs are not very ‘code’ friendly. I mean, not even .txt files are allowed for upload, what is with that?