Page History
This appendix is designed to guide system admins installing Single-Sign-On (SSO) for Shrine (using Shibboleth).
Very Basic Overview of SSO
idP IdP (Identity Provider): A web-based system that can authenticate a user on behalf of another system called a SP (for Service Provider).
In the present casethis implementation of SSO, the SP consists of the Shibboleth SP version 3 software. See https://shibboleth.atlassian.net/wiki/spaces/SP3/overview .
Upon successful login at the idPIdP, the idP IdP will send information about the user back to the SP as "attributes" – in the present case, at least "remote_user".
Among other things, The SP must be configured to specify which of these attributes should be passed to the shrine code (in the form of HTTP servlet request attributes and/or headers).
Installation Layout
The following instructions assume that (1) you are using Tomcat as your application server, and (2) Apache and Tomcat are running on the same host.
Ideally the following layout is used:
/opt/shrine/tomcat ← Tomcat home
/etc/shibboleth ← Shibboleth configuration files
/etc/httpd/* ← Apache configuration files
/var/www/html ← Apache static content as set in, for instance, /etc/httpd/conf/httpd.conf
Quick Shibboleth Instructions for Adjusting Configuration
The following instructions are meant to get you going as quickly as possible. If you want to understand what's going on, go to the next section of this document.
There are five configuration files that need to go on the host that is running shibd (Shibboleth SP). They will be installed upon installing Shibboleth SP, and they need to be overlayed/modified to reflect your installation, as follows:
...
/etc/shibboleth/idp-metadata.xml
...
/var/www/html/sp-metadata.xml
– if your Apache sets DocumentRoot to /var/www/html (for instance in /etc/httpd/conf/httpd.conf)
...
To be shared dynamically with your site's Shibboleth IdP (i.e. make it available at a given URL and share that URL with your idP's maintainers/admins)
Or omit from the SP, and instead email it to the IdP admins
...
Tells Apache to require Shibboleth login for Shrine Urls (/shrine-api/*) .
Tomcat should open port 8080 only to localhost, and should reside on the same host as your SP
...
shrine.conf
Each of these files needs to be adjusted to the particulars of your site, your requirements.
You can search for the marker: 'ADJUST_FOR_YOUR_SITE' in those files for indications of what / where you need to edit.
More-Detailed Discussion of Shibboleth, Apache, and Tomcat Configuration
Here we discuss key items in the various configuration files; not necessarily the items that need to be modified but those that deserve an explanation.
Apache Configuration
/etc/httpd/conf.d/sp.conf
ServerName should be set to your SP host's name, for instance my-shibboleth-sp-host.net:
ServerName shrine-sso-node01.catalyst.harvard.edu
The following tells Apache to proxy all calls to a URL starting with "shrine-api" to http://127.0.0.1:8080/shrine-api/. Therefore we need to set up Tomcat to listen for HTTP traffic on port 8080 (see Tomcat Configuration below)
ProxyPassReverse "/shrine-api/" "http://127.0.0.1:8080/shrine-api/"
ProxyPass "/shrine-api/" "http://127.0.0.1:8080/shrine-api/"
The following tells Apache to use Shibboleth for authentication for any URL starting with "shrine-api":
<LocationMatch "/shrine-api/">
AuthType shibboleth
ShibRequestSetting requireSession 1
Require valid-user local
...
Shibboleth config Documentation
This is not required reading, but if you want to jump in depth, this is the official Shibboleth configuration documentation
...
https://shibboleth.atlassian.net/wiki/spaces/
...
...
...
ShibUseEnvironment Off
ShibUseHeaders On
</LocationMatch>
Shibboleth Configuration
Shibboleth consists of a Daemon plus an apache module. This Apache module must be configured for Shibboleth to intercept certain requests. When a request is intercepted, Shibboleth will decide whether the user (1) needs to login at the configured idP (which will present a login form to the user), or (2) is already logged in (and Shibboleth will let the request be served as if it wasn't there to intercept it)
/etc/shibboleth/shibboleth2.xml
entityID: the ID of our Service Provider (SP)
REMOTE_USER: how REMOTE_USER will be populated. Note that "ecommonsid which is specific to HMS IT, comes first, so REMOTE_USER will be set to its value. Otherwise, the first attribute name that matches an attribute returned by the idP will be used.
<ApplicationDefaults entityID="https://shrine-sso-node01.catalyst.harvard.edu"
REMOTE_USER="ecommonsid eppn uid persistent-id targeted-id"
signing="true"
>
TBD
...
Developer tools
- SAML : "SAML DevTools extension" for Chrome. These tools let you view encoded SAML content.
A Decent Book on SAML
- Stefan Rasmusson: "SAML 2.0; Designing Secure Identity Federation". Just one of many books on the topic.
Next Step:
SHRINE 4.0.0 Appendix A.1 - Installing the Software Stack
...
The following specifies the entityID of the idP to use for authentication. We also specify that we speak only SAML2 protocol.
<SSO entityID="http://sso.med.harvard.edu/adfs/services/trust">
SAML2
</SSO>
When logging out, only log out of the local Shibboleth session.
<Logout>Local</Logout>
Setting the status-reporting-service to "/Shibboleth.sso/Status"
<Handler type="Status" Location
="/Statu
s"/>
Setting the session diagnostic service to "/Shibboleth.sso/Session"
...
The idP's metadata is stored in a file call idp-metadata.xml. It should be obtained from the idP admin/maintainer.
<MetadataProvider type="XML" validate="true" path="idp-metadata.xml"/>
The attribute-map.xml file will specify which attributes are extracted from the idP's response and the name of the request headers they will be available as (to the java code). More on this file later.
<AttributeExtractor type="XML" validate="true" reloadChanges="false" path="attribute-map.xml"/>
We left this and file(s) it points to unchanged:
<AttributeResolver type="Query" subjectMatch="true"/>
<AttributeFilter type="XML" validate="true" path="attribute-policy.xml"/>
We created a key pair:
<CredentialResolver type="File" key="/etc/shibboleth/sp-key.pem" certificate="/etc/shibboleth/sp-cert.pem"/>
We left this and file(s) it points to unchanged:
...
Our Shibboleth configuration has been pared down to the essential ( ? ). If needed, for instance if we want to add functionality to our Shibboleth installation, refer to shibboleth2.xml.dist
File idp-metadata.xml
Get from your IdP (Probably do not (need to) distribute ours)
File attribute-map.xml
<Attributes xmlns="urn:mace:shibboleth:2.0:attribute-map" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
...
Tomcat Configuration
Tomcat should accept requests on port 8080, but only from localhost, and redirect to the SSL port 6443:
<Connector port="8080" protocol="HTTP/1.1"
connectionTimeout="20000"
address="127.0.0.1"
redirectPort="6443" />
Configure port 6443:
<Connector port="6443" protocol="org.apache.coyote.http11.Http11NioProtocol"
maxThreads="150" SSLEnabled="true" scheme="https" secure="true">
<SSLHostConfig clientAuth="none" sslProtocol="TLS" sslEnabledProtocols="TLSv1.3,TLSv1.2"
honorCipherOrder="true" ciphers="TLS_AES_256_GCM_SHA384,TLS_AES_128_GCM_SHA256,
TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,
TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256">
<Certificate certificateKeystoreFile="/opt/shrine/shrine.keystore"
certificateKeystorePassword="changeit"
certificateKeyAlias="*.catalyst.harvard.edu" />
</SSLHostConfig>
</Connector>
Some help might come from
...
- Set up a listener on port 8080
- Accessing data received from the idP (Request Headers)
shibboleth2.xml
attribute-map.xml
sp.conf
Shrine Application Configuration
shrine.conf
shrineSP.conf
Serving Metadata
Certificate
Developer tools
- SAML
Appendix: a Decent Book