CAS ISAPI Client
NOTE: UC Davis no longer maintains the ISAPI CAS client. ISAPI is deprecated by Microsoft. Use at your own risk.
CASAuthN ISAPI Client
Release Notes
- Version 2.2 - Nov 25, 2013
- Chrome interoperability issue fixed.
- Version 2.1 - Aug 19, 2010
- A security vulnerability with the authentication header was fixed.
- Version 2.0 - Feb 09, 2010
- Two new versions of the CAS ISAPI module have been released. Windows Server 2008 can run in 64-bit mode, which requires a specially-compiled binary. For users of Windows Server 2008 32-bit instances and earlier operating systems, please use the 32-bit installer.
- This release also fixes the issue with secondary cookies causing CAS authentications to fail.
- MsMXL 6.0 or newer must be installed. MsXML 6.0 can be downloaded from: http://www.microsoft.com/Downloads/details.aspx?familyid=993C0BCF-3BCF-4009-BE21-27E85E1857B1&displaylang=en
- These modules may only be used with CAS servers running commercial certificates.
Overview
Windows Internet Information (IIS) server is used to deliver web sites and applications for numerous departments. While the newest versions of IIS suppport .NET technology for which there is a well-supported CAS authentication module, older applications rely on ISAPI, the Information Server Application Programming Interface. Unfortunately, there is little or no support for an ISAPI CAS module. In order to support our IIS clients, we have created an ISAPI client module.
Alternatives
Ja-Sig provides links to several ISAPI modules developed by other organizations. If you encounter problems with the UC Davis ISAPI module, you can try the modules listed at http://www.ja-sig.org/wiki/display/CASC/ISAPI+Filter.
Download
Installation Instructions
Please follow these instructions to install and configure the CAS ISAPI Filter for IIS Web Sites and ASP applications.
Download and Install MsXML 6.0 (If Necessary)
- Download the appropriate version of MsXML 6.0 for your architecture from http://www.microsoft.com/Downloads/details.aspx?familyid=993C0BCF-3BCF-4009-BE21-27E85E1857B1&displaylang=en
- Run the installer
Download and Install the CAS ISAPI Filter
- Download the CAS ISAPI Installer from https://confluence.ucdavis.edu:8443/confluence/x/eFY
- Run the installer.
The installer now starts with valid default values for all required settings that will result in your entire site being protected by the UC Davis production CAS server. If you wish to customize the settings this table will provide you with information on their function:Parameter
Description
Default
CAS Server URL
The base URL of the CAS server
https://cas.ucdavis.edu/cas
Session Timeout
The time in minutes each local session should last before requiring a roundtrip to the CAS server to confirm authenticated status.
4 hours (240 minutes)
Cache Clean Timeout
The time to wait between cleanings of the authentication cache. If you experience out of memory errors, decrease this.
1 hour (60 minutes)
URL(s)
Strings to match against requested URLS. When matched, CAS authentication is enforced.
/ (Matches all URLs)
CAS Login Path
The path to the login URL on the CAS server
login
CAS Validation Path
The path to the validation URL on the CAS server
serviceValidate
Service URL
When set, users will be directed back to this URL during the initial authentication step.
not set
Authentication Header
The request header that receives the authenticated user ID.
CASUser
Deploy the CAS Filter to your Web Site
Windows Server 2008 |
Windows Server 2003 and earlier |
---|---|
|
|
Done!
That's it! Test your new protection scheme by using a Web browser to try and access a URL on your Web server with one of the protected path settings you set in this installer. It should redirect you to your CAS authentication server. You can also verify that the dll was loaded correctly by following steps a-f above and checking the status of the recently entered filter. It should have a green arrow to the left pointing up. If not, the filter is failing on initializationt. Check the registry keys and all relevant files listed therein as well as the location of the dll. Please also consult the troubleshooting section for information on common errors.
Accessing the authenticated user id
The CAS ISAPI module sets the "CASUser" header by default, this can be overridden during the installation process. In any server-side processing script (ASP, ASP.NET, .NET, Cold Fusion) you will be able to access this variable to get the authenticated user id.
Do not use "remote_user" as the header value, Windows asserts complete control over this header and any settings by the ISAPI module will be discarded by Windows.
Editing the Configuration
The CAS client configuration can be edited after installation via a registry editor like regedit. To access the CAS ISAPI module settings, browse to: /HKEY_LOCAL_MACHINE/SOFTWARE/CASAuthN It is possible to set up more than four path matching expressions using this method. The ISAPI module can handle up to ten (10) path expressions.
Registry settings are loaded at module initialization. Therefore, you must restart IIS after editing the configuration via a registry editor in order for the module to register the changes.
Classlist / User File Configuration
The Distauth ISAPI client never supported the Classlist feature. However, the College of Letters and Science has provided an ODBC filter which can authorize users against a database. Please go to ODBCFilter for more information.
Passthrough / Gateway Configuration
The CAS ISAPI Module does not currently provide support for Gateway mode.
IP Restriction Configuration
IP Restriction can be configured via the IIS Administrator console:
- Open the IIS Adminsitrator Console
- Select your Web Site
- Right Click and Select Properties
- When the Properties Window Opens, select the Security Tab.
- Click Edit in the IP address and domain restrictions section
- Add the UC Davis IP ranges:
- 169.237.
- 128.120.
- 152.79.
- IP restrictions are now in effect.
Troubleshooting
The ISAPI module logs to the Windows Application Event log. Entries can be viewed using the Event View administration tool. The CAS log entries can be identified by a Source value of "CASAuthN". In its default configuration CAS will write entries on service start, stop, error conditions and cache cleanings.
The new module also comes with a debugging mode. To enable debugging, edit the /HKEY_LOCAL_MACHINE/SOFTWARE/CASAuthN/Debug registry key, setting the value to 1. After an IIS restart, you will see a marked increase in event log entries.
If the filter is not working correctly, you may want to check these items:
- Red Arrow in IIS Administrator
- Access Permissions: Make sure the IIS group (whatever group the IWAM_MACHINENAME user belongs to) has read access to its location.
- Registry Keys: The CAS ISAPI module stores its configuration in the system registry during install. Check that the following keys exist and are populated:
- /HKEY_LOCAL_MACHINE/SOFTWARE/CASAuthN
- /HKEY_LOCAL_MACHINE/SYSTEM/CurrentControlSet/Services/EventLog/Application/CASAuthN
- Isolation Mode: Try turning on IIS 5.0 Isolation mode. In the IIS Adminsistrator, Right Click on the 'Web Sites' folder and choose 'Properties'. In the properties window, select the 'Service' tab, and make sure the Checkbox labeled 'Run WWW service in IIS 5.0 Isolation mode' is checked. Then restart IIS.
- It's not redirecting
- Make sure the filter is loading. Under the Internet Information Services panel, look for the filter where you applied it earlier, and make sure there is a green arrow up next to it. Make sure the IIS group (whatever group the IWAM_MACHINENAME user belongs to) has read access to its location.
- Redirection Limit Exceeded Error
- Ensure that your links and/or users are accessing protected resources via a url with your site's domain name and not IP address. The ISAPI plugin requires that users access the protected website via its configured domain name. Additionally, domain names must be inside the ucdavis.edu domain.
- Unable to create an XML Document Instance
- If the CAS module is not working, and you see messages in the Application Log that reference "unable to create an XML Document Instance", try installing MSXML 4 Service Pack 2 or higher. This has been reported in some Windows Server 2008 installations.
- The CASAuthN Authentication filter was unable to validate the authentication cookie
This version of the ISAPI module cannot make https connections to cas servers that run with self-signed certificates. When using the UC Davis CAS service, always make sure the ServerURL parameter is set to https://cas.ucdavis.edu/cas - Other Problems
- Please contact websso@ucdavis.edu if you need additional assistance.