URL: http://www.switch.ch/aai/docs/shibboleth/SWITCH/1.3/sp/install-sp-1.3-win2003.html Author: Patrik Schnellmann, SWITCH $Date: 2007/12/19 14:20:22 $ $Revision: 1.20 $ Thanks go to Yan Corneille, University of Zurich, for his substantial contribution.
This guide describes Windows 2003 server specific installation of a Shibboleth Service Provider 1.3 and its configuration for the SWITCHaai Federation. It covers the installation on Windows 2003 Server with IIS 6.0.
More information can be found on the Shibboleth Wiki from Internet2. It is recommended to familiarize yourself with the Internet2 guide before starting with this document.
Note: If you want to join the AAI-Test Federation instead of the productive SWITCHaai Federation, please consult the AAI-Test Reconfiguration guide after following the instructions on this page.
The Shibboleth Service Provider (SP) 1.3 is implemented in VC++ as an ISAPI Filter ISAPI_Shib
and a separate service shibd.
The example values used in this guide are:
As indicated in the title, this guide applies to Windows 2003. Configuration for Windows 2000 server platforms are basically the same: some parts are not necessary, like Server Extension settings.
First of all, download and install the latest Shibboleth package from Internet2: http://shibboleth.internet2.edu/downloads/win32/.
By default, the Shibboleth SP 1.3 will be installed under: C:\opt\shibboleth-sp\. This directory will be used
as shibboleth root in the following document. If you decide to change it, please adapt the procedure to your specific configuration.
The Shibboleth Service Provider (Shibboleth Daemon, Apache module, libraries, ... )
is now fully installed under C:\opt\shibboleth-sp\.
Post-installation updates are only necessary when updating an existing
installation. To update, e.g. Shibboleth 1.3 to 1.3.1, use the post-install
archive: http://shibboleth.internet2.edu/downloads/win32/
Services (IIS and Shibboleth) will have to be stopped before the update and
started afterwards. The process is described on the
Shibboleth Wiki.
This section briefly mentions the needed steps to get a server certificate. For a full documentation how to get SWITCHpki certificates, see http://www.switch.ch/pki/manage.html
C:\opt\shibboleth-sp\bin\openssl genrsa -out sp.example.ch.key 2048
C:\opt\shibboleth-sp\bin\openssl req -new -key sp.example.ch.key -out sp.example.ch.csr
sp.example.ch.crt.
Copy the private key and certificate to the C:/opt/shibboleth-sp/etc/shibboleth/ directory:
Make sure the permissions are set correctly.
IUSR_<machine name> must be able to read the private key.
Other users don't need to access the key file, so setting the correct ownership and
access permissions is highly recommended.
Get the shibboleth.windows.xml file, rename and store it
as C:\opt\shibboleth-sp\etc\shibboleth\shibboleth.xml . This is the main configuration file
for the Service Provider and is already preconfigured for the SWITCHaai federation.
Edit the C:\opt\shibboleth-sp\etc\shibboleth\shibboleth.xml file and configure your SP 1.3:
providerId: This URN is the unique identifier of your resource
within the federation. It's value should be 'stable'. It should not change,
even when you have to move your resource from one host to another one. So
choosing a 'service name' is preferred over a host name.https://<HOSTNAME>/shibboleth<SPConfig xmlns="urn:mace:shibboleth:target:config:1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="urn:mace:shibboleth:target:config:1.0 C:/opt/shibboleth-sp/share/xml/shibboleth/shibboleth-targetconfig-1.0.xsd" logger="C:/opt/shibboleth-sp/etc/shibboleth/shibboleth.logger" clockSkew="180"> <!-- These extensions are "universal", loaded by all Shibboleth-aware processes. --> <Extensions> <Library path="C:/opt/shibboleth-sp/libexec/xmlproviders.so" fatal="true"/> </Extensions> <!-- The Global section pertains to shared Shibboleth processes like the shibd daemon. --> <Global logger="C:/opt/shibboleth-sp/etc/shibboleth/shibd.logger"> <!-- <Extensions> <Library path="C:/opt/shibboleth-sp/libexec/shib-mysql-ccache.so" fatal="false"/> </Extensions> --> <!-- Only one listener can be defined. --> <!-- <UnixListener address="@-VARRUNDIR-@/shib-shar.sock"/> --> <TCPListener address="127.0.0.1" port="1600" acl="127.0.0.1"/> <!-- See deploy guide for details, but: cacheTimeout - how long before expired sessions are purged from the cache AATimeout - how long to wait for an AA to respond AAConnectTimeout - how long to wait while connecting to an AA defaultLifetime - if attributes come back without guidance, how long should they last? strictValidity - if we have expired attrs, and can't get new ones, keep using them? propagateErrors - suppress errors while getting attrs or let user see them? retryInterval - if propagateErrors is false and query fails, how long to wait before trying again Only one session cache can be defined. --> <MemorySessionCache cleanupInterval="300" cacheTimeout="3600" AATimeout="30" AAConnectTimeout="15" defaultLifetime="1800" retryInterval="300" strictValidity="false" propagateErrors="false"/> <!-- <MySQLSessionCache cleanupInterval="300" cacheTimeout="3600" AATimeout="30" AAConnectTimeout="15" defaultLifetime="1800" retryInterval="300" strictValidity="false" propagateErrors="false" mysqlTimeout="14400" storeAttributes="false"> <Argument>--language=C:/opt/shibboleth-sp/share/english</Argument> <Argument>--datadir=C:/opt/shibboleth-sp/data</Argument> </MySQLSessionCache> --> <!-- Default replay cache is in-memory. --> <!-- <MySQLReplayCache> <Argument>--language=C:/opt/shibboleth-sp/share/english</Argument> <Argument>--datadir=C:/opt/shibboleth-sp/data</Argument> </MySQLReplayCache> --> </Global> <!-- The Local section pertains to resource-serving processes (often process pools) like web servers. --> <Local logger="C:/opt/shibboleth-sp/etc/shibboleth/native.logger" localRelayState="true"> <!-- To customize behavior, map hostnames and path components to applicationId and other settings. The following provider types are available with the delivered code: type="edu.internet2.middleware.shibboleth.sp.provider.NativeRequestMapProvider" - Web-server-specific plugin that allows native commands (like Apache's ShibRequireSession) to override or supplement the XML syntax. The Apache version also supplies an htaccess authz plugin for all content. type="edu.internet2.middleware.shibboleth.sp.provider.XMLRequestMapProvider" - portable plugin that does not support the older Apache-specific commands and works the same on all web platforms, this plugin does NOT support htaccess files for authz unless you also place an <htaccess/> element somewhere in the map By default, the "native" plugin (the first one above) is used, since it matches older behavior on both Apache and IIS. --> <RequestMapProvider type="edu.internet2.middleware.shibboleth.sp.provider.NativeRequestMapProvider"> <RequestMap applicationId="default"> <!-- This requires a session for documents in /secure on the containing host with http and https on the default ports. Note that the name and port in the <Host> elements MUST match Apache's ServerName and Port directives or the IIS Site name in the <ISAPI> element below. --> <Host name="sp.example.ch"> <Path name="secure" authType="shibboleth" requireSession="true" exportAssertion="true"> <!-- Example shows the folder "/secure/admin" assigned to a separate <Application> --> <!-- <Path name="admin" applicationId="foo-admin"/> --> </Path> </Host> </RequestMap> </RequestMapProvider> <Implementation> <ISAPI normalizeRequest="true"> <!-- Maps IIS Instance ID values to the host scheme/name/port/sslport. The name is required so that the proper <Host> in the request map above is found without having to cover every possible DNS/IP combination the user might enter. The port and scheme can usually be omitted, so the HTTP request's port and scheme will be used. <Alias> elements can specify alternate permissible client-specified server names. If a client request uses such a name, normalized redirects will use it, but the request map processing is still based on the default name attribute for the site. This reduces duplicate data entry in the request map for every legal hostname a site might permit. In the example below, only sp.example.ch needs a <Host> element in the map, but spalias.example.ch could be used by a client and those requests will map to sp.example.ch for configuration settings. --> <Site id="1" name="sp.example.ch"> <!-- <Alias>spalias.example.ch</Alias> --> </Site> </ISAPI> </Implementation> </Local> <!-- The Applications section is where most of Shibboleth's SAML bits are defined. resource requests are mapped in the Local section into an applicationId that points into this section. --> <Applications id="default" providerId="https://sp.example.ch/shibboleth" homeURL="https://sp.example.ch/index.html" xmlns:saml="urn:oasis:names:tc:SAML:1.0:assertion" xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"> <!-- Controls session lifetimes, address checks, cookie handling, and the protocol handlers. You MUST supply an effectively unique handlerURL value for each of your applications. The value can be a relative path, a URL with no hostname (https:///path) or a full URL. The system can compute a relative value based on the virtual host. Using handlerSSL="true" will force the protocol to be https. You should also add a cookieProps setting of "; path=/; secure" in that case. Note that if the value of checkAddress is set to "false", this has a slightly negative impact on the security of the SP. This security feature checks the user's IP address at the SP and compares it with the IP address used at the IdP. If they don't match, an error is thrown. This rather strict security feature can cause problems for users behind proxies or for users with IPv6 addresses. Therefore, this setting is deactivated per default. To compensate the slightly reduced security the consistentAddress feature is activated in the default configuration. The consistentAddress feature is available as of version 1.3c for theelement. It defaults to true when not present and ensures that once a session cookie is issued to a client, any further use of that session cookie must be from a client with the same network address. This raises the bar for session hijackers to the level of network address spoofing, which may or may not be simple to do, but is definitely harder than stealing cookies and relies on a different set of attacking skills. On the other hand the consistentAddress may also cause problems for users whose IP changes during the session (e.g. for AOL users or for users behind proxies which have multiple IP addresses). For additional information about the checkAddress and the consistentAddress setting have a look at https://spaces.internet2.edu/display/SHIB/AddressChecking --> <Sessions lifetime="7200" timeout="3600" checkAddress="false" consistentAddress="true" handlerURL="/Shibboleth.sso" handlerSSL="false" idpHistory="true" idpHistoryDays="7"> <!-- SessionInitiators handle session requests and relay them to a WAYF or directly to an IdP, if possible. Automatic session setup will use the default or first element (or requireSessionWith can specify a specific id to use). Lazy sessions can be started with any initiator by redirecting to it. The only Binding supported is the "urn:mace:shibboleth:sp:1.3:SessionInit" lazy session profile using query string parameters: * target the resource to direct back to later (or homeURL will be used) * acsIndex optional index of an ACS to use on the way back in * providerId optional direct invocation of a specific IdP --> <!-- This example directs users to a specific IdP's SSO service. --> <!-- <SessionInitiator isDefault="true" id="example" Location="/WAYF/idp.example.ch" Binding="urn:mace:shibboleth:sp:1.3:SessionInit" wayfURL="https://idp.example.ch/shibboleth-idp/SSO" wayfBinding="urn:mace:shibboleth:1.0:profiles:AuthnRequest"/> --> <!-- This default directs users to the SWITCHaai Production federation's WAYF service. --> <SessionInitiator id="SWITCHaai" Location="/WAYF/SWITCHaai" Binding="urn:mace:shibboleth:sp:1.3:SessionInit" wayfURL="https://wayf.switch.ch/SWITCHaai/WAYF" wayfBinding="urn:mace:shibboleth:1.0:profiles:AuthnRequest"/> <!-- md:AssertionConsumerService elements replace the old shireURL function with an explicit handler for particular profiles, such as SAML 1.1 POST or Artifact. The isDefault and index attributes are used when sessions are initiated to determine how to tell the IdP where and how to return the response. --> <md:AssertionConsumerService Location="/SAML/POST" isDefault="true" index="1" Binding="urn:oasis:names:tc:SAML:1.0:profiles:browser-post"/> <md:AssertionConsumerService Location="/SAML/Artifact" index="2" Binding="urn:oasis:names:tc:SAML:1.0:profiles:artifact-01"/> <!-- md:SingleLogoutService elements are mostly a placeholder for 2.0, but a simple cookie-clearing option with a ResponseLocation or a return URL parameter is supported via the "urn:mace:shibboleth:sp:1.3:Logout" Binding value. --> <md:SingleLogoutService Location="/Logout" Binding="urn:mace:shibboleth:sp:1.3:Logout"/> </Sessions> <!-- You should customize these pages! You can add attributes with values that can be plugged into your templates. You can remove the access attribute to cause the module to return a standard 403 Forbidden error code if authorization fails, and then customize that condition using your web server. --> <Errors session="C:/opt/shibboleth-sp/etc/shibboleth/sessionError.html" metadata="C:/opt/shibboleth-sp/etc/shibboleth/metadataError.html" rm="C:/opt/shibboleth-sp/etc/shibboleth/rmError.html" access="C:/opt/shibboleth-sp/etc/shibboleth/accessError.html" supportContact="YOUR_EMAIL_ADDRESS" logoLocation="YOUR_LOGO_LOCATION" styleSheet="YOUR_STYLESHEET_LOCATION"/> <!-- Indicates what credentials to use when communicating --> <CredentialUse TLS="switchaai" Signing="switchaai"> <!-- RelyingParty elements can customize credentials for specific IdPs/sets. --> <!-- <RelyingParty Name="urn:mace:switch.ch:aaitest" TLS="aaitest" Signing="aaitest"/> --> </CredentialUse> <!-- Use designators to request specific attributes or none to ask for all --> <!-- <saml:AttributeDesignator AttributeName="urn:mace:dir:attribute-def:eduPersonScopedAffiliation" AttributeNamespace="urn:mace:shibboleth:1.0:attributeNamespace:uri"/> --> <!-- AAP can be inline or in a separate file --> <AAPProvider type="edu.internet2.middleware.shibboleth.aap.provider.XMLAAP" uri="C:/opt/shibboleth-sp/etc/shibboleth/AAP.switchaai.xml"/> <!-- Operational config consists of metadata and trust providers. Can be external or inline. --> <!-- SWITCHaai Production federation metadata --> <MetadataProvider type="edu.internet2.middleware.shibboleth.metadata.provider.XMLMetadata" uri="C:/opt/shibboleth-sp/etc/shibboleth/metadata.switchaai.xml"/> <!-- The standard trust provider supports SAMLv2 metadata with path validation extensions. --> <TrustProvider type="edu.internet2.middleware.shibboleth.common.provider.ShibbolethTrust"/> <!-- Zero or more SAML Audience condition matches (mainly for Shib 1.1 compatibility). If you get "policy mismatch errors, you probably need to supply metadata about your SP to the IdP if it's running 1.2. Adding an element here is only a partial fix. --> <saml:Audience>urn:mace:switch.ch:SWITCHaai</saml:Audience> <!-- You can customize behavior of specific applications here. The default elements inside the outer <Applications> element generally have to be overridden in an all or nothing fashion. That is, if you supply a <Sessions> or <Errors> override, you MUST include all attributes you want to apply, as they will not be inherited. Similarly, if you specify an element such as <MetadataProvider>, it is not additive with the defaults, but replaces them. Note that each application must have a handlerURL that maps uniquely to it and no other application in the <RequestMap>. Otherwise no sessions will reach the application. If each application lives on its own vhost, then a single handler at "/Shibboleth.sso" is sufficient, since the hostname will distinguish the application. The example below shows a special application that requires use of SSL when establishing sessions, restricts the session cookie to SSL and a specific folder, and inherits most other behavior except that it requests only EPPN from the origin instead of asking for all attributes. Note that it will inherit all of the handler endpoints defined for the default application but will append them to the handlerURL defined here. --> <!-- <Application id="foo-admin"> <Sessions lifetime="7200" timeout="3600" checkAddress="true" handlerURL="/secure/admin/Shibboleth.sso" handlerSSL="true" cookieProps="; path=/secure/admin; secure"/> <saml:AttributeDesignator AttributeName="urn:mace:dir:attribute-def:eduPersonPrincipalName" AttributeNamespace="urn:mace:shibboleth:1.0:attributeNamespace:uri"/> </Application> --> </Applications> <!-- Define all the private keys and certificates here that you reference from <CredentialUse>. --> <CredentialsProvider type="edu.internet2.middleware.shibboleth.common.Credentials"> <Credentials xmlns="urn:mace:shibboleth:credentials:1.0"> <FileResolver Id="switchaai"> <Key> <Path>C:/opt/shibboleth-sp/etc/shibboleth/sp.example.ch.key</Path> </Key> <Certificate> <Path>C:/opt/shibboleth-sp/etc/shibboleth/sp.example.ch.crt</Path> </Certificate> </FileResolver> <!-- Mostly you can define a single keypair above, but you can define and name a second keypair to be used only in specific cases and then specify when to use it inside a <CredentialUse> element. --> <!-- <FileResolver Id="inqueuecreds"> <Key> <Path>C:/opt/shibboleth-sp/etc/shibboleth/inqueue.key</Path> </Key> <Certificate> <Path>C:/opt/shibboleth-sp/etc/shibboleth/inqueue.crt</Path> </Certificate> </FileResolver> --> </Credentials> </CredentialsProvider> <!-- Specialized attribute handling for cases with complex syntax. --> <AttributeFactory AttributeName="urn:oid:1.3.6.1.4.1.5923.1.1.1.10" type="edu.internet2.middleware.shibboleth.common.provider.TargetedIDFactory"/> </SPConfig>
Download the Attribute Acceptance Policy file AAP.switchaai.xml
and store it as C:\opt\shibboleth-sp\etc\shibboleth\AAP.switchaai.xml .
This file implements the AAI Attribute Specifications and maps the attributes to Apache environment variables. For more information about the specification, see the PDF document: http://www.switch.ch/aai/docs/AAI_Attr_Specs.pdf.
Download the SWITCHaai metadata file metadata.switchaai.xml and store it as C:\opt\shibboleth-sp\etc\shibboleth\metadata.switchaai.xml.
The SWITCHaai federation metadata must be periodically updated to keep your resource up-to-date with the actual state of the federation. See the SWITCHaai Federation Metadata page for more information.
The Shibboleth SP will log in the C:\opt\shibboleth-sp\var\log\shibboleth\ directory.
Logging is configured in the files shibd.logger, shibboleth.logger and native.logger.
IIS6 introduced the concept of "Web service Extensions". Therefore, this part of the configuration is not needed in Windows 2000 Server.
The 1.3 package is able to configure it by itself, but you should check in the IIS administration console, under "Web Service Extensions", that
a "Shibboleth Web Service Extension" is displayed and allows "C:\opt\shibboleth-sp\libexec\isapi_shib.dll". If not, add it.
This part applies to all windows versions.
Once again, the shibboleth 1.3 package should configure it. Go to "Web sites" Properties panel of the administration console ("Server properties > Internet information service tab
> Edit WWW Master Properties" for Win 2000), "ISAPI Filters" Tab, and check that a High-Priority Filter called "Shibboleth" is present and loaded.
If not, create it and restart IIS.
C:\iisresetIf the filter cannot be loaded, this may be due to errors in the configuration file
shibboleth.xml and file permissions of
the ISAPI filter isapi_shib.dll.
The following permission settings can solve the problem of the filter not being loaded:
libexec\isapi_shib.dll libexec\isapi_shib.dll
Still in the "Web Sites" properties panel, go to the "Home Directory" Tab, and open the "Configuration" window. On the first tab ("Mappings"),
check that the .sso extension is correctly mapped to C:\opt\shibboleth-sp\libexec\isapi_shib.dll for all verbs, with "script engine" option activated.
Finally start the Shibboleth 1.3 Daemon (shibd):
From Services MMC snap-in, start the "Shibboleth 1.3 Daemon" service.
It is vital that you register your Service Provider in the AAI Resource Registry.
Do the following steps to register a resource:
Find detailed instructions on how to protect a resource with Shibboleth on Shibboleth Service Provider Access Rules.
-- $Id: install-sp-1.3-win2003.html,v 1.20 2007/12/19 14:20:22 schnell Exp $