Page History

...

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.
Please note that in mod_shib the "ShibUseHeaders" must be set to "On", as DSpace currently receives authentication information through HTTP headers.
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

...

The Lazy Session method is preferable for most DSpace installations, as you generally usually want to provide public access to (most) DSpace content, while restricting access restricting to only particular areas (e.g. administration UI/tools, private Items, etc.). When Active Sessions are enabled , this will essentially access restrict your entire DSpace instancesite will be access restricted. 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 as anonymous access will not be allowed).

...

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

The Shibboleth setting "ShibUseHeaders" must is no longer required to be set to "On", as DSpace currently receives authentication information through HTTP headers.will correctly utilize attributes instead of headers.
- When "ShibUseHeaders" is set to "Off" (which is recommended in the mod_shib documentation), proper configuration of Apache to pass attributes to Tomcat (via either mod_jk or mod_proxy) can be a bit tricky, SWITCH has some great documentation on exactly what you need to do. We will eventually paraphrase/summarize this documentation here, but for now, the SWITCH page will have to do.
When initially setting up Apache & mod_shibWhen initially setting up Apache & mod_shib, https://www.testshib.org/ provides 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. It acts as a "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/

Code Block

##### WhileSAMPLE this MOD_SHIB CONFIGURATION FOR APACHE2 (it may require local modifications based on your Apache setup) ####
# While this sample VirtualHost is for HTTPS requests (recommended for Shibboleth, obviously), 
# you may also need/want to create one for HTTP (*:80)
<VirtualHost *:443>
   ...
   # PLEASE NOTE: We have omitted many Apache settings (ServerName, LogLevel, SSLCertificateFile, etc) 
   # which you may need/want to add to your VirtualHost
   
   # As long as Shibboleth module is installed, Enableenable all Shibboleth/mod_shib 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 ShibShibboleth. 
       # This section turns on Shibboleth "Lazy Session". Also ensures that once they have authenticated
       # (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, your 
         # DSpace Service Provider, then you may need to tell Apache which "id" to redirect Shib requests to. 
         # Just uncomment this and change the value "my-dspace-id" to the associated @id attribute value.
         #ShibRequestSetting applicationId my-dspace-id
       </Location>

       # If a user attempts to access the DSpace shibboleth login page, force them to authenticate via Shib
       <Location "/shibboleth-login">
         AuthType shibboleth
         ShibRequireSession On
         # DSpacePlease requiresnote usingthat Shibbolethsetting Headers. So this MUST be ShibUseHeaders to "On"
 is a potential security  risk. 
   ShibUseHeaders On
     # You may wish require valid-user
       </Location>
     to set it to "Off". See the mod_shib docs for details about this setting:
    
       # Ensure /Shibboleth.sso path (in Apache) can be accessed
       # By default it may be inaccessible if your Apache security is tight.
https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPApacheConfig#NativeSPApacheConfig-AuthConfigOptions
         # Here's a good guide to configuring Apache + Tomcat when this setting is "Off": 
         <Location "/Shibboleth.sso"># https://www.switch.ch/de/aai/support/serviceproviders/sp-access-rules.html#javaapplications 
         OrderShibUseHeaders deny,allowOn
         Allow from allrequire valid-user
       </Location>
  # Also ensure Shibboleth/mod_shib responds to this path
       # Ensure SetHandler shib
       </Location>
 
/Shibboleth.sso path (in Apache) can be accessed
       # By #default Finally,it optionallymay ensurebe thatinaccessible requestsif to /Shibboleth.sso are NOT redirected your Apache security is tight.
       # to Tomcat (as they will be handled by mod_shib instead).<Location "/Shibboleth.sso">
         Order deny,allow
       # NOTE: THISAllow SETTINGfrom ISall
 LIKELY ONLY NEEDED IF YOU ARE USING PROXYPASS TO REDIRECT# Also ensure Shibboleth/mod_shib responds to this path
       # ALL REQUESTS TO TOMCAT (e.g. ProxyPass / ajp://localhost:8080/)  SetHandler shib
       </Location>
 
       # ProxyPass Finally, you may need to ensure requests to /Shibboleth.sso !
are NOT redirected 
       </IfModule>
 
   ...
 
</VirtualHost># to Tomcat (as they need to be handled by mod_shib instead).
       # NOTE: THIS SETTING IS LIKELY ONLY NEEDED IF YOU ARE USING mod_proxy TO REDIRECT
       # ALL REQUESTS TO TOMCAT (e.g. ProxyPass / ajp://localhost:8009/)
       # ProxyPass /Shibboleth.sso !
   </IfModule>
 
   ...
 
</VirtualHost>

DSpace Shibboleth Configuration Options

...

Used when a netid or email headers are not available should Shibboleth authentication fall back to using Tomcat's remote user feature? Generally this is not recommended. See the "Authentication Methods" section above.

Configuration File:

[dspace]/config/modules/authentication-shibboleth.cfg

Property:

lazysession

Example Value:

lazysession = true

Informational Note:

Whether to use lazy sessions or active sessions. For more DSpace instances, you will likely want to use lazy sessions. Active sessions will force every user to authenticate via Shibboleth before they can access your DSpace (essentially resulting in a "dark archive").

Property:

lazysession.loginurl

Example Value:

lazysession.loginurl = /Shibboleth.sso/Login

Informational Note:

The url to start a shibboleth session (only for lazy sessions). Generally this setting will be "/Shibboleth.sso/Login"

Property:

lazysession.secure

Example Value:

lazysession.secure = true

Informational Note:

Force HTTPS when authenticating (only for lazy sessions). Generally this is recommended to be "true".

Property:

netid-header

Example Value:

netid-header = SHIB-NETID

Informational Note:

The HTTP header where shibboleth will supply a user's NetID. This HTTP header should be specified as an Attribute within your Shibboleth "attribute-map.xml" configuration file.

Property:

email-header

Example Value:

email-header = SHIB-MAIL

Informational Note:

The HTTP header where the shibboleth will supply a user's email address. This HTTP header should be specified as an Attribute within your Shibboleth "attribute-map.xml" configuration file.

Property:

email-header-use-tomcat-remote-user

Example Value:

email-header = SHIB-MAIL-use-tomcat-remote-user = false

Informational Note:

The HTTP header where the shibboleth will supply a user's email address. This HTTP header should be specified as an Attribute within your Shibboleth "attribute-map.xml" configuration file.

Property:

email-use-tomcat-remote-user

Example Value:

email-use-tomcat-remote-user = false

Used when a netid or email headers are not available should Shibboleth authentication fall back to using Tomcat's remote user feature? Generally this is not recommended. See the "Authentication Methods" section above.

Property:

reconvert.attributes

Example Value reconvert.attributes = false

Informational Note:

Shibboleth attributes are by default UTF-8 encoded. Some servlet container automatically converts the attributes from ISO-8859-1 (latin-1) to UTF-8. As the attributes already were UTF-8 encoded it may be necessary to reconvert them. If you set this property true DSpace converts all shibboleth attributes retrieved from the servlet container from UTF-8 to ISO-8859-1 and uses the result as if it were UTF-8. This procedure restores the shibboleth attributes if the servlet container wrongly converted them from ISO-8859-1 to UTF-8. Set this true, if you notice character encoding problems within shibboleth attributes.

This property was added with DSpace version 4.2 and is not available in DSpace versions before.

Informational Note:

Property:

autoregister

Example Value:

autoregister = true

Informational Note:

Should we allow new users to be registered automatically?

Property:

sword.compatabilitycompatibility

Example Value:

sword.compatability compatibility = truefalse

Informational Note:

Sword compatability SWORD compatibility will allow this authentication method to work when using swordSWORD. Sort SWORD relies on username and password based authentication and is entirely incapable of supporting shibboleth. This option allows you to authenticate username and passwords for sword SWORD sessions with out adding another authentication method onto the stack. You will need to ensure that a user has a password. One way to do that is to create the user via the create-administrator command line command and then edit their permissions.

WARNING: If you enable this option while ALSO having "PasswordAuthentication" enabled, then you should ensure that "PasswordAuthentication" is listed prior to "ShibAuthentication" in your authentication.cfg file. Otherwise, ShibAuthentication will be used to authenticate all of your users INSTEAD OF PasswordAuthentication.

Property:

firstname-header

Example Value:

firstname-header = SHIB_GIVENNAME

Informational Note:

The HTTP header where the shibboleth will supply a user's given name. This HTTP header should be specified as an Attribute within your Shibboleth "attribute-map.xml" configuration file.

Property:

lastname-header

Example Value:

lastname-header = SHIB_SN

Informational Note:

The HTTP header where the shibboleth will supply a user's surname. This HTTP header should be specified as an Attribute within your Shibboleth "attribute-map.xml" configuration file.

Property:

eperson.metadata

Example Value:

Code Block
eperson.metadata = \ SHIB-telephone => phone, \ SHIB-cn => cn

Informational Note:

Additional user attributes mapping, multiple attributes may be stored for each user. The left side is the Shibboleth-based metadata Header and the right side is the eperson metadata field to map the attribute to.

Property:

eperson.metadata.autocreate

Example Value:

eperson.metadata.autocreate = true

Informational Note:

If the eperson metadata field is not found, should it be automatically created?

Property:

role-header

Example Value:

role-header = SHIB_SCOPED_AFFILIATION

Informational Note:

The shibboleth header to do role-based mappings (see section on roll based mapping section above)

Property:

role-header.ignore-scope

Example Value:

role-header.ignore-scope = true

Informational Note:

Weather to ignore the attribute's scope (everything after the @ sign for scoped attributes)

Property:

role-header.ignore-value

Example Value:

role-header.ignore-value = false

Informational Note:

Weather to ignore the attribute's value (everything before the @ sign for scoped attributes)

Property:

role.[affiliation-attribute]

Example Value:

Code Block
role.faculty = Faculty, Member \ role.staff = Staff, Member \ role.student = Students, Member

Informational Note:

Mapping of affiliation values to DSpace groups. See the "Role-based Groups" section above for more info.

...

All Versions

DSpace Documentation

Page tree

Versions Compared

Old Version 10

New Version Current

Key

DSpace Shibboleth Configuration Options