== [[https://iam.alaska.edu/shib|Shibboleth]] / Shibboleth SP Setup ==

This page documents installing a Shibboleth SP.

UA Supported Configurations:
* Apache or IIS on Windows 
* Apache on Linux
* Shibboleth SP Version 2.5

N.B. 2014-05-08: RHEL - we now recommend you use /etc/shibboleth metagen.sh (rather than curl) to generate the SP's metadata (step 5 below)!

Installation:
1. Download and install the appropriate installers/packages.
 * Windows: (It is recommended to use the MSIs.)
   * [[http://www.shibboleth.net/downloads/service-provider/latest/win32/|Latest 32-bit Windows Installer Packages]]
   * [[http://www.shibboleth.net/downloads/service-provider/latest/win64/|Latest 64-bit Windows Installer Packages]]
 * Linux: (It is recommended to use a binary repo.)
  * [[http://download.opensuse.org/repositories/security://shibboleth/|Binary RPMs]]
  * [[http://www.shibboleth.net/downloads/service-provider/latest/SRPMS/|Source RPMs]]
NOTE: experience with upgrading the Parking app from 32-bit to 64-bit, per Walker Wheeler:
"[An] anomaly was caused by a modification to an application pool configuration setting in IIS setting to be 64bit instead of 32bit to support the newer Oracle client the product was using. This modification resulted in the application not finding a ISAPI filter for Shibboleth. Adding the 64 bit isapi_dll for Shibboleth resolved this issue." If both the 32 and 64 bit isapi_dll versions were installed, it would seem to be cheap insurance against encountering a future anomaly.
2. Configure the SP[[br]]
 2.1. Remove and regen the SP keys.
  * Linux:
{{{
[root@idmt-1 shibboleth]# pwd
/etc/shibboleth
[root@idmt-1 shibboleth]# rm -rf sp-key.pem sp-cert.pem 
[root@idmt-1 shibboleth]# ./keygen.sh 
Generating a 2048 bit RSA private key
...........................................................................................+++
.........................................................................................................................................................+++
writing new private key to 'sp-key.pem'
-----
}}}
  * Windows: TBD
 2.2. Download and setup the IdP's metadata. Check config for correct syntax.
There are two approaches; either is configured in '''shibboleth2.xml''' configuration file:[[br]]
 2.2.1 simply keep an unchanging local copy of the UA IdP metadata (quicker but less robust) [[br]]
 2.2.2 use the !InCommon metadata and refresh to maintain current version (preferred robust and extensible option)[[br]]
The first option is easier to set up; if the IdP metadata changes, however - in particular if the IdP's certificate is changed and published in new metadata, you will have to be aware of that change and manually update the local copy.  The second option requires importing the !InCommon signing key, and will trigger refreshes of the metadata on a schedule you choose (usually every several hours).  The second method is more general and would allow you to include additional Identity Providers from !InCommon should that need arise. [[br]]
[[br]] Option 1 (discouraged): Manually maintained local copy of IdP metadata:

  * Linux:
{{{
[root@idmt-1 shibboleth]# wget https://idp.alaska.edu/idp-metadata.xml
--2011-06-27 15:50:17--  https://idp.alaska.edu/idp-metadata.xml
Resolving idp.alaska.edu... 137.229.114.38
Connecting to idp.alaska.edu|137.229.114.38|:443... connected.
HTTP request sent, awaiting response... 200 OK
Length: 6973 (6.8K) [application/xml]
Saving to: `idp-metadata.xml'

100%[===================================================================================================================================================================================================>] 6,973       --.-K/s   in 0s      

2011-06-27 15:50:17 (302 MB/s) - `idp-metadata.xml' saved [6973/6973]
[root@idmt-1 shibboleth]# pwd
/etc/shibboleth
[root@idmt-1 shibboleth]# vi shibboleth2.xml
            -->
            <SSO entityID="urn:mace:incommon:alaska.edu">
              SAML2 SAML1
            </SSO>

            <!-- SAML and local-only logout. -->
            <Logout>SAML2 Local</Logout>

        <!-- Example of locally maintained metadata. -->
        <MetadataProvider type="XML" file="idp-metadata.xml"/>
:wq!
[root@idmt-1 shibboleth]# shibd -t
overall configuration is loadable, check console for non-fatal problems
}}}
  * Windows: TBD
Option 2 (preferred): rely on !InCommon metadata:

Comment out the locally maintained metadata section in shibboleth2.xml and include the following:
{{{
	<MetadataProvider type="XML" uri="http://md.incommon.org/InCommon/InCommon-metadata.xml" backingFilePath="federation-metadata.xml" reloadInterval="7200">
            <MetadataFilter type="RequireValidUntil" maxValidityInterval="2419200"/>
            <MetadataFilter type="Signature" certificate="incommon.pem"/>
            <MetadataFilter type="Whitelist">
		<Include>urn:mace:incommon:alaska.edu</Include>
	    </MetadataFilter>
        </MetadataProvider>
}}}
This configuration checks the signature of the InCommon metadata, so you need to download and install that long-lived certificate.  The process is detailed below (from https://spaces.internet2.edu/display/InCFederation/Metadata+Signing+Certificate).  Once you have downloaded and verified the fingerprint of that certificate, save it in the same directory as shibboleth2.xml under the name incommon.pem.
{{{
Metadata Signing Certificate
The InCommon metadata signing certificate is a long-lived, self-signed certificate containing the public key corresponding to the private metadata signing key. Important details about the metadata signing certificate are shown on this authoritative web page:

https://ops.incommon.org/inc_md_cert.html
Note in particular the certificate fingerprints listed at the top of that page. InCommon Operations certifies that these are the actual fingerprints of the metadata signing certificate. Accept no substitute!

Bootstrapping Trust
To ensure the security of your metadata refresh process, you must verify the XML signature on each and every metadata aggregate you consume. To do that, you need an authentic copy of the metadata signing certificate. The certificate must be obtained securely since all subsequent operations depend on it.

To obtain an authentic copy of the metadata signing certificate, perform the following steps:

Download a copy of the metadata signing certificate via a secure channel
Compute the SHA-1 and SHA-256 fingerprints of the metadata signing certificate
Compare the computed fingerprints to the actual fingerprints
The latter two steps guarantee the integrity of the metadata signing certificate so obtained.

	Check the integrity of the metadata signing certificate!
To bootstrap your trusted metadata process, you MUST check the integrity of the metadata signing certificate configured into that process. It is not sufficient to fetch the certificate via a TLS-protected HTTPS connection.
You may check the integrity of the downloaded certificate in a variety of ways. For example, on a GNU/Linux system, you could use curl and openssl to perform the first two steps of the bootstrap process:

# Step 1: Download a copy of the metadata signing certificate via a secure channel
$ MD_CERT_LOCATION=https://ds.incommon.org/certs/inc-md-cert.pem
$ MD_CERT_PATH=/path/to/inc-md-cert.pem
$ /usr/bin/curl --silent $MD_CERT_LOCATION > $MD_CERT_PATH
 
# Step 2: Compute the SHA-1 and SHA-256 fingerprints of the metadata signing certificate
$ /bin/cat $MD_CERT_PATH | /usr/bin/openssl x509 -sha1 -noout -fingerprint
SHA1 Fingerprint=7D:B4:BB:28:D3:D5:C8:52:E0:80:B3:62:43:2A:AF:34:B2:A6:0E:DD
$ /bin/cat $MD_CERT_PATH | /usr/bin/openssl x509 -sha256 -noout -fingerprint
SHA256 Fingerprint=2F:9D:9A:A1:FE:D1:92:F0:64:A8:C6:31:5D:39:FA:CF:1E:08:84:0D:27:21:F3:31:B1:70:A5:2B:88:81:9F:5B
	On a Windows system
The Shibboleth SP on Windows ships with its own curl and openssl utilities.
Step 3: The final step is to compare the computed fingerprints to the actual fingerprints. The latter are shown on this authoritative web page:

https://ops.incommon.org/inc_md_cert.html
If the computed fingerprints match the actual fingerprints, you are done. You may now safely use the certificate to verify the signature on the metadata file.
}}}

2.3 Set SP to find an IdP; within shibboleth2.xml

A simple case is for your service to rely on (just) the UA IdP; that is, the SP will redirect users' browser to the UA IdP for authentication and attributes:
{{{
            <SSO entityID="urn:mace:incommon:alaska.edu"
                 discoveryProtocol="SAMLDS" discoveryURL="https://ds.example.org/DS/WAYF">
              SAML2 SAML1
            </SSO>


}}}

Setting up for federated access to your service - allowing users to choose from among a list of different Identity Providers - is outside the scope of this document.
See https://wiki.shibboleth.net/confluence/display/SHIB2/DiscoveryService

 3. Setup EntityID for SP. Note the entityID for the SP is _NOT_ a URL. It is a unique string that identifies your SP and is usually based off of the hostname of the system. It may also be a CNAME for the system.


 * Linux example using curl:
{{{
[root@idmt-1 shibboleth]# hostname
idmt-1.alaska.edu
[root@idmt-1 shibboleth]# pwd
/etc/shibboleth
[root@idmt-1 shibboleth]# vi shibboleth2.xml
    <!-- The ApplicationDefaults element is where most of Shibboleth's SAML bits are defined. -->
    <ApplicationDefaults entityID="{entityid of your service}"
                         REMOTE_USER="eppn persistent-id targeted-id">

        <!--
:wq!
[root@idmt-1 shibboleth]# shibd -t
overall configuration is loadable, check console for non-fatal problems
}}}
  * Windows: TBD
 4. Start Apache/IIS and Shibd and check function.
  * Linux:
{{{
[root@idmt-1 shibboleth]# service httpd start
Starting httpd:                                            [  OK  ]
[root@idmt-1 shibboleth]# service shibd start
Starting shibd:                                            [  OK  ]
[root@idmt-1 shibboleth]# curl -k https://localhost/Shibboleth.sso/Status | xmllint --format - | grep -C 3 "<Status>"
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100  4889  100  4889    0     0   194k      0 --:--:-- --:--:-- --:--:-- 4774k
      </ds:X509Data>
    </ds:KeyInfo>
  </md:KeyDescriptor>
  <Status>
    <OK/>
  </Status>
</StatusHandler>
}}}
  * Windows: TBD
 5. Generate SP metadata.

  * Linux using metagen.sh; include attributes of your Service SP in the metagen command for a better metadata description of the service:[[br]]
 man page: http://manpages.ubuntu.com/manpages/lucid/man1/shib-metagen.1.html
{{{
 ./metagen.sh 
     -c sp-cert.pem 
     -h yourhosthostname.alaska.edu 
     -o "Your Human-friendly Organization Name" 
     -u "Your Organization URL"
     -a "AdminContactFirst/Last/Email" 
     -s "SupportContactFirst/Last/Email" 
  > sp-metadata.xml
}}}

  * Linux alternative using curl, which will require additional manual editing of metadata to include UI elements and to remove un-needed end points:
{{{
[root@idmt-1 shibboleth]# curl -k https://$(hostname)/Shibboleth.sso/Metadata > $(hostname -s)-metadata.xml
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100  3807  100  3807    0     0   169k      0 --:--:-- --:--:-- --:--:-- 3717k
[root@idmt-1 shibboleth]# xmllint --format $(hostname -s)-metadata.xml 
....

}}}
  * Windows: TBD

 * Add a display name of the service to be shown on the Shibboleth login page if that login page is triggered by a request to login at your service:
{{{
<md:Extensions>
<mdui:UIInfo xmlns:mdui="urn:oasis:names:tc:SAML:metadata:ui">
        <mdui:DisplayName xml:lang="en">Human-friendly Service Name</mdui:DisplayName>
</mdui:UIInfo>
</md:Extensions>
}}}
 * A sample relatively simple sp-metadata file to illustrate and show added UI extensions:
{{{
<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" xmlns:ds="http://www.w3.org/2000/09/xmldsig#" entityID="https://staffcouncil.uaf.edu/shibboleth">
  <md:SPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol urn:oasis:names:tc:SAML:1.1:protocol">
<md:Extensions>
   <mdui:UIInfo xmlns:mdui="urn:oasis:names:tc:SAML:metadata:ui">
        <mdui:DisplayName xml:lang="en">UAF Staff Council Services</mdui:DisplayName>
   </mdui:UIInfo>
</md:Extensions>
    <md:KeyDescriptor>
      <ds:KeyInfo>
        <ds:X509Data>
          <ds:X509Certificate>
...
...
          </ds:X509Certificate>
        </ds:X509Data>
      </ds:KeyInfo>
    </md:KeyDescriptor>
    <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://staffcouncil.uaf.edu/Shibboleth.sso/SAML2/POST" index="1"/>
    <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST-SimpleSign" Location="https://staffcouncil.uaf.edu/Shibboleth.sso/SAML2/POST-SimpleSign" index="2"/>
    <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:PAOS" Location="https://staffcouncil.uaf.edu/Shibboleth.sso/SAML2/ECP" index="3"/>
    <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:1.0:profiles:browser-post" Location="https://staffcouncil.uaf.edu/Shibboleth.sso/SAML/POST" index="4"/>
  </md:SPSSODescriptor>
  <md:Organization>
    <md:OrganizationName xml:lang="en">UAF Staff Council</md:OrganizationName>
    <md:OrganizationDisplayName xml:lang="en">UAF Staff Council</md:OrganizationDisplayName>
    <md:OrganizationURL xml:lang="en">https://staffcouncil.uaf.edu/shibboleth</md:OrganizationURL>
  </md:Organization>
  <md:ContactPerson contactType="administrative">
    <md:GivenName>UAF Staff</md:GivenName>
    <md:SurName>Council</md:SurName>
    <md:EmailAddress>uaf-staff-council@alaska.edu</md:EmailAddress>
  </md:ContactPerson>
  <md:ContactPerson contactType="support">
    <md:GivenName>Phil</md:GivenName>
    <md:SurName>Jacobs</md:SurName>
    <md:EmailAddress>ptjacobs@alaska.edu</md:EmailAddress>
  </md:ContactPerson>
</md:EntityDescriptor>

}}}
3. Email SP metadata to iam@alaska.edu and request integration with UA IdP. Once the metadata is registered with the UA IdP integration can be tested at the https://idmt-1.alaska.edu/secure test URL that is configured by default with most installations.
4. Decide which attributes your application will need to authorize access then email iam@alaska.edu and request those attributes be released to your SP from the UA IdP.