This document describes the procedure used to install Shibboleth Service Provider (SP) software on Windows Server and Internet Information Server (IIS), and to configure it to work with the Cornell Shibboleth Identity Provider (IdP).
Table of Contents |
---|
Prerequisites
...
- Shibboleth Service Provider 3.x software supports Windows Server 2008 and later, and installers are available for both 32-bit and 64-bit systems. Shibboleth 3.x supports the versions of the IIS web server that are provided with the supported Windows versions.
...
- The IIS website must have an appropriate SSL certificate installed and SSL enabled. To request a SSL certificate: https://it.cornell.edu/ssl/renew-or-request-ssl-certificate
- If you have any URL rewrite rules defined in IIS, make sure those rules do not apply to Shibboleth.sso path. Or you can add this rule at the top of all the other rules that will stop redirecting any request for /Shibboleth.sso
Installation
Expand | |
---|---|
|
...
|
...
These links may break at some point, but for now the 32-bit and 64-bit run times can be found at: https://aka.ms/vs/15/release/VC_redist.x86.exe https://aka.ms/vs/15/release/VC_redist.x64.exe The top-level link to find them is https://visualstudio.microsoft.com/downloads/ via Other Tools |
...
Expand | ||
---|---|---|
|
...
|
...
1 |
...
Download the latest version of the Windows installer package from the Shibboleth download site at https://shibboleth.net/downloads/service-provider/latest/. Select either the win32/ or win64/ directory as appropriate to your 32-bit or 64-bit system. Then download .msi file. 2 |
...
Run the installer package. It is recommended that you accept all defaults, as follows:
|
...
|
...
|
...
|
Expand | ||
---|---|---|
| ||
On |
...
the Administrative Tools menu, click Services. Find Shibboleth Daemon in the list and double-click it. Verify that Service Status |
...
is "Running", Startup type |
...
is "Automatic", and on the Log On tab, verify |
...
that "Local System |
...
" is selected. |
...
Configuration
...
Go to your SP installation directory(C:\opt\shibboleth-sp
if you
...
use the default) . All the SP configuration files are in the \etc\shibboleth directory.
...
...
Expand | ||
---|---|---|
|
Save a copy of |
...
attribute-map.xml |
...
to attribute-map.xml.orig |
...
or similar. Download our sample attribute-map.xml and replace your attribute-map.xml with downloaded file. Our attribute-map.xml defines all commonly used attributes. All attributes except groups are released by default to all SP. Attribute "groups" is released on demand. Submit group membership requirement when you submit shibboleth integration request form. Find all the default attributes released by Cornell IDP from Shibboleth at Cornell Page. Edit attribute-map.xml as needed. |
Expand | ||
---|---|---|
| ||
Save a copy of |
...
or similar. Download our sample shibboleth2.xml and replace your shibboleth2.xml with downloaded file. Open shibboleth2.xml in a text editor.
Find <ISAPI...>...<Site id="1" name=" |
...
shibtest.cit. |
...
cornell. |
...
edu"/>. Change the "site id" to match the id assigned to your site by IIS. You can find your site id in Internet Services (IIS) Manager by clicking on "Sites". |
...
In this same location, change the site name to your |
...
Verify that scheme="https" and port="443". Note that if you're using a non-standard SSL port you should use that instead of 443.
...
website domain name |
...
. Our example defined two sites. Delete or add more as needed.
|
Find <RequestMap>...<Host name=" |
...
shibtest.cit. |
...
cornell. |
...
edu">. Change the "Host name" to |
...
4.3 Find <ApplicationDefaults entityID=" https://sp.example.org/shibboleth "...>. Replace https://sp.example.org/shibboleth with something based on your DNS name (e.g. https://myserver.mydept.washington.edu/shibboleth ).
4.4 Find <ApplicationDefaults...>...<Sessions...>...checkAddress="false" handlerSSL="false" cookieProps="http"> ...Change to checkAddress="true" handlerSSL="true" cookieProps="https">
If you are using DNS proxy, such as Amazon Route 53, you may receive a "500 - Internal server error." when testing. This is caused by the client's IP address differing from the one used to authenticate to the identity provider. The work around is to set checkAddress="false" instead of "true"; while useful for security, NAT and proxy usage (as well as IPv6 support on only either the webserver hosting the IdP or the SP) often make this setting a source of errors.
4.5 Find <ApplicationDefaults...>...<Sessions...>...<SSO entityID="https://idp.example.org/shibboleth"...>.... Change the entityID to "urn:mace:incommon:washington.edu" (just "urn:mace:incommon:washington.edu" NOT" https://urn:mace:incommon:washington.edu/shibboleth "). Remove discoveryProtocol="SAMLDS" discoveryURL =" https://ds.example.org/DS/WAYF ".
...
the site name you defined in step above. In this example file, we defined two hosts and specifies different authorization rules for each site and location. Please modify it to meet your site requirement. If your site supports both http and https, add redirectToSSL="443" in Host element because shibboleth SP doesn't work with http connection.
Find <ApplicationDefaults entityID="https://shibtest.cit.cornell.edu/shibboleth" ...>. EntityID is the unique identifier for your SP. Cornell Shibboleth Identity Provider(IDP) provides service to many applications. This entityID will help Cornell IDP to identify your SP. We recommend you follow shibboleth convention named it "https://yourDomainName/shibboleth". It's better not include space or special characters in it( / or : are fine). You can use one entityID for all your sites hosted in the same IIS.
Find < Errors supportContact ="root@localhost" helpLocation ="/about.html" styleSheet ="/shibboleth-sp/main.css" /> |
...
. Change the email address to your application's support email address. |
4.7 Find the <MetadataProvider...>...</MetadataProvider> section and un-comment the metadata type you'll be using by removing the <!-- and --> tags that surround it.
4.8 If your SP will rely only on the UW IdP for user authentication, skip steps 4.9 and 4.10 and follow instructions at UW IdP Metadata. If your SP will rely on other IdPs from InCommon, continue on at step 4.9.
4.9 Find <MetadataProvider type="XML" url="http://federation.org/federation-metadata.xml"...>. Change the url to "http://md.incommon.org/InCommon/InCommon-metadata-idp-only.xml".
4.10 Find ...backingFilePath="federation-metadata.xml" reloadInterval="7200">. Change the backingFilePath to =
"InCommon-metadata.xml".
4.11 Find <MetadataProvider...><MetadataFilter type="Signature" certificate="fedsigner.pem"/>. Change the certificate to "inc-md-cert.pem
".
4.12 Save shibboleth2.xml and close your editor.
4.13 Use Internet Services (IIS) Manager to restart IIS and Administrative Tools > Services to restart the Shibboleth 2 Daemon.
4.14 Restart the web server and the access the URL from the server's browser: https://<your dns name>.sso/Shibboleth.sso/Session . The web server should return a page that says:
A valid session was not found. |
This message demonstrates that the Shibboleth module is loaded by the webserver and is communicating with the shibd
process.
...
Find <SSO entityID=" https://shibidp.cit.cornell.edu/idp/shibboleth ">.Replace our production IDP's entityID with test IDP's entityID: https://shibidp-test.cit.cornell.edu/idp/shibboleth Find <MetadataProvider ... url=" https://shibidp.cit.cornell.edu/idp/shibboleth " ..>. This is production IDP's metadata url. Comment out this block for your test site. Then un-comment MetadataProvider for Cornell test IDP.
|
Expand | |||||
---|---|---|---|---|---|
| |||||
Go to your SP installation directory(
"overall configuration is loadable, check console for non-fatal problems" If there is error, check log for detail. All the log files are in SP installation directory\var\log\shibboleth |
Info |
---|
Whenever you make changes to SP's configuration file, save the file. You can wait for the Shibboleth Daemon to pick up the changes or you can restart the Shibboleth Daemon to make the changes take effect right away. Some changes may require IIS restart. |
Register Service Provider with Cornell IDP
Expand | |||||||
---|---|---|---|---|---|---|---|
| |||||||
|
Expand | ||
---|---|---|
| ||
Submit your shibboleth integration request from https://shibrequest.cit.cornell.edu. On the second page of request form, select 'No' for question "Has the application service provider's metadata been published with InCommon?". Use text editor open your SP's metadata, copy the content of the metadata and paste it in the "Service Provider's metadata field. Once the form is submitted, Identity Management get a Remedy case. We'll configure your SP in prod IDP in 1 - 2 business day. We'll notify you when the configuration is complete. |
Test SP integration with IdP
Confirm that you are able to log in with your netID and user's attributes are properly released.
- Using a web browser, visit the /secure directory (or other protected location) of your SP.
- If you are prompted to log in, that means that your SP is properly integrated with Cornell IdP.
- After you log in, open a new tab of the same browser and point your web browser to https://<your dns name>/Shibboleth.sso/Session. Your browser should return a status page that show you all the attributes and values released to your SP.
FAQ
Expand | ||
---|---|---|
| ||
"Looping" refers to a situation in which an attempt to login to the SP results in a rapid cycle of redirections between the IdP and the SP with a new session created every time around. Please follow the instructions from Shibboleth WIKI page to troubleshoot. |
Expand | ||
---|---|---|
| ||
If possible snap shot your Windows server before you make any changes. When integrating your website with Shibboleth, you will need to submit a Shibboleth integration request form. After IDM receive the request, your SP's metadata will be configured in Cornell Identity Provider(IDP). It may take as long as one business day for IDM to complete your request. Before your SP's metadata is loaded in IDP, shibboleth authentication won't work. To avoid the long down time of your production website, we recommend you make the transition in two steps and make the changes during maintenance hours. <ISAPI normalizeRequest="true" safeHeaderNames="true"> <! – <Site id="1" name="shibtest1.cit.cornell.edu"/ > --> <! – <Site id="2" name="shibtest2.cit.cornell.edu"/ > → </ISAPI>
|
Expand | ||
---|---|---|
| ||
By default, Shibboleth attributes that released to your shibboleth SP are available to your application as server variables, not available in HTTP headers. But not all the server/module expose custom server variables to application, for example .asp. It's dangerous using HTTP headers. If you have to get Shibboleth attributes from HTTP header, you could enable it by adding useHeaders=”true” in <ISAPI tag>. In your application, you should always get authenticated user's netID from server variable REMOTE_USER. Detail and examples about attribute access https://wiki.shibboleth.net/confluence/display/SP3/AttributeAccess SpoofChecking if using HTTP headers https://wiki.shibboleth.net/confluence/display/SP3/SpoofChecking |
Need Help?
contact idmgmt@cornell.edu