Shibboleth Service Provider - Installation (Windows/IIS)

Description

Use this guide in addition to the official Shibboleth Service Provider documentation to perform the installation and configuration of a Shibboleth service provider on a Windows server (IIS). The OS used to develop this guide:

Windows 2022 (IIS)

Shibboleth Service Provider - About

Applicable To:

IT Admins and System Admins of CSU System Shibboleth Service Providers

System Prerequisites:

Please review the Shibboleth System Requirements for Shibboleth Service Providers in the CSU System

Install or Add Management Capability
- Install IIS
Configure SSL Certificate
- CSR & Private Key
  - Create CSR
  - Submit CSR
- Configure Public Cert
Website Hosting Preparation
- Prepare IIS
  - Set up Files and Folders for Testing
  - Configure Test Pages in IIS
- Test
Shibboleth Service Provider Installation
Shibboleth Service Provider Configuration

Configure Metadata
Configure Signing Certificate
Configure Web Server Settings
Configure Request Mapping, App Defaults and Sessions
Configure Errors
Configure Handlers
Test for Configuration Errors

Instructions:

1.) Install or Add Management Compatibility

Install IIS

Open Server Manager > Manage menu > Add Roles and Features
Click Installation Type > Role-based or feature-based installation > Click Next
In Server Selection, Select your server > Click Next
In Server Roles, select Web Server (IIS)
1. A new window will appear, select Add Features
Click Role Services that now appears in the left-hand menu
Select:
1. Application Development > ISAPI Extensions
2. Application Development > ISAPI Filters
3. Management Tools > IIS [#] Management Compatibility > IIS [#] Metabase Compatibility
4. You can now, or later, add any other requirements of your IIS application
5. Click Next
Click Install
Click Close after installation complete

2.) Configure SSL Certificate

CSR (Certificate Signing Request) & Private Key

Create CSR

NOTE: Certificate requests processed through CSU's InCommon SSL Certificate request portal can take up to 24 hours over business days to complete and process

Open the Internet Information Services (IIS) Manager and select your server from the left-hand side menu
Double-click Server Certificates
2. Under Actions, in right-hand pane, select Create Certificate Request...
3. Be sure the Common name matches the name of the website (and not necessarily of the server-itself)
  1. Click Next
4. In the Cryptographic Service Provider Properties, select Bit length: 2048
  1. Click Next
5. Select a location and filename for your CSR (Certificate Signing Request)
  1. Click Finish

Submit CSR

For requests with CSU's InCommon SSL Certificate request portal:
1. Log in to CSU's InCommon SSL Certificate request portal (VPN/campus access required)
  1. Recommended: include your full department's email in the Contact Email field
2. Allow up to 24 hours over business days to receive an email with your public certificate information and double-check your spam and other folders.

Configure Public Cert

Retrieve your server's public certificate
1. For InCommon SSL certificates, you'll receive an email titled Your SSL certificate for <website> is ready
2. From the email, select + download the link titled as Certificate only, PEM encoded (should be the first available certificate format)
3. Copy the certificate file onto your web server in an accessible location
Configure your certificate in IIS
1. Open the Internet Information Services (IIS) Manager and select your server from the left-hand side menu
2. Double-click Server Certificates
  1. Under Actions, in right-hand pane, select Complete Certificate Request...
    1. Navigate to and select your certificate file
    2. For Friendly name, enter a value for your service (does not need to be the full domain name)
    3. Under Select a certificate store for the new certificate, select Web Hosting
    4. ClickOK
3. Your certificate should now appear in the Server Certificates middle pane

3.) Website Hosting Preparation

Prepare IIS

Set up Files and Folders for Testing

In File Explorer, navigate to the folder (or create the folder) where your website files will reside
1. Enable File name extensions (if not already enabled)
2. Configure Security Permissions for IIS
  1. Right-click, Select Properties in the empty content area of your website directory
  2. Click the Security tab
  3. Click Edit below the list of Group or user names
    1. Click Add to add the IUSR user (Internet Information Services [IIS] User), if not already added
      1. In Enter the object names to select, type IUSR
        
        Click Check Names
        IUSR should appear underlined (validated)
        
        Click OK
      2. Confirm the IUSR user has Allow permissions for:
        
        Read & execute
        
        List folder contents
        
        Read
      3. Click Apply to save changes
    2. Review the Permissions for the SYSTEM user and Administrator-users, ensuring each has Full control
Create testing infrastructure
1. In "home" folder of your website's folder-structure, create a test file default.htm with contents:
  - ```
  <html>
  Public
  </html>
```
2. In "home" folder of your website's folder-structure, create a folder called secure
  1. In secure, create another test file default.htm with contents:
    - <html> Secure </html>

Configure Test Pages in IIS

Open IIS Manager
1. In left pane, click to expand your server
  1. click to expand Sites
  2. Right-click Default Web Site > Manage Website > Stop
2. In left-hand pane, right-click on Sites > Add Website
  1. Enter your Site name
  2. Select the Physical path to the folder-location of your website
  3. Under Binding select https
    1. Select an appropriate IP address if your site has multiple configured
  4. Under SSL certificate, select the public SSL certificate you created in the prior step
  5. Click OK to save & start website
3. In left-hand pane, click on Sites
  1. Identify the ID associated with the site you just added
  2. Note this Site ID for later

Test

In a browser outside of your server, navigate to your website, using https (https://yoursite.colostate.edu)
- Your default.htm page content displaying Public should load in the browser
- Your SSL Certificate should be valid

4.) Shibboleth Service Provider Installation

Download Shibboleth SP

In a browser outside your server, Navigate to the Shibboleth Software Repository
1. Open the Win64/Win32 folder that matches your system
2. Download the shibboleth-sp-<version>.msii file
3. Copy/move the shibboleth-sp-<version>.msi file onto your server

Install Shibboleth SP

In your server, double-click your shibboleth-sp-<version>.msi file to run the installer
1. Click Next at the Welcome to the Shibboleth... setup screen
2. Check I accept the terms in the License Agreement, click Next
3. For install location, use C:\opt\shibboleth-sp\ and check the box for Configure IIS Support; click Next
4. Click Install
5. Click Finish after install has completed
6. Click Yes to restart your system when prompted

Verify ISAPI Settings

ISAPI (Internet Server Application Programming Interface) is a technology that allows developers to extend the functionality of IIS through custom DLLs.

Open Windows Administrative Tools > Services
1. Locate Shibboleth Daemon (Default), should display:
  1. Status: Started or Running
  2. Startup Type: Automatic
  3. Log on As: Local System
Open Internet Information Services (IIS) Manager to verify ISAPI (Internet Server Application Programming Interface) settings
1. Click to expand your server
  1. Double-click on ISAPI and CGI Restrictions
    1. If Shibboleth is not listed, click Add from right-hand pane
      1. For ISAP or CGI path, find + select C:\opt\shibboleth-sp\lib[64/32]\shibboleth\isapi_shib.dll
      2. Type Shibboleth for Description
      3. Check the box for Allow extension path to execute
      4. Click OK to Save
    2. Shibboleth should now be listed in the center pane
    3. Double-click on your server name in the left-pane to return to the server home
  2. Double-click on ISAPI Filters
    1. If Shibboleth is not listed, click Add from right-hand pane
      1. For Filter name type Shibboleth
      2. For Executable, find + select C:\opt\shibboleth-sp\lib[64/32]\shibboleth\isapi_shib.dll once again
        Click OK to Save
    2. Shibboleth should now be listed in the center pane
  3. Double-click on Handler Mappings

If Shibboleth is not listed, click Add Script Map... from right-hand pane
1. For Request path type *.sso
  1. For Executable, find + select C:\opt\shibboleth-sp\lib[64/32]\shibboleth\isapi_shib.dll one more time
  2. For Name: Shibboleth
  3. Click Request Restrictions...
    1. In Mapping, make sure Invoke handler... is unchecked
    2. In Verbs, make sure All Verbs is selected
    3. In Access, make sure Script is selected
    4. Click OK to Save Request Restrictions
  4. Click OK to Save Edit Script Map
2. Shibboleth should now be listed in the center pane

5.) Shibboleth Service Provider Configuration

Configure Metadata

The shibboleth2.xml file configures and defines settings for the Shibboleth service provider, governing authentication, attribute mapping, and communication parameters with identity providers. Most, if not all, of the settings specific to your service provider will be configured here.

In order for Single Sign-On (SSO) to function in the CSU Federation, your Service Provider will be configured to use the CSU Federation metadata

In File Explorer, make a backup copy of your original C:\opt\shibboleth-sp\etc\shibboleth\shibboleth2.xml file
In File Explorer, create file c:\opt\shibboleth-sp\etc\shibboleth\csufederation-metadata-cert.pem
1. Direct browser (outside of server) to https://csufederation.acns.colostate.edu/publickey/csufederation-metadata-cert.pem and paste contents into file

Open C:\opt\shibboleth-sp\etc\shibboleth\shibboleth2.xml in a text editor

In the same area as the example (commented-out) MetadataProvider elements (near bottom-half of file), add MetadataProvider element for the CSU Test Federation

        <MetadataProvider type="XML" validate="true"
            url="https://csufederation.acns.colostate.edu/csufederationtest-metadata.xml"
            backingFilePath="c:\opt\shibboleth-sp\etc\shibboleth\csufederationtest-metadata.xml"
            maxRefreshDelay="7200">
            <MetadataFilter type="RequireValidUntil" maxValidityInterval="2419200" />
            <MetadataFilter type="Signature"
                certificate="c:\opt\shibboleth-sp\etc\shibboleth\csufederation-metadata-cert.pem"
                verifyBackup="false" />
            <MetadataFilter type="Include">
                <Include>https://shibidptest.colostate.edu/idp/shibboleth</Include>
            </MetadataFilter>
        </MetadataProvider>

Save

Configure Signing Certificate

For entry in the CSU Federation, you will use the same cert+key pair for both signing and encryption in your Shibboleth Service Provider

In shibboleth2.xml, locate the CredentialResolver (near bottom of file) element
In the CredentialResolver element indicated for encryption, replace the cert and key to match the files used for the signing CredentialResolver

Save

        <!-- Simple file-based resolvers for separate signing/encryption keys. -->
        <!-- CSU Federation requires same cert+key pair for both signing & encryption -->
        <CredentialResolver type="File" use="signing"
            key="sp-signing-key.pem" certificate="sp-signing-cert.pem" />
        <CredentialResolver type="File" use="encryption"
            key="sp-signing-key.pem" certificate="sp-signing-cert.pem" />

Configure Web server settings

The <InProcess> section in the Shibboleth configuration file (shibboleth2.xml) is used for settings affecting web server modules, specifically for IIS and is not required for other/non-IIS web servers.

In shibboleth2.xml, locate InProcess (near top of file) element

Add logger="native.logger to InProcess tag
In the Site element, change the name value to your site's domain
- Update the Site id to match the Site ID identified earlier when configuring your IIS test pages

Save

    <InProcess>
        <ISAPI normalizeRequest="true" safeHeaderNames="true">
            <!--
            Maps IIS Instance ID values to the host scheme/name/port. 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.
            -->
            <Site id="2" name="yoursite.colostate.edu" />
            <!--
            When the port and scheme are omitted, the HTTP request's port and scheme are used.
            If these are wrong because of virtualization, they can be explicitly set here to
            ensure proper redirect generation.
            -->
            <!--
            <Site id="42" name="virtual.example.org" scheme="https" port="443"/>
            -->
        </ISAPI>
    </InProcess>

Configure Request Mapping, App Defaults and Sessions

The RequestMapper section in the Shibboleth configuration file defines how incoming requests are mapped to specific authentication and authorization settings based on the requested resource's path and the configured host settings.

In shibboleth2.xml, locate RequestMapper (below InProcess) element

Add logger="native.logger to InProcess tag

Change value for Host name and Path name to match your domain and test file

    <RequestMapper type="Native">
        <RequestMap>
            <!--
            The example 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 above.
            -->
            <Host name="yoursite.colostate.edu">
                <Path name="default.htm" authType="shibboleth" requireSession="true" />
            </Host>
            <!-- Example of a second vhost mapped to a different applicationId. -->
            <!--
            <Host name="admin.example.org" applicationId="admin" authType="shibboleth" requireSession="true"/>
            -->
        </RequestMap>
    </RequestMapper>

Save

The ApplicationDefaults section in the Shibboleth configuration file defines the core SAML settings and behavior for the service provider, including session handling, SSO configurations, error handling, metadata providers, attribute extraction and filtering, as well as credential resolution.

In shibboleth2.xml, locate ApplicationDefaults (below RequestMapper) element

In the ApplicationDefaults tag, change the value for entityID to <https://<yourwebsite>/shibboleth>

<ApplicationDefaults entityID="https://yoursite.colostate.edu/shibboleth"
        REMOTE_USER="eppn subject-id pairwise-id persistent-id"
        cipherSuites="DEFAULT:!EXP:!LOW:!aNULL:!eNULL:!DES:!IDEA:!SEED:!RC4:!3DES:!kRSA:!SSLv2:!SSLv3:!TLSv1:!TLSv1.1">

The Sessions element defines session timeouts and default handler settings. It's recommended to enforce secure cookies by setting cookieProps="; path=/; secure; HttpOnly" to mitigate the risk of unauthorized cookie use, particularly in scenarios where HTTP is disabled on the server. The below configuration provides suggested practices with an explanation for each element should you need to make any changes.

In shibboleth2.xml, locate Sessions (near beginning of ApplicationDefaults) element
In the ApplicationDefaults tag, change the value for entityID to <https://<yourwebsite>/shibboleth>
1. In Sessions tag, add/change:
  - consistentAddress="true"
  - cookieProps="; path=/; secure; HttpOnly; domain=<subdomain>.colostate.edu"
    - replace <subdomain> with the applicable subdomain for your service
2. Save
  - ```
          <Sessions lifetime="28800" timeout="3600" relayState="ss:mem"
              checkAddress="false" consistentAddress="true" handlerSSL="true"
              cookieProps="; path=/; secure; HttpOnly; domain=<subdomain>.colostate.edu"
              redirectLimit="exact">
```

Further Information on Sessions element:

lifetime: maximum duration (seconds) that a session maintained by the SP will be valid
timeout: maximum inactivity (seconds) allowed between requests in a session maintained by the SP
relayState: controls how information associated with requests for authentication, primarily the original resource accessed, is preserved for the completion of the authentication process
- ss:mem uses the SP's persistent storage
checkAddress: The IdP includes the authenticated user agent's IP address in assertions, which the SP verifies against the presenting client's address to establish sessions, but complexities like NAT, proxies, and limited IPv6 support can lead to errors.
- See Address Checking error in CSU's Shibboleth Service Provider - Troubleshooting guide for issues related to "split tunneling"
consistentAddress: when true, the SP will remember the IP address used when creating a session and ensure that all subsequent access associated with this session come from the same address
handlerSSL: when true, only web requests over SSL/TLS will be processed by handlers.
cookieProps: allows appending custom meta-properties like path, secure, and HttpOnly flags to the cookies maintained by the service provider, commonly used with the value "; path=/; secure; HttpOnly" to enforce SSL-only usage.
redirectLimit: prevents the injection of redirect locations after login or logout that don't meet specific criteria, to prevent misusing the SP to carry out phishing attacks.
Shibboleth Service Provider documentation - Sessions

Set up the IdP link and remove the Discovery Service feature from the SSO element. (You can enable the Discover Service at a later point if desired.)

In shibboleth2.xml, locate the SSO (beginning of Sessions) element
1. Set the entityID for CSU's test Identity Provider https://shibidptest.colostate.edu/idp/shibboleth
2. Remove the discovery elements
3. Save
  - ```
              <SSO entityID="https://shibidptest.colostate.edu/idp/shibboleth">
                  SAML2
              </SSO>
```

Configure Errors

In shibboleth2.xml, locate the Errors (below Sessions) element

Set a value for supportContact and set helpLocation="https://wsprod.colostate.edu/cwis262/shibidplogout/error.aspx" to use for testing
- https://wsprod.colostate.edu/cwis262/shibidplogout/error.aspx is designed to be used for testing-only.
You may edit the styleSheet now or later

Save

        <Errors supportContact="<yourhelpemail>"
            helpLocation="https://wsprod.colostate.edu/cwis262/shibidplogout/error.aspx"
            styleSheet="/shibboleth-sp/main.css" />

In shibboleth2.xml, locate the Handler (in bottom of Sessions) elements
1. In each element (MetadataGenerator, Status, Session, DiscoverFeed), review and update the acl values if you've decided to add the IP address restriction
  - IP addresses are space-separated
  - Can list individual IP addresses or use CIDR notation as a subnet
2. Save
3. Note: The MetadataGenerator handler, shipped with the Shibboleth Service Provider, is also deprecated (by Shibboleth), without a suggested replacement. DEPRECATED warnings in Shibboleth indicate that the feature is likely to be removed from the next future major version change. This feature is useful in initial testing and configuration, but not required once configuration is complete. To suppress DEPRECATED warnings, consider commenting-out this feature at a later point, once configuration is complete.
  - ```
  
              <Handler type="MetadataGenerator" Location="/Metadata" signing="false" acl="10.205.0.0/24 10.206.0.0/24" />
  
              
              <Handler type="Status" Location="/Status" acl="10.205.0.0/24 10.206.0.0/24" />
  
              
              <Handler type="Session" Location="/Session" showAttributeValues="false" acl="10.205.0.0/24 10.206.0.0/24"  />
  
              
              <Handler type="DiscoveryFeed" Location="/DiscoFeed"  acl="10.205.0.0/24 10.206.0.0/24"  />
          </Sessions>
```

Test for Configuration Errors

This will test for a functional shibboleth2.xml configuration

Make sure your shibboleth2.xml file is saved
Open Windows Administrative Tools > Services > Shibboleth Daemon > Right-click Restart
1. If the Daemon fails to restart, you'll generate a message. This typically indicates an error in the xml of your shibboleth2.xml file. Review and resolve before continuing to the next step
2. In Command Prompt, execute C:\opt\shibboleth-sp\sbin64\shibd -check
3. Your response should include a DEPRECATED warning about the metadataGenerator handler and a confirmation message that your configuration is loadable
  - ```
  C:\opt\shibboleth-sp\etc\shibboleth>C:\opt\shibboleth-sp\sbin64\shibd -check
  2024-03-15 15:50:51 WARN Shibboleth.DEPRECATION : MetadataGenerator handler
  overall configuration is loadable, check console or log for non-fatal problems
```
4. Test Shibboleth Handlers
  1. In a browser, test each handler:
    1. https://<yoursite>/Shibboleth.sso/Metadata
      - Will display or download a default metadata file
    2. https://<yoursite>/Shibboleth.sso/Status
      - Will display status and metadata .xml
    3. https://<yoursite>/Shibboleth.sso/DiscoFeed
      - Will display json output
    4. https://<yoursite>/Shibboleth.sso/Session
      - Will display "A valid session was not found."
5. If you generate any ERRORS, review and resolve before continuing
  1. To aid in resolution, review logs at: C:\opt\shibboleth-sp\var\log\shibboleth
    1. shibd.log
    2. shibd_warn.log

Outcome:

CONGRATULATIONS! You now have a Shibboleth Service Provider ready for customization and further configuration to start performing Single Sign-On Configurations.