Knowledge Base

How to dynamically choose authentication scheme using ISAPI filter in IIS

Article ID: 254787

Article Last Modified on 1/9/2007

APPLIES TO

Microsoft Internet Information Services 5.1
Microsoft Internet Information Services 5.0
Microsoft Internet Information Server 4.0

This article was previously published under Q254787

SUMMARY

This step-by-step article describes how to write an Internet Server API (ISAPI) filter that permits you to specify the authentication method for a user based on the user Internet Protocol (IP) address.

For example, in Internet Information Server (IIS), you can use the Windows NT Challenge/Response authentication for clients who come from an internal corporate network and, at the same time, allow clients from the Internet to be authenticated through Basic authentication.

Note This article assumes that you are familiar with the following topics:

How to write an ISAPI filter.
How to code in Microsoft C and Microsoft C++ programming languages.

Authentication schemes

This article describes the authentication method in the context of IIS, which supports Windows NT Challenge/Response (NTLM) and Basic authentication. IIS 5.0 and 5.1 also allow Digest authentication and then replaces Windows NT Challenge/Response authentication with Integrated Windows authentication. The corresponding HTTP WWW-Authenticate header authentication schemes follow.

Authentication	Scheme
Basic	Basic
Windows NT Challenge/Response	NTLM
Digest	Digest
Integrated Windows	Negotiate, NTLM

Write an ISAPI filter

To write an ISAPI filter that permits you to specify the authentication method for a user based on the user IP address, perform the following steps:

In IIS turn on both Basic and NTLM authentication on the server.
Build an ISAPI filter to register the SF_NOTIFY_PREPROC_HEADERS event and the SF_NOTIFY_SEND_RESPONSE notifications.
1. On the SF_NOTIFY_PREPROC_HEADERS notification, the filter uses the GetServerVariable function to retrieve the value of REMOTE_ADDR or REMOTE_HOST and then determines whether the user IP address is on the internal network based on the value of the server variable. The filter just sets "pfc->pFilterContext = (LPVOID)fInternalUser" to communicate the information to the send response notification handler.
2. On the SF_NOTIFY_SEND_RESPONSE notification, the filter uses the pfc->pFilterContext value to determine which WWW-Authenticate headers it must remove with the SetHeaders method if the status code is 401. Make sure that you only do this for 401 responses with code that is similar to:
```
if ((HTTP_FILTER_PREPROC_HEADERS *)pvNotification->HttpStatus != 401)
     return SF_STATUS_REQ_NEXT_NOTIFICATION;
                        
```
After you determine that this is a 401 response, you can work with the WWW-Authenticate header as illustrated in the following code segment:
```
if (pfc->pFilterContext)
     RemoveBasic; 
else
     RemoveNTLM; 
                    
```

Note You must turn on the specified authentication scheme on the server as stated at the beginning of the article. For example, if you merely add the "WWW-Authenticate: NTLM" header does not cause an NTLM authentication handshake if you do not turn on Windows NT Challenge/Response authentication.

Note You cannot specifically remove or change built-in IIS authentication protocols on the SF_NOTIFY_ACCESS_DENIED event. As a result, you cannot dynamically select the authentication scheme with an access denied notification handler.

REFERENCES

For more information on ISAPI filter DLLs, click the following article numbers to view the articles in the Microsoft Knowledge Base:

150312 How to install an ISAPI filter dynamic-link library

183480 How to debug ISAPI DLLs in IIS 4.0, IIS 5.0, IIS 5.1, and IIS 6.0

For more information about how to develop ISAPI extensions and filters, visit the following Microsoft Developer Network (MSDN) Web site:

http://msdn2.microsoft.com/en-us/library/ms525321.aspx

Keywords: kbfilter kbhowto kbhowtomaster KB254787

Microsoft KB Archive/254787

Contents