This appendix is designed to guide system admins installing Single-Sign-On (SSO) for Shrine (using Shibboleth).

Very Basic Overview of SSO

IdP (Identity Provider): A web-based system that can authenticate a user on behalf of another system called a SP (for Service Provider).

Installation Layout

The following instructions assume that Apache and Tomcat or your application server are running on the same host.

Quick Shibboleth Instructions for Adjusting Configuration 

For Shibboleth, we are using SP-3. See https://shibboleth.atlassian.net/wiki/spaces/SP3/overview .

Consult your local Shibboleth experts for guidance.

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 

...

To be shared dynamically with your site's Shibboleth IdP.

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

...

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 Considerations

Apache Configuration

/etc/httpd/conf.d/sp.conf

ServerName should be set to your SP host's address/name, for instance my-shibboleth-sp-host.net:

ServerName my-shibboleth-sp-host.net

...

In this implementation of SSO, the SP consists of the Shibboleth SP version 3 software. See

https://shibboleth.atlassian.net/wiki/spaces/SP3/

...

To publish your metadata to your IdP:

• Email to them, or
• Place your metadata in a file called sp-metadata.xml in a folder configured in .../httpd.conf, e.g.

DocumentRoot "/var/www/html"

• And then in sp.conf .........

The following tells Apache to use Shibboleth for authentication of any URL starting with "shrine-api":

#### whitelist URLs which need to be protected by Shibboleth

<LocationMatch "/shrine-api/">

  AuthType shibboleth

  ShibRequestSetting requireSession 1

  Require valid-user local

The following tells Shibboleth to make the attributes it collects from the idP available as request headers in Apache. This is the opposite of what is recommended. However the recommended (and default) setup (ShibUseEnvironment=On and ShibUseHeaders=Off) requires proxying to Tomcat using the AJP protocol, which we are not using (we are proxying using the HTTP protocol).

  # as per https://shibboleth.atlassian.net/wiki/spaces/SHIB2/pages/2577072327/NativeSPApacheConfig,

  # ShibUseEnvironment is strongly favored over ShibUseHeaders

  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

--------------------------- make it generic! ----------------------------------

...

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

Near the top of the file in the ApplicationDefaults element, we set

• 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)
• The sessionHook is the URL of code running on Tomcat. It will run before Shibboleth redirects the user to the wanted URL after the user authenticates. More on this later.

<ApplicationDefaults entityID="https://shrine-sso-node01.catalyst.harvard.edu"
REMOTE_USER="ecommonsid eppn uid persistent-id targeted-id"
sessionHook="/shrine-api/sso/rest/authentication/consume"
signing="true"
>

Within the <ApplicationDefaults><Sessions> element

• entityID is the URL of the idP to use for authentication
• We talk only SAML2 protocol

<SSO entityID="http://sso.med.harvard.edu/adfs/services/trust">
SAML2
</SSO>

Set logout to only local:

<Logout>Local</Logout>

Set status URL to

https://shrine-sso-node01.catalyst.harvard.edu/Shibboleth.sso/Status

And session URL to:

https://shrine-sso-node01.catalyst.harvard.edu/Shibboleth.sso/Session

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">

...

overview .

Upon successful login at the IdP, the IdP will send information about the user back to the SP as "attributes".

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).

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/SP3/pages/2065335529/GettingStarted

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

Tomcat Configuration

Tomcat should accept requests on port 8080 only from localhost. Something like?

<Connector port="8080" protocol="HTTP/1.1"

               connectionTimeout="20000"

               redirectPort="6443" />

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

Serving Metadata

Certificate

Developer tools

• SAML 

Appendix: a Decent Book