IISCosign Config File

From cosign wiki

Current revision

For IISCosign 2.0.0, the config file format was changed to provide more clarity as well as accommodate new options that were not previously available, such as multi-factor authentication.

[edit] 2.0.x config file options

[edit] Example IISCosign config file

All items are required unless otherwise noted and must appear in this order to be compliant with the schema.

<?xml version="1.0"?>
<Cosign xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="iiscosign.xsd">

	<CAFilePath>C:\Program Files\IISCosign\SSL\CA\</CAFilePath>
	<ChainFilePath>C:\Program Files\IISCosign\SSL\server.name.cert</ChainFilePath>
        <PrivateKeyFilePath>C:\Program Files\IISCosign\SSL\server.name.key</PrivateKeyFilePath>

	<Log>
         	<Path>C:\Program Files\IISCosign\Logs</Path>
		<MaxSizeKB>4096</MaxSizeKB>
		<WriteDataToEventViewer>false</WriteDataToEventViewer>
	</Log>
	
	<CookieDB>
		<Path>C:\Program Files\IISCosign\CookieDB</Path>
		<CookieExpireTimeSeconds>60</CookieExpireTimeSeconds>
	</CookieDB>
	
	<LoginServer>
		<DNSName>weblogin.umich.edu</DNSName>
		<LoginURL>https://weblogin.umich.edu/?</LoginURL>
		<LoginPostErrorURL>https://weblogin.umich.edu//cosign/post_error.html</LoginPostErrorURL>
                <Port>6663</Port>		
	</LoginServer>

	<ConnectionPoolSize>8</ConnectionPoolSize>
	
	<HttpsOnly>false</HttpsOnly>
	
	<!-- only needed if using cosignlogout.dll -->
	<!-- LogoutURL>https://weblogin.umich.edu/cgi-bin/logout</LogoutURL -->
	
	<!-- optional, defaults to never -->
	<CheckIPAddress>never</CheckIPAddress>
	
	<!-- optional -->
	<!-- KerberosTicketsPath>c:\krbtkts</KerberosTicketsPath> -->
	
	<Service>
		<Name>cosign-IISCosignDefault</Name>
		<!-- Either Website or IISDescription must be used, but not both -->
		<Website>localhost</Website>
		<!-- IISDescription>Default Web Site</IISDescription -->
		
		<!-- SiteEntry is optional -->
		<SiteEntry>http://localhost/welcome.html</SiteEntry>

		<!-- RequireFactors are optional -->
		<RequireFactor>UMICH.EDU</RequireFactor>
		<RequireFactor>mtoken</RequireFactor>
		<!-- FactorIgnoreSuffixOn is optional.  Default is true -->
		<FactorIgnoreSuffixOn>false</FactorIgnoreSuffixOn>
		<!-- FactorIgnoreSuffix is optional -->		
		<FactorSuffix>-junk</FactorSuffix>

                <Protected>/</Protected>
		<AllowPublicAccess>/webapp1</AllowPublicAccess>
		<Unprotected>/webapp2</Unprotected>
		
	</Service>

</Cosign

[edit] Description of config options

<?xml version="1.0"?>
<Cosign xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="iiscosign.xsd">

This informs that we're working with XML 1.0 and the location of the schema. The iiscosign.xsd should be in the same directory as the config file so IISCosign can find it!

	<CAFilePath>C:\Program Files\IISCosign\SSL\CA\</CAFilePath>

The location of the certificate authority files identifying the weblogin server. These values need to be hashed.

	<ChainFilePath>C:\Program Files\IISCosign\SSL\server.name.cert</ChainFilePath>

The location of the public certificate identifying the server.

        <PrivateKeyFilePath>C:\Program Files\IISCosign\SSL\server.name.key</PrivateKeyFilePath>

The server's private key file location.

	<Log>

Configuration of the IISCosign error logs.

         	<Path>C:\Program Files\IISCosign\Logs</Path>

The directory where IISCosign should place its error logs.

		<MaxSizeKB>4096</MaxSizeKB>

The maximum size the error logs should grow to before creating a new log file.

		<WriteDataToEventViewer>false</WriteDataToEventViewer>
	</Log>

This is intended for troubleshooting purposes. If troubleshooting is not helping, this can optionally be set to "true". IISCosign will then populate Windows Application Log with verbose output of what it is trying to do.

	<CookieDB>

Options for how the cached service cookies are handled.

		<Path>C:\Program Files\IISCosign\CookieDB</Path>

Directory where the service cookies will be cached.

		<CookieExpireTimeSeconds>60</CookieExpireTimeSeconds>
	</CookieDB>

How long a cached service cookie is good before the filter contacts the weblogin server to verify it.

	<LoginServer>

Options for describing the weblogin server.

		<DNSName>weblogin.example.edu</DNSName>

The DNS entry for the weblogin server.

		<LoginURL>https://weblogin.example.edu/?</LoginURL>

Where to redirect web browsers if the user is not logged in.

		<LoginPostErrorURL>https://weblogin.example.edu//cosign/post_error.html</LoginPostErrorURL>

Where to redirect users if they are attempting to POST and are not logged in.

                <Port>6663</Port>
        </LoginServer>

The port number the filter should use to talk to the weblogin server.

	<ConnectionPoolSize>8</ConnectionPoolSize>

The maximum number of connections the filter should have ready to talk to the weblogin server.

	<HttpsOnly>false</HttpsOnly>

When a user attempts to connect to the server, will redirect them to "https" even if they entered "http" in their web browser.

	<LogoutURL>https://weblogin.example.edu/cgi-bin/logout</LogoutURL>

Optional: If you are using the CosignLogout DLL, include this item so CosignLogout knows where to send users upon logging out.

	
	<CheckIPAddress>never</CheckIPAddress>

Optional: Three options are available: intial, always, and never. They are in lower case letters. Default value: never

	<KerberosTicketsPath>c:\krbtkts</KerberosTicketsPath> -->

Optional: This allows the filter to request Kerberos tickets from the weblogin server. The server must be permitted by the weblogin server to retrieve tickets. The value is where the tickets will be stored. To retrieve the ticket location, use the server variable HTTP_KRB5CCNAME.

	<Service>

At least one service must be defined! You can define multiple services on the same server.

		<Name>cosign-IISCosignDefault</Name>

The name of the service. Right now, the ISAPI filter is not super smart and will not add the "cosign-" part automatically.

		<Website>localhost</Website>
		<!-- IISDescription>Default Web Site</IISDescription -->

These options tell IISCosign which web site to protect. You can use either Website or IISDescription, but not both.

If Website is set, IISCosign looks up the SERVER_NAME server variable. 'THIS IS POTENTIALLY INSECURE' If you are using the website value you should also using IIS's 'Advanced Web Site Identification' feature to locally bind the DNS name of your server to an IP address. Otherwise, a user could bypass Cosign-protected pages by simply editing their local system's hosts file!

If IISDescription is set, IISCosign looks up all the server instances present in the metabase. It looks for the ServerComment that matches the IISDescription and saves the ID number associated with that ServerComment. When a user attempts to access the web server, the INSTANCE_ID server variable is compared to the value previously retrieved to determine if it is Cosign-protected.

		<SiteEntry>http://localhost/welcome.html</SiteEntry>

Optional: When a user arrives at any Cosign-protected page for the first time, they are redirected to this "gateway" page.

		<RequireFactor>UMICH.EDU</RequireFactor>
                <RequireFactor>mtoken</RequireFactor>

Optional: Tells IISCosign which authentication factor or factors must be satisfied before the user can access Cosign-protected pages. Each factor must be in a tag by itself.

		<FactorIgnoreSuffixOn>false</FactorIgnoreSuffixOn>
		<FactorSuffix>-junk</FactorSuffix>

Optional: Allows users with a faked authentication factor to have access. See Multi-factor specification for an explanation of this feature. Generally, this should be left to false.

                <Protected>/</Protected>
		<AllowPublicAccess>/webapp1</AllowPublicAccess>
		<Unprotected>/webapp2</Unprotected>

At least one of these must be defined.

Protected requires a user to be authenticated before accessing the specified URL, and any sub-URLs.

AllowPublicAccess means IISCosign will populate the Cosign server variables if the user has already authenticated. That is, if they already have a service cookie from visiting a Protected URL. If no service cookie is present, the user is still allowed to access the page. This can also override Protected and Unprotected tags.

Unprotected is the default behavior for all URLs. Use it here to override previous Protected or AllowPublicAccess tags. In the above example, all URLs require authentication except for URLs starting with "/webapp1" or "/webapp2".

		
	</Service>
</Cosign>

The end of the Service tag. Any number of Service sections can be added to allow multiple services on one web server.

[edit] Pre-2.0.0 config file options

<Cosign>

<CAFilePath>C:\Program Files\IISCosign\SSL\</CAFilePath>

The location of the certificate authority file and its hash. Before IISCosign 1.1.1, this pointed directly to the certificate authority file.

<ChainFilePath>C:\Program Files\IISCosign\SSL\my.server.name.umich.edu.cert</ChainFilePath>

The location of the SSL certificate for your server.

<PrivateKeyFilePath>C:\Program Files\IISCosign\SSL\my.server.name.umich.edu.key</PrivateKeyFilePath>

The location of the private key file for your server.

<LogFilePath fileSizeInKB="4096" >C:\Program Files\IISCosign\Logs</LogFilePath>

The folder where IISCoSign puts its log files and the maximum size of the log files. When the log grows to the size specified, it is closed and a new log file is started.

<CookieDBPath>C:\Program Files\CoSignFilter\CookieDB</CookieDBPath>

The folder where IISCoSign caches service cookies.

<CoSignServer port="6663">weblogin.umich.edu</CoSignServer>

The port and DNS name of the central weblogin server(s). This is where the filter makes 'backside' connections to check the validity of cookies.

<RedirectURL>https://weblogin.umich.edu/?</RedirectURL>

If a user is not logged in this is the URL they are sent to for logging in. You'll notice that the '?' means the user is being redirected to a CGI. The part after the ? is constructed by the filter.

<ConnectionPool size="4" />

The number of backside connections the filter has ready-to-use for doing cookie CHECKs.

<CookieDBExpireTime seconds="60" />

The amount of time a cookie in the server's local cookie cache is considered good. When the cached cookie's last time stamp is greater than this value, the filter talks to the central login server to see if the user is still logged in. If the user is still logged in then the timestamp is updated. If the user is no longer logged in, then the user is redirected to the login page.

<WriteDataToEventViewer>FALSE</WriteDataToEventViewer>

Probably best left to FALSE. If you are having trouble running the IISCoSign filter you can set this to TRUE to send logging information to the Windows Event Viewer. This is recommended only as a last resort since IISCoSign is quite verbose and will fill up your logs quickly. You can also open a debug viewer such as dbmon.exe or DebugView to see what IISCoSign is up to.

<CheckIPAddr>FALSE</CheckIPAddr>

By setting this to TRUE IISCoSign will check that a service cookie is from the same IP address each time. Setting this to FALSE allows IISCoSign to work with hardware load balancers.

<Service website="my.server.name.umich.edu">CoSign-YOUR_SERVICE_NAME_HERE
 <Protected>/secure</Protected>
 <Protected allowPublicAccess="TRUE">/test1</Protected>
 <Protected>/test2</Protected>
 <Protected>/protected_page.html</Protected>
</Service>

</Cosign>

You can have multiple web sites with different services or multiple web sites with one service. Just add more <service> tags. To make a resource CoSign protected, create as many <Protected> tags under the <Service> tag as you'd like. By default, protecting something like /test1 will also protect all URLs and pages underneath /test1 -- such as /test1/script.asp, /test1/images/pic1.jpg, and /test1/more/info/.

Currently, the website="" relies on the SERVER_NAME variable to determine if a web site is protected. THIS IS INSECURE WITH THE DEFAULT IIS SETTINGS. If you are using the website value you should also using IIS's 'Advanced Web Site Identification' feature to locally bind the DNS name of your server to an IP address. An alternative to using website="" is to use IISDescription. For example:

<Service IISDescription="Default Web Site">CoSign-YOUR_SERVICE_NAME_HERE
...
</Service>

This setting relies on the name of the web site used by IIS and uses the INSTANCE_ID server variable to lookup the web site name in the metabase. Be sure the value for IISDescription is exactly the same, including spaces, as it appears in the metabase.

The allowPublicAccess option can be set to TRUE or FALSE. By default, the value is FALSE. By setting this to TRUE a web page or URL can be viewed by anybody. However, if a user has already logged in AND visited a protected page then the CoSign variables HTTP_REMOTE_USER and HTTP_REMOTE_REALM will be added by the filter. The idea is that web applications can check for these variables, and, if present, can customize a page for a user if he's logged in or showing a generic page if he is not. The value HTTP_CoSign_SERVICE variable is always populated whether a user has authenticated or not (and is visiting a protected URL).