The following instructions assume that Apache and Tomcat or your application server are running on the same host.
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:
Filename | Location on SP | Notes |
---|---|---|
idp-metadata.xml | /etc/shibboleth/idp-metadata.xml | A copy of your site's IdP metadata |
sp-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 |
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 miscellaneous aspects of your SP |
Each of these files needs to 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.
/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
Timeout 300
ProxyTimeout 300
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/"
# as per https://shibboleth.atlassian.net/wiki/spaces/SP3/pages/2065335062/Apache:
# "You do not have to set UseCanonicalName On, but you usually should ..."
### XH : when set to On, no longer works (???)
UseCanonicalName On
#### whitelist URLs which need to be protected by Shibboleth
<LocationMatch "/shrine-api/">
AuthType shibboleth
ShibRequestSetting requireSession 1
Require valid-user local
ShibUseEnvironment Off ## we are only using headers for now
ShibUseHeaders On
</LocationMatch>
To publish your metadata to your IdP:
DocumentRoot "/var/www/html"
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 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)
--------------------------- make it generic! ----------------------------------
<SPConfig xmlns="urn:mace:shibboleth:3.0:native:sp:config"
xmlns:conf="urn:mace:shibboleth:3.0:native:sp:config"
xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"
clockSkew="180"
allowedSchemes="https">
<!-- The ApplicationDefaults element is where most of Shibboleth's SAML bits are defined. -->
<ApplicationDefaults entityID="https://shrine-sso-node01.catalyst.harvard.edu"
REMOTE_USER="ecommonsid eppn uid persistent-id targeted-id"
signing="true"
>
<!--
Controls session lifetimes, address checks, cookie handling, and the protocol handlers.
You MUST supply an effectively unique handlerURL value for each of your applications.
The value defaults to /Shibboleth.sso, and should be a relative path, with the SP computing
a relative value based on the virtual host. Using handlerSSL="true", the default, will force
the protocol to be https. You should also set cookieProps to "https" for SSL-only sites.
Note that while we default checkAddress to "false", this has a negative impact on the
security of your site. Stealing sessions via cookie theft is much easier with this disabled.
-->
<Sessions lifetime="28800" timeout="3600" relayState="ss:mem"
checkAddress="false" handlerSSL="true" cookieProps="https">
<!--
Configures SSO for a default IdP. To allow for >1 IdP, remove
entityID property and adjust discoveryURL to point to discovery service.
(Set discoveryProtocol to "WAYF" for legacy Shibboleth WAYF support.)
You can also override entityID on /Login query string, or in RequestMap/htaccess.
-->
<SSO entityID="http://sso.med.harvard.edu/adfs/services/trust">
SAML2
</SSO>
<!-- SAML and local-only logout. -->
<!-- <Logout>SAML2 Local</Logout>-->
<Logout>Local</Logout>
<!-- Extension service that generates "approximate" metadata based on SP configuration. -->
<Handler type="MetadataGenerator" Location="/Metadata" signing="false"/>
<!-- Status reporting service. -->
<!-- <Handler type="Status" Location="/Status" acl="127.0.0.1 ::1"/>-->
<Handler type="Status" Location="/Status"/>
<!-- Session diagnostic service. -->
<Handler type="Session" Location="/Session" showAttributeValues="true"
contentType="application/json"
/>
</Sessions>
<!--
Allows overriding of error template information/filenames. You can
also add attributes with values that can be plugged into the templates.
-->
<Errors supportContact="admin@shrine-docker"
helpLocation="/about.html"
styleSheet="/shibboleth-sp/main.css"/>
<!-- Example of remotely supplied batch of signed metadata. -->
<!--
<MetadataProvider type="XML" validate="true"
url="http://federation.org/federation-metadata.xml"
backingFilePath="federation-metadata.xml" reloadInterval="7200">
<MetadataFilter type="RequireValidUntil" maxValidityInterval="2419200"/>
<MetadataFilter type="Signature" certificate="fedsigner.pem"/>
<DiscoveryFilter type="Blacklist" matcher="EntityAttributes" trimTags="true"
attributeName="http://macedir.org/entity-category"
attributeNameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"
attributeValue="http://refeds.org/category/hide-from-discovery" />
</MetadataProvider>
-->
<!-- Example of locally maintained metadata. -->
<!--
<MetadataProvider type="XML" validate="true" path="partner-metadata.xml"/>
-->
<MetadataProvider type="XML" validate="true" path="idp-metadata.xml"/>
<!-- Map to extract attributes from SAML assertions. -->
<AttributeExtractor type="XML" validate="true" reloadChanges="false" path="attribute-map.xml"/>
<!-- Use a SAML query if no attributes are supplied during SSO. -->
<AttributeResolver type="Query" subjectMatch="true"/>
<!-- Default filtering policy for recognized attributes, lets other data pass. -->
<AttributeFilter type="XML" validate="true" path="attribute-policy.xml"/>
<!-- Simple file-based resolver for using a single keypair. -->
<CredentialResolver type="File" key="/etc/shibboleth/sp-key.pem" certificate="/etc/shibboleth/sp-cert.pem"/>
</ApplicationDefaults>
<!-- Policies that determine how to process and authenticate runtime messages. -->
<SecurityPolicyProvider type="XML" validate="true" path="security-policy.xml"/>
<!-- Low-level configuration about protocols and bindings available for use. -->
<ProtocolProvider type="XML" validate="true" reloadChanges="false" path="protocols.xml"/>
</SPConfig>
------------------------------------------------
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
<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
<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
Get from your IdP (Probably do not (need to) distribute ours)
<!-- 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 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
----------------------------------------------------------------
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"
----------------------------------------------------------------
shibboleth2.xml
attribute-map.xml
sp.conf
Certificate
Appendix: a Decent Book