Page History

...

Shibboleth is a distributed authentication system for securely authenticating users and passing attributes about the user from one or more identity providers. In the Shibboleth terminology DSpace is a Service Provider which receives authentication information and then based upon that provides a service to the user. With To use Shibboleth, DSpace will require requires that you use Apache installed with the mod_shib module acting as a proxy for all HTTP requests for your servlet container (typically Tomcat). DSpace will receive authentication information from the mod_shib module through HTTP headers.

See for more information on installing and configuring a Shibboleth Service Provider: https://wiki.shibboleth.net/confluence/display/SHIB2/Installation

Sessions:

...

Before DSpace will work with Shibboleth, you must have the following:

1. An Apache web server with the "mod_shib" module installed. As mentioned, this mod_shib module acts as a proxy for all HTTP requests for your servlet container (typically Tomcat).  Any requests to DSpace that require authentication via Shibboleth should be redirected to 'shibd' (the shibboleth daemon) by this "mod_shib" module.  Details on installing/configuring mod_shib in Apache are available at: https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPApacheConfig   We also have a sample Apache + mod_shib configuration provided below.
   1. Please note that in mod_shib the "ShibUseHeaders" must be set to "On", as DSpace currently receives authentication information through HTTP headers.
2. An external Shibboleth Idp (Identity Provider).  Using mod_shib, DSpace will only act as a Shibboleth SP (Service Provider). The actual Shibboleth Authentication & Identity information must be provided by an external IdP.  If you are using Shibboleth at your institution already, then there already should be a Shibboleth IdP available. More information about Shibboleth IdPs versus SPs is available at: https://wiki.shibboleth.net/confluence/display/SHIB2/UnderstandingShibboleth

For more information on installing and configuring a Shibboleth Service Provider see: https://wiki.shibboleth.net/confluence/display/SHIB2/Installation

• Please note that "ShibUseHeaders" must be set to "On", as DSpace currently receives authentication information through HTTP headers.

Note about Active vs Lazy Sessions:

When configuring your Shibboleth Service Provider there are two Shibboleth paradigms you may use: Active or Lazy Sessions. Active sessions is where the mod_shib module is configured to product an entire URL space. No one will be able to access that URL without first authenticating with Shibboleth. Using this method you will need to configure shibboleth to protect the URL: "/shibboleth-login". The alternative, Lazy Session does not protect any specific URL. Instead Apache will allow access to any URL, and when the application wants to it may initiate an authenticated session.

The Lazy Session method is preferable for most DSpace installations, as you generally want to provide public access to (most) DSpace content, while access restricting only particular areas (e.g. administration UI/tools).  When Active Sessions are enabled, this will essentially access restrict your entire DSpace instance.  In other words, when using Active Sesssions, Shibboleth will require everyone to first authenticate before they can access any part of your repository (which essentially results in a "dark archive", since anonymous access will not be allowed).

Apache "mod_shib" Configuration (required)

As mentioned above, you must have Apache with the "mod_shib" module installed in order for DSpace to be able to act as a Shibboleth Service Provider (SP). The mod_shib module acts as a proxy for all HTTP requests for your servlet container (typically Tomcat).  Any requests to DSpace that require authentication via Shibboleth should be redirected to 'shibd' (the shibboleth daemon) by this "mod_shib" module.  Details on installing/configuring mod_shib in Apache are available at: https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPApacheConfig  General information about installing/configuring Shibboleth Service Providers (SPs) can be found at: https://wiki.shibboleth.net/confluence/display/SHIB2/Installation

A few extra notes/hints when configuring mod_shib & Apache:

• The "ShibUseHeaders" must be set to "On", as DSpace currently receives authentication information through HTTP headers.
• When initially setting up Apache & mod_shib, we recommend https://www.testshib.org/ as a great testing ground for your configurations. This site provides a sample/demo Shibboleth IdP (as well as a sample Shibboleth SP) which you can test against. This acts as a great "sandbox" to get your configurations working properly, before you point DSpace at your production Shibboleth IdP.

Below, we have provided a sample Apache configuration.  However, as every institution has their own specific Apache setup/configuration, it is highly likely that you will need to tweak this configuration in order to get it working properly. Again, see the official mod_shib documentation for much more detail about each of these settings: https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPApacheConfig  These configurations are meant to be added to an Apache <VirtualHost> which acts as a proxy to your Tomcat (or other servlet container) running DSpace.  More information on Apache VirtualHost settings can be found at: https://httpd.apache.org/docs/2.2/vhosts/

# While this sample VirtualHost is for HTTPS requests (recommended for Shibboleth, obviously), you may also need to create one for HTTP (*:80)
<VirtualHost *:443>
   ...
   # PLEASE NOTE: We have omitted many settings (ServerName, LogLevel, SSLCertificateFile, etc) which you may need/want to add to your VirtualHost
   
   # As long as Shibboleth module is installed, Enable all Shibboleth related settings
   <IfModule mod_shib>
       # Shibboleth recommends turning on UseCanonicalName
       # See "Prepping Apache" in https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPApacheConfig
       UseCanonicalName On


       # Most DSpace instances will want to use Shibboleth "Lazy Session", which ensures that users can access DSpace content without first
       # authenticating via Shib. 
       # This section turns on Shibboleth "Lazy Session". It also ensures that once they have authenticated with Shib
       # (by accessing /Shibboleth.sso/Login path), then their Shib session is kept alive
       <Location />
         AuthType shibboleth
         ShibRequireSession Off
         require shibboleth
         # If your "shibboleth2.xml" file specifies an <ApplicationOverride> setting for your DSpace, 
         # then you may need to tell Apache which "id" to redirect Shib requests to. Just uncomment this and change the value "my-dspace-id"
         #ShibRequestSetting applicationId my-dspace-id
       </Location>


       # If a user attempts to access the DSpace shibboleth login page, force them to authenticate via Shibboleth
       <Location "/shibboleth-login">
         AuthType shibboleth
         ShibRequireSession On
         # DSpace requires using Shibboleth Headers. So this MUST be "On"
         ShibUseHeaders On
         require valid-user
       </Location>
         
       # Ensure /Shibboleth.sso path (in Apache) can be accessed
       # By default it may be inaccessible if your Apache security is tight.
       <Location "/Shibboleth.sso">
         Order deny,allow
         Allow from all
         # Also ensure Shibboleth/mod_shib responds to this path
         SetHandler shib
       </Location>
 
       # Finally, optionally ensure that requests to /Shibboleth.sso are NOT redirected to Tomcat (as they will be handled by mod_shib instead)
       # NOTE: THIS SETTING IS ONLY NEEDED IF YOU ARE USING PROXYPASS TO REDIRECT ALL REQUESTS TO TOMCAT (e.g. ProxyPass / ajp://localhost:8080/)
       # ProxyPass /Shibboleth.sso !
   </IfModule>
 
</VirtualHost>

DSpace Configuration Options

Authentication Methods:

DSpace supports authentication using NetID, or email address. A user's NetID is a unique identifier from the IdP that identifies a particular user. The NetID can be of almost any form such as a unique integer, string, or with Shibboleth 2.0 you can use "targeted ids". You will need to coordinate with your shibboleth federation or identity provider. There are three ways to supply identity information to DSpace:

...