Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 6 Next »

CASAuthN ISAPI Client

In this Section

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.

Download

Click here to download the CAS ISAPI Client Installer

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)

  1. 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
  2. Run the installer

Download and Install the CAS ISAPI Filter

  1. Download the CAS ISAPI Installer from https://confluence.ucdavis.edu:8443/confluence/x/eFY
  2. 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
  1. Start the Internet Information Services (IIS) Manager
  2. Click on your server and select "Stop" from the Actions.
  3. Click on your Web server instance in your Console. The default title of your Web server instance is "Default Web Site", unless you changed it.
  4. Select ISAPI Filters from the Features View.
  5. Select "Add..." from the Actions list and enter "CASAuthN" as the "Filter Name".
  6. Browse to the CASAuthN.dll.
    • Windows Server 2008 64-bit: It is installed with this path: "C:\WINDOWS\sysWOW64\inetsrv\CASAuthN.dll".
    • Windows Server 2008 32-bit: It is installed with this path: "C:\WINDOWS\system32\inetsrv\CASAuthN.dll".
  7. Click "Ok".
  8. Restart the IIS Web Service.
    1. Click on the Web server instance.
    2. Select "Restart" from the Manage Server Actions section.
  1. The Web Server and IIS Admin service must be stopped. Check the services dialog box and stop these services if they are running.
  2. Start the IIS Administrator Console
  3. Click on your Web server instance in your Console. The default title of your Web server instance is "Default Web Site", unless you changed it. It maybe hidden under "Console Root/Internet Information Server/NAME", where "NAME" is the name of your computer.
  4. Access the properties page via right click.
  5. Click on the "ISAPI Filters" tab.
  6. Click on "Add..." and enter "CASAuthN" as the "Filter Name".
  7. Browse to the CASAuthN.dll. It is installed with this path: "C:\WINDOWS\system32\inetsrv\CASAuthN.dll".
  8. Click "Ok" on all dialogs until you are back at the IIS Administrator.
  9. Restart the IIS Web Service.
    1. Right click on the local computer in the IIS Adminstrator.
    2. Select All Tasks->Restart IIS.

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.

Troubleshooting

If the filter is not working correctly, you may want to check these items.

  • Red Arrow in IIS Administrator
    • Make sure the IIS group (whatever group the IWAM_MACHINENAME user belongs to) has read access to its location.
    • 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.
  • Other Problems
    • Please contact distauth@ucdavis.edu if you need additional assistance.
  • No labels