| Wiki Markup |
|---|
h2. Shibboleth SP 1.3 Install & Configuration For Windows/IIS6
{tip}Audience: System/Application Administrators
Category: Technical Guides
Version/Platform: Shibboleth SP 1.3 / Linux-Apache{tip}
This guide describes the process of installing and configuring a Shibboleth SP module *v1.3* for this environment:
_OS: Windows 2000/2003 server_
_Web Server: IIS_
[Internet2 Wiki|https://spaces.internet2.edu/display/SHIB/WebHome] provides most of the material. The document below is only a supplement.
Below instruction is for configuring Shibboleth SP to work with UCLA {nl:IdP} test instance. [Production configuration|ShibbolethSPMigration2Production] varies slightly.
h3. Intended Audience
This document is intended for developers and system administrators who will be installing and maintaining a Shibboleth Service Provider server at UCLA. The audience is expected to have following skills:
* Familiarity with the local operating system, including how to install software.
* Install and Configure web servers (Apache, IIS, etc).
* Basic understanding of SSL, including how to generate a key and CSR.
* Basic understanding of XML.
* University Policy
* You will need Administrative privileges on the machine you are installing the software on
This document covers only the technical aspects of running a Shibboleth SP software. What is equally important and one that is not covered here is the policy requirements of accessing the user data. Depending on the data(attributes) requirements, you need appropriate permission from data owners i.e Registrar's office for Student date, HR for staff and faculty. Until this request is made and approved, no production data will be released to your application. You will have to plan for data approval from respective data owners and begin to use those data according to your business needs.
h3. Before you start
Before you install Shibboleth SP software, create a simple web application to display HTTP header attributes.
Sample asp.net code to display HTTP headers:
{code}
For k = 0 To Request.Servervariables.Count - 1
Response.Write(Request.Servervariables.Keys(k) & " = " & Request.Servervariables(k) & "<br>"
Next
{code}
Make sure you can access the page from a browser (for ex, {nl:http://yourhost.ucla.edu/yourapp/DisplayHttpHeaders.aspx}). This page does not require Authentication yet. You will probably see a bunch of http headers information.
The idea here is to display http headers before and after shibboleth installation and compare the difference to see what shibboleth delivers. If shibboleth successfully installed you will see all http headers you saw before plus attributes delivered by shibboleth.
h3. Download & Install
Download Shibboleth SP software from Internet2 website. The site also offers documentation for installing Shibboleth on various platforms. Follow the appropriate Service Provider Installation instructions for your platform.
Please note the site is maintained by internet2, and may have moved. If you can't locate appropriate version for your environment please contact AIS. Download is at [http://shibboleth.internet2.edu/downloads/shibboleth/cppsp/1.3.1/win32].
Download the .msi Shibboleth SP installer from the download site. Run the installer. The installer will prompt for an install path, change default configuration files as appropriate for Windows, and set various environment variables for you. A service by the name _shibd_ is also installed.
Reboot the server for the changes to take effect. You have to make several configuration changes to make it work.
h2. Configuration
h3. IIS filter
* ISAPI filter
Go to IIS Manager. Right click on [WebSites], select Properties. Click on ISAPI Filters. Make sure the Shibboleth filter shows up with a green arrow. If you don't see the filter add it.
Check the Windows event log and/or the Shibboleth logs if it fails to load.
* SSO extension
Go to IIS Manager. Right click on [WebSites], select Properties. Click on "Home Directory" tab. Click on "Configuration" button. Scroll down and verify there is an ".sso" extension pointing to the isapi_shib dll. If you don't see the extension add it. You should NOT select the option to limit verbs, and you MUST uncheck the "Check that file exists" box.
If you made these changes reboot the server.
h3. shibboleth.xml
This is the main configuration file for Shibboleth SP. It includes configuration items such as the port Shibboleth deamon runs on, Resources to protect, SSL certificates to use, providerId etc.
Eventually we will have a form where you can fill out the values specific to your application and have a custom shibboleth.xml generated for you. But for now, change the following variables specific to your SP.
You may grab a trimmed version of shibboleth.xml file at [this link|https://spaces.ais.ucla.edu/download/attachments/8224874/iis.shibboleth.xml]. It is a bit easier to read and navigate through.
{code:xml}
<TCPListener address="127.0.0.1" port="1600" acl="127.0.0.1" />
{code}
Shibboleth daemon listens on this port for requests coming from the web server. Make sure this port is available. This port should not be open to public.
{code:xml}
<Host name="yourhost.ucla.edu">
<Path name="yourapp" applicationId="yourapp" authType="shibboleth" requireSession="true" exportAssertion="true"/>
</Host>
{code}
The name of the server/VM instance host your SP is residing on. Replace _yourhost.ucla.edu_ with the actual host name of the site that your shibboleth SP is installed on. Do not include http, https etc.
Path is for individual applications within the same host. You may configure multiple applications using multiple <path>. For simplicity configure just one application.
We chose the application name _yourapp_ for demo purpose only. Use a meaningful application name.
{builder-hide}
Most SP installs will only include one application on the server - if this is the case then you can ignore the second occurrence of {{Host name}}. {{{builder-hide}
{code:xml}
<ISAPI normalizeRequest="true">
<Site id="1615594566" name="yourhost.ucla.edu">
<Alias>yourhost.ucla.edu</Alias>
</Site>
{code}
The site id can be found in IIS Enterprise Manager.
{builder-hide}
Once in the program click on Websites, on the right pane where it lists virtual sites one of the columns is 'identifier' - that contains the id you will put in here. If you are unsure about the Alias just put in the host name.
{builder-hide}
{code:xml}
<Applications id="default" providerId="https://yourhost.ucla.edu/shibboleth/sp" homeURL="https://yourhost.ucla.edu/index.htm">
<Sessions lifetime="7200" timeout="3600" checkAddress="false" consistentAddress="true" handlerURL="/Shibboleth.sso" handlerSSL="false" cookieProps="; path=/;" idpHistory="true" idpHistoryDays="7">
{code}
providerId: The providerId is an identifier for SP. This is how SP identifies itself to the IdP or other federation members. You may choose an arbitrary string, we recommend the above URL convention.
homeURL: homeURL is where the SP redirects the user to, when there is nothing else that can be done with a request. It should be set to a application home page or index page.
handlerURL: Set this to /Shibboleth.sso. SP constructs a url based on this relative path (for ex, {nl:http://yourhost.ucla.edu/Shibboleth.sso/SAML/POST})and passes to IDP. IDP posts the authn assertion to this URL. The ISAPI filter processes all requests to this path and handles accordingly.
{builder-hide}cookieProps: Add application context to cookieProps property (for ex, _cookieProps="; path=/; yourapp"_).{builder-hide}
handlerSSL: For test or development this is usually set to false. If user can get to your application with https URL instead of http, then set to true.
{code:xml}
<Errors session="$SHIB-HOME/etc/shibboleth/sessionError.html"
supportContact="support-contact-email-address@ucla.edu"/>
{code}
User will see this error page if there is an error during Shibboleth processing. Customize this html page to show a more friendly message. Include a proper support contact e-mail.
{code:xml}
<SessionInitiator isDefault="true" Location="/yourapp/DisplayHttpHeaders.aspx" Binding="urn:mace:shibboleth:sp:1.3:SessionInit" wayfURL="https://shb1.ais.ucla.edu/shibboleth-idp/SSO" wayfBinding="urn:mace:shibboleth:1.0:profiles:AuthnRequest" />
{code}
{nl:SessionInitiators} handle session requests for applications and relay them to a Single Sign On service of IdP. If a Shibboleth session is not yet established, it redirects to wayfURL to request for an Authentication session for the user.
In the above configuration wayfURL points to Single Sign On of UCLA IdP's Test instance.
{code:xml}
<CredentialUse TLS="shib_credentials" Signing="shib_credentails">
</CredentialUse>
{code}
{nl:CredentialUse} describes credentials that SP uses when communicating with various {nl:IdPs}. _shib_credentials_ above is just a placeholder; Actual credentials details (certificate & key) described further down in {nl:FileResolver} section.
{code:xml}
<Application id="yourapp" providerId="https://yourhost.ucla.edu/shibboleth/sp">
<Sessions lifetime="7200" timeout="3600" checkAddress="true" consistentAddress="true"
handlerURL="/Shibboleth.sso" handlerSSL="false" cookieProps="; path=/;"/>
</Application>
{code}
You can customize the behavior of specific applications here. The default elements inside the
outer <Applications> element generally have to be overridden in an all or nothing fashion.
Note that single SP instance can support multiple applications which can be configured differently.
{code:xml}
<CredentialsProvider type="edu.internet2.middleware.shibboleth.common.Credentials">
<Credentials xmlns="urn:mace:shibboleth:credentials:1.0">
<FileResolver Id="shib_credentials">
<Key>
<Path>$SHIB-HOME/etc/shibboleth/testshib.key</Path>
</Key>
<Certificate>
<Path>$SHIB-HOME/etc/shibboleth/testshib.crt</Path>
</Certificate>
</FileResolver>
{code}
Change the location of key and certificate files as appropriate. See Certificate and Metadata section below to obtain a test key/certificate.
h3. shibd.logger
This is a configuration file for logging. Configure location of log file, log to a file or database, level of logging (verbose or errors only). Make sure your Web Server (IIS) can write to it. If you are testing you may want to use DEBUG level which dumps lot of diagnostic information.
h4. native.logger
Similar to shibd.logger. Contains generic Web Server information rather than the shibd daemon.
h3. Certificate and Metadata
To test with {nl:IdP} test instance you will need a Certificate and Key. Details on obtaining test certificate described in this [document|iamucla:TestshibFederation]
h3. AAP.xml
IdP delivers attributes using standard naming convention. Map them to custom http header names (or Alias) that your application expects. Your application will not receive any attributes unless they are configured in AAP.xml with a Header name.
Verify attribute names with the attribute provider (IdP).
AIS always releases at least one attribute in test urn:mace:dir:attribute-def:eduPersonTargetedID. Rest of the attributes are released on request.
You may use the simple rules below to replace the default AAP.xml. If you expect more than the below 3 attributes, code additional <[AttributeRule]>.
If you don't see the attributes you expect, perhaps IdP is not releasing them. Check with IdP.
{code:xml}
<AttributeAcceptancePolicy xmlns="urn:mace:shibboleth:1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="urn:mace:shibboleth:1.0 /usr/share/xml/shibboleth/shibboleth.xsd">
<AttributeRule Name="urn:mace:dir:attribute-def:eduPersonTargetedID" Header="SHIB-TargetedID" Alias="targetedId">
<AnySite>
<AnyValue />
</AnySite>
</AttributeRule>
<AttributeRule Name="urn:mace:ucla.edu:edimi:attributes:uclaUniversityID" CaseSensitive="false" Header="SHIB-UID" Alias="uid">
<AnySite>
<AnyValue />
</AnySite>
</AttributeRule>
<AttributeRule Name="urn:mace:dir:attribute-def:mail" CaseSensitive="false" Header="SHIB-EMAIL" Alias="affiliation">
<AnySite>
<AnyValue />
</AnySite>
</AttributeRule>
</AttributeAcceptancePolicy>
{code}
h3. Attributes
Visit [Available Attributes|AvailableEDAttributes] page for more attributes and the usage of these attributes within the AAP.xml.
Attributes will be released to SPs as appropriate. For ex,
_urn:mace:dir:attribute-def:displayName_ Joe Bruin
_urn:mace:dir:attribute-def:eduPersonPrincipalName_ jbruin@ucla.edu
_urn:mace:ucla.edu:edimi:attributes:uclaUniversityID_ 676767676
Note the naming convention. Standard eduPerson attributes defined by MACE start with _urn:mace:dir:attribute-def:_ ; Custom attributes specific to UCLA start with _urn:mace:ucla.edu:edimi:attributes:_
h3. http vs https
Most of the development/test servers don't have SSL certs to protect the web content. Change your shibboleth.xml configuration for this. Set handlerSSL="false" and remove the parameter redirectToSSL="443". You may want to revisit this when you move to Production.
h3. Test Run
Make sure the xml file shibboleth.xml is well-formed. Typos are common errors. Opening this file in IE indicates any structural errors.
Now that you completed above configuration changes run the Shibboleth daemon. From command line run
_$SHIB-HOME/sbin/shibd \-console \-check_
Check the console and log files (native.log & shibd.log). If you see no errors you got the basics right. Not all problems can be detected this way. Only an end-to-end testing involving the {nl:IdP} will confirm if its been set up & configured properly.
h3. Restart IIS and Shibboleth daemon
Now access the same sample page, {nl:http://yourhost.ucla.edu/yourapp/DisplayHttpHeaders.aspx}. You will see same http headers you saw earlier plus some Shibboleth attributes like {nl:eduPersonTargetedID}. If you saw Shibboleth attributes, end-to-end testing is successful.
Attribute name you see on the page depends on how you mapped in AAP.xml.
If you saw errors on page, or didn't see the attributes check the logs first (shibd.log). Contact the {nl:IdP}(AIS) and verify SP has been configured properly at the {nl:IdP}.
h3. Additional Resources
Shibboleth Wiki - The [Shibboleth Wiki|https://spaces.internet2.edu/display/SHIB/WebHome] is the primary source of documentation for all aspects of installing and configuring Shibboleth.
Internet2 Mailing Lists - the Shibboleth project maintains three mailing lists to announce news and discuss Shibboleth development and deployment. You are strongly encouraged to join shibboleth-users if you have any trouble installing or configuring Shibboleth. Subscription details are available at [http://shibboleth.internet2.edu/support.html#lists]
For a list of common errors visit [https://spaces.internet2.edu/display/SHIB/CPPSPCommonErrors] |
Page History
Overview
Content Tools