Overview: How it Works
Installation Layout
Apache Configuration
/etc/httpd/conf.d/sp.conf
ServerName should be set to the SP host's address/name
ServerName shrine-sso-node01.catalyst.harvard.edu
Timeout 300
ProxyTimeout 300
Set up proxy to Tomcat for URLs that start with shrine-api
ProxyIOBufferSize 65536
#### serve content from Tomcat
ProxyPassReverse "/shrine-api/" "http://127.0.0.1:8080/shrine-api/"
ProxyPass "/shrine-api/" "http://127.0.0.1:8080/shrine-api/"
Serve metadata dynamically but as though an XML file was being accessed, from Tomcat
#### serve metadata
ProxyPass "/sp-metadata.xml" "http://127.0.0.1:8080/shrine-api/sso/rest/util/sp-metadata"
as per https://shibboleth.atlassian.net/wiki/spaces/SP3/pages/2065335062/Apache
# "You do not have to set UseCanonicalName On, but you usually should ..."
UseCanonicalName On
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
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
Tomcat Configuration
- 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