Child pages
  • SPWindowsInstall

The Shibboleth 1.x software has reached its End of Life and is no longer supported. This documentation is available for historical purposes only.

Skip to end of metadata
Go to start of metadata

Use of provided installers is recommended for Windows deployments, although it is theoretically possible to build it yourself. This program will install all Shibboleth components necessary on either Apache 1.3.x, Apache 2, or IIS 6. Prerequisites listed below must be independently installed regardless of deployment method.

The following software requirements listed correspond to the distributed installers. In general, source builds should work against all recent versions of the software dependencies listed below. For specific questions, inquire or search the support mailing list, or give it a try. OpenSSL releases frequent security updates; the version listed may not be the most current, but most minor "letter" updates should be usable.

1. Prepare the Environment

  • Any Apache modules used, and Apache itself, must be compiled with the Microsoft DLL-based runtime, selected by compiling with the /MD switch. The binary distribution was built against Apache versions 1.3.33 (with EAPI patches from mod_ssl 2.8.16) and 2.0.52. Forward compatibility is likely, but errors will result if an Apache implementation such as IBM's IHS product or any other non-EAPI version of 1.3 is used. In such cases, you must build the Shibboleth Apache modules from source.
  • Debug versions of the libraries and software are included, and may be used by appending "debug" to the Shibboleth library path and using the corresponding modules and binaries. If you do so, be aware that Apache and other modules must also be compiled with Microsoft's debug runtime (via the /MDd compiler option). In most cases, you can safely ignore or even delete the debug versions.
  • Apache 2.0.x: Apache 2.0.x must be compiled with mod_so for DSO module support, and should include SSL support which is available but not included by default.
  • OpenSSL: Versions 0.9.6 and 0.9.7 are both supported, but 0.9.7 should be used if possible, as support for 0.9.6 may be dropped in a future release. Support for threads and shared libraries must be included during configuration using the threads and shared options.

2a. Install Shibboleth for Apache:

This configuration information is for Windows installations that use Apache. IIS is described below.

  1. Download the Shibboleth SP installer.
  2. Run the installer. The installer will prompt for an install path (you cannot have spaces in this path, e.g. "\Program Files\"), change default configuration files as appropriate for Windows, and set various environment variables for you. A default shibd service can also be installed, or you can install it manually using the instructions in this guide.
  3. Edit httpd.conf :
    • Shibboleth bundles configuration directives in the files /opt/shibboleth/etc/shibboleth/apache.config , /opt/shibboleth/etc/shibboleth/apache2.config , and /opt/shibboleth/etc/shibboleth/apache22.config which must be Included in httpd.conf . Select and use only the one that matches your version of Apache, e.g. apache22.config for Apache 2.2.x. Be wary of placing the configuration in the wrong VirtualHost .
    • The UseCanonicalName directive should be set to On . On some Apache builds including the RedHat distribution, this defaults to Off which will cause problems in resource mapping.
    • Ensure that the ServerName directive is properly set, and that Apache is being started with SSL enabled.
  4. By default, the Shibboleth module is configured to log information on behalf of Apache to /var/log/httpd/native.log , though this can be changed by modifying the .logger files pointed to by the configuration. For this log to be created, Apache must have permission to write to this file, which may require that the file be manually created and permissions assigned to whatever user Apache is configured to run under. If the file does not appear when Apache runs with the modules loaded, check for permission problems or change the location used.
  5. shibd creates its own separate logs at /var/log/shibboleth/shibd.log and must have appropriate write permissions itself.

2b. Install Shibboleth for IIS:

This configuration information is for Windows installations that use IIS 6.0. Apache is described above. Windows 2000 Server and IIS 5 information is also available.

The Shibboleth SP installer will install an ISAPI filter and sign sign-on (sso) extension within the global configuration of your IIS server. This configuration section is accessible through the IIS manager tool by opening the properties pane of the "Web Sites" folder (select the folder and choose "Action -> Properties"). The filter's configuration file will be located in the etc\shibboleth\shibboleth.xml directory (within the directory you install the SP software).

  1. Download the Shibboleth SP installer.
  2. Run the installer. The installer will prompt for an install path (you cannot have spaces in this path, e.g. "\Program Files\"), change default configuration files as appropriate for Windows, and set various environment variables for you. A default shibd service can also be installed, or you can install it manually using the instructions in this guide.
  3. Restart IIS.
  4. shibd creates its own separate logs at var\log\shibboleth (e.g. C:\opt\shibboleth-sp\var\log\shibboleth if you accept the default install location) and must have appropriate write permissions itself.

In order to configure Shibboleth you'll need the site identifier that IIS has assigned to your website. If you're simply using the default website this identifier is 1 (one). If you're not you can find the identifier through the IIS Manager tool by selecting the "Web Sites" folder and looking in the identifier column, on the right, that corresponds to your website.

3. Run shibd :

shibd is a console application that is installed as a Windows service. To run the process in console mode for testing or to diagnose major problems, supply a -console parameter when running it. If shibd won't start, use the -check option from the command line to echo most logging information to the console for debugging. Otherwise, parameters are used to install (or remove) shibd from the service database and subsequent control is via the Service Control Manager applet. The following command line parameters can be used:

-console

Allows the process to be started from a command prompt. Since the console will exit if the desktop user logs out, this is not suitable for production use, but may be useful for testing.

-check

Validates the general correctness of the configuration. Not all problems can be detected this way, but the chance of successful startup is high if the checking process does not log any errors.

-config <pathname>

Specifies the pathname of shibd's configuration file. Defaults to \opt\shibboleth\etc\shibboleth\shibboleth.xml or the value of the SHIBCONFIG environment variable, if it is set.

-schemadir <path>

Specifies the path to the XML schema files. Defaults to \opt\shibboleth\share\xml\shibboleth or the value of the SHIBSCHEMAS environment variable, if it is set.

-install <servicename>

Installs shibd as a named service in the Windows service database. A name should be provided if multiple instances of shibd need to be run on different ports, and thus installed separately. The -config option can be provided to include a specific configuration file on the service's command line.

-remove <servicename>

Removes the named service instance of shibd from the Windows service database.

Newer versions of Windows support automatic restart of failed services. We suggest using this feature to restart shibd when it fails. Although stability is good, maximum reliability will be achieved by monitoring the process. To confirm the install worked properly you can go to control panel > administration tools > services and make sure that the shibd service shows up. You can set it to automatic if necessary using the GUI.

At this point, you should have a fully functional SP, but before it can be tested, you'll need to configure it to interoperate with an !IdP. Many federations will provide these for their community, and TestShib is available for anyone to test with.

  • No labels