Very Basic Overview

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

In the present case, the SP consists of the Shibboleth SP version 3 software. See https://shibboleth.atlassian.net/wiki/spaces/SP3/overview .

Upon successful login at the idP, the 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 request 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 Instructions for Adjusting Configuration and Getting Going

The following instructions are meant to get you going as quickly as possible. If you want a better understanding of what's going on, go to the next section of this document.

There are eight configuration files that need to go on the host. They will be installed upon installing Shibboleth SP, and they need to be overlayed/modified to reflect your installation, as follows:

Filename	Location on SP	Notes
idp-metadata.xml	/etc/shibboleth/idp-metadata.xml	A copy of your IdP's metadata.
key pair	/etc/shibboleth/sp-key.pem /etc/shibboleth/sp-cert.pem	Create a key pair; include the certificate (sp-cert.pem) in sp-metadata.xml
sp-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 In either case, populate the public key certificate with yours
attribute-map.xml	/etc/shibboleth/attribute-map.xml	Specifies the user-information that your IdP sends to the SP upon login
sp.conf	/etc/httpd/conf.d/sp.conf	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
shibboleth2.xml	/etc/shibboleth/shibboleth2.xml	Specifies many aspects of your SP
shrine.conf	/opt/shrine/tomcat/lib/shrine.conf	replace "shrine-sso-node01" with your own node name add the the shrine element: queryEntryPoint { authenticationType = "sso" }

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

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, i.e. the Shibboleth documentation says that ideally ShibUseEnvironment should be On (resulting in request attributes) and ShibUseHeaders should be Off. However the recommended setup requires proxying to Tomcat using the AJP protocol, which we are not using because it is being phased out of Tomcat (so we are proxying using the HTTP protocol). Also, see https://shibboleth.atlassian.net/wiki/spaces/SHIB2/pages/2577072327/NativeSPApacheConfig.

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 (see Apache Configuration above). 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 for this environment REMOTE_USER will be set to the value of "ecommonsid". 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"
    >

Sessions configuration documentation is available at https://shibboleth.atlassian.net/wiki/spaces/SP3/pages/2065334342/Sessions


<Sessions lifetime="28800" timeout="3600" relayState="ss:mem" checkAddress="false" handlerSSL="true" cookieProps="https">

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="/Status"/>

Setting the session diagnostic service to "/Shibboleth.sso/Session"

<Handler type="Session" Location="/Session" showAttributeValues="true" contentType="application/json" />

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 the file it points to unchanged:

<AttributeResolver type="Query" subjectMatch="true"/>
<AttributeFilter type="XML" validate="true" path="attribute-policy.xml"/>

This points to the key pair we created above:

<CredentialResolver type="File" key="/etc/shibboleth/sp-key.pem" certificate="/etc/shibboleth/sp-cert.pem"/>

We left this and the file it points to unchanged:

<SecurityPolicyProvider type="XML" validate="true" path="security-policy.xml"/>
<ProtocolProvider type="XML" validate="true" reloadChanges="false" path="protocols.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

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

    
    <!--    The 'name' attributes need to match exactly what your IdP sends in 
            its response to your (successful) AuthnRequest
            
            E.g.
    -->
    <Attribute name="ecommonsId" id="ecommonsid"/>
    <Attribute name="Email" id="email"/>
    <Attribute name="Firstname" id="firstname"/>
    <Attribute name="Lastname" id="lastname"/>

</Attributes>

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

----------------------------------------------------------------
How to configure Tomcat to only listen to 127.0.0.1?
The environment is Ubuntu 10.04.1 LTS running Tomcat 6 and Apache 2.2 from the repos. Apache is configured to proxy requests to Tomcat, so I really want to turn off Tomcat listening to requests on
2:52

<Connector address="127.0.0.1" port="8080" protocol="HTTP/1.1"
----------------------------------------------------------------

Set up a listener on port 8080
Accessing data received from the idP (Request Headers)

Shrine Application Configuration

shrine.conf

File sp-metadata.xml


<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" xmlns:ds="http://www.w3.org/2000/09/xmldsig#" entityID="https://shrine-sso-node01.catalyst.harvard.edu">
<md:SPSSODescriptor AuthnRequestsSigned="true" WantAssertionsSigned="true" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
<md:KeyDescriptor>
<ds:KeyInfo>
<ds:X509Data>

<ds:X509Certificate>MIIC6zCCAdOgAwIBAgIJAOy0nki3WAOVMA0GCSqGSIb3DQEBBQUAMBcxFTATBgNV
BAMTDDc5OTQzZmVlNzg2NTAeFw0xNTEyMTEwMzAwNDJaFw0yNTEyMDgwMzAwNDJa
MBcxFTATBgNVBAMTDDc5OTQzZmVlNzg2NTCCASIwDQYJKoZIhvcNAQEBBQADggEP
ADCCAQoCggEBALPBzAz0DTn+j2YsQKfqWI+m08lP5UzwVsE9ZKzLqO3PRHZqiOBm
EaFmRrYCZCAOcJ0TXcxPGtNSo8HC4uw5/Y5lJGuI3jN7X7KB1VUQDpUSwfgOqtro
uDoVRKrsaYZTnlNV8KbZ0WQz5s4Uw6CxKRB9RZ5iQMP1fuxc8B6GSOb3x69MiY6c
1jlgVAc6rV4zGfpafacxOLM8qcYhY8u3TiSd0H+oiGEqi1mFLK8yp6FKzX8OUkQf
We49YHz6wBxFOe+/p+7ziym1rBs/lGfenEo8ziCIMmjnoo257fz00bcz9rFl1rTx
KLFfgy72xTlG72l6u+pB9VqK3YNJS52Ns5UCAwEAAaM6MDgwFwYDVR0RBBAwDoIM
Nzk5NDNmZWU3ODY1MB0GA1UdDgQWBBRiDMNPjiAMC50WWubI3PMjP45S/DANBgkq
hkiG9w0BAQUFAAOCAQEAYZM/iWgC93vAq0d98egEzvESKodxHffkDOagd4Kxt/S0
AAHsVQCmAK/9kmRhsWzR3f1KIw98q4EX7nH/K68BFrerUvaL5+fEGE9W6Ki6QdW8
bM17GQkLyRDKZzGPm/hsaG1Oxru2kDf7qSvv59aRZlZ8skrDEnx8+dZ8JKC02ZDU
ClC+xWl1UPfO2BL4tJei/siSymGpiRqznQ2JMoTFu5CUUpoxyCVz1bl9lCVceoJ9
FaL38knS0p5DnXcm+I8wqNEVGLDPbDalBQryhJT9fIMm1/B85gB3AWAvcu9PPfHK
lQQUhxyEXTBJx3luLlpIjoloFKIute9K7pE5qAENjg== </ds:X509Certificate>
</ds:X509Data>
</ds:KeyInfo>
</md:KeyDescriptor>


<md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://shrine-sso-node01.catalyst.harvard.edu/Shibboleth.sso/SAML2/POST" index="1"/>
</md:SPSSODescriptor>
</md:EntityDescriptor>

Certificate

Developer tools

SAML

Appendix: a Decent Book

Page tree

Shrine SSO Technical Documentation