View source for SSL, certificates and security with Shibboleth

{{New Docs}}

Basic network connections are insecure – traffic between endpoints can be snooped or altered in transit, and neither end of a connection has any reason to believe anything about the other. Shibboleth makes extensive use of public key cryptography to address this where necessary. Doing this typically requires some software, some configuration, and one or more pairs of keys and corresponding digital certificates. 

Two different approaches are used:
* data can be signed and/or encrypted, which provides a strong assurance of its integrity and where it came from and/or keeps it secure; or
* HTTP traffic can be layered over SSL (a.k.a. TLS for the purposes of this document) which protects it in transit and allows at least the client, and optionally both the client and the server, to positively identify the other end of the connection.

One thing that makes all this complicated is that public key cryptography is used for several different, independent purposes, each of which may (but need not) use a different key pair, and it's easy to get them confused. A 'Cambridge SP' perspective appears below; there is also a [https://wiki.shibboleth.net/confluence/display/SHIB/KeysAndCertificates similar description in the Shibboleth wiki] (actually about version 1 but still applicable to version 2).

==Internal SP to IdP communication==

In Shibboleth, IdPs and SPs exchange information either directly via network connections established for the purpose or via messages passed through the user's browser using HTTP redirects. In the former case an SSL protected connection is used with both ends of the connection using their keys to authenticate to the other; in the latter case the sender provides a signature made with its private key which can be verified by the receiver using the sender's certificate (the data may also be encrypted). 

The software needed to do all this is included with the Internet2 Shibboleth implementation and  configured in the shibboleth2.xml file. 

In each case, SPs and IdPs need to be able to verify the certificate offered by the other. While certificates signed by 'Global' CAs can normally be used for this purpose, current 'best practice' is to use a 'self signed' certificates and to include each entity's certificate in its metadata. This approach is supported and recommended by both the UK and Ucam federations. The standard install creates a suitable key and self-signed certificate (in the same directory as shibboleth2.xml) called sp-key.pem and sp-cert.pem and configures shibboleth2.xml to use them. Note that everything in the certificate apart from the public key itself (so expiry date, hostname, etc.) is ignored by the Shibboleth software - the certificate is just a convenient standard container for transporting the key. 

The Raven IdP's certificate is included in the federation metadata (UK or Ucam federations) that the SP is configured to download automatically. The SPs certificate is included the metadata it provides on [[SP registration | registration]].

==SP to browser communication==

Shibboleth does not actually require that communication between the user's browser and the SP be secured, though it is recommended. However if it isn't then both initial authentication and subsequent session management are vulnerable to interception and misuse by third parties. With increasing use of unsecured wireless networks (such as Lapwing and similar) much HTTP traffic is literally being broadcast for anyone to intercept. A particular problem is the resulting lack of security on the cookie used to manage sessions:
 
:"We strongly recommend use of SSL across all of a web site because Shibboleth sessions are ultimately based on HTTP cookies. Stealing cookies is much easier if they travel in the clear. The strongest authentication technology in the world is reduced to a simple cookie. This is all you've got left. Consider why you're bothering to install Shibboleth at all before going further" [https://wiki.shibboleth.net/confluence/display/SHIB/KeysAndCertificates]

Support for this SSL protection must be provided by your web server and is independent of Shibboleth. Configuration, which will be part of normal web server set up, is outside the scope of this document. 

Your server will require a private key and corresponding certificate. To avoid worrying warning messages from user's browsers ''this'' certificate must be issued by a CA that the browser trusts and in practice this means one of a small number of commercial CAs. Self-signed certificates are not suitable for this purpose, except perhaps as part of very limited testing. In Cambridge, [http://www.ucs.cam.ac.uk/tlscerts/ appropriate certificates can be obtained from University Information Services].

The UK federation requires that at least the special URLs used internally by the SP software (the so-called 'protocol endpoints', typically with URL paths starting /Shibboleth.sso/...) be SSL protected and this therefore makes SSL support mandatory for such SPs.

The Ucam federation does not require SSL support, but '''''strongly''''' recommends it. As well as the inevitable insecurity, not using SSL may result in a warning message each time a user is redirected from Raven back to the SP-protected site.

What ''is'' important is to ensure that use of http: or https: urls is consistent with the URLs registered in the SPs metadata. Getting this wrong will lead to 'Invalid assertion consumer service URL' errors when authenticating (see [[SP Metadata]]).

Sites that support SSL may want to add the

  redirectToSSL="443"

[https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPRequestMapper#NativeSPRequestMapper-Properties request mapper property] to relevant [https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPRequestMap <RequestMap>], [https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPRequestMapHost <Host>], [https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPRequestMapHostRegex <HostRegex>], [https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPRequestMapPath <Path>], [https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPRequestMapPathRegex <PathRegex>] or [https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPRequestMapQuery <Query>] elements within the [https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPRequestMapper <RequestMapper>] element to automatically force any attempt to access the site over HTTP to the corresponding requests over HTTPS. Note that you '''''can't''''' add this property to the [https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPRequestMapper <RequestMapper>] itself - adding it doesn't cause an error but it doesn't work either. Alternatively, such sites might want to use the equivalent ShibRedirectToSSL Apache directive or other web server or web application facility). Sites that do this can, and probably should, add

  cookieProps="; path=/; secure"

to the relevant [https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPSessions <Sessions>] element in shibboleth2.xml to ensure that the session cookie is not exposed over unsecured connections. Note however that setting 'cookieProps' like this without also redirecting all traffic to HTTPS can cause authentication attempts to loop between the SP and the IdP (see "Looping between SP and IdP after setting cookieProps" in [[Shibboleth FAQs]]).

==Validating metadata==

The integrity of metadata files is crucial to the correct operation of Shibboleth services, not least because they carry certificate information on which the security of the system depends. Some, though not all, federations distribute their metadata with a digital signature. This is of no use unless it is actually verified, and doing this requires a copy of a certificate corresponding to the federation key used to create the signature. Federation documentation will explain how to obtain copies of a suitable certificate and how to verify it. For the UK federation, see http://www.ukfederation.org.uk/content/Documents/Setup2SP. Ucam federation IdP metadata is not currently signed, but is distributed from an SSL-protected endpoint on a University server.