Versions Compared

Old Version 3

changes.mady.by.user Tim Donohue

Saved on

compared with

New Version 4

changes.mady.by.user Tim Donohue

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Existing Authentication Methods include

...

Configuration File:

[dspace]/config/modules/authentication.cfg

Property:

plugin.sequence.org.dspace.authenticate.AuthenticationMethod

Example Value:


Code Block
plugin.sequence.org.dspace.authenticate.AuthenticationMethod = org.dspace.authenticate.ShibAuthentication

(NOTE: This setting may be repeated to support multiple AuthenticationMethods)

Configuring Shibboleth Authentication

...

  1. An Apache web server with the "mod_shib" module installed.  As 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.
  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

...

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

  • In Debian based environments, "mod_shib" tends to be in a package named something like "libapache2-mod-shib2"
  • The Shibboleth setting "ShibUseHeaders" is no longer required to be set to "On", as DSpace 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_shib,  https://wwwsamltest.testshib.orgid/ 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.
  • You also may wish to review the Shibboleth setup in our "dspace-shibboleth" Docker setup which the development team uses for testing (and it uses https://samltest.id as the IdP).  It may provide you with good examples/hints on getting everything setup. However, keep in mind this code has not been tested in Production scenarios.

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 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
#### SAMPLE 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, enable 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 without first authenticating via Shibboleth. 
       # 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 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 pageendpoint, force them to authenticate via Shib.
       <Location "/server/api/authn/shibboleth-login">
         AuthTypeOrder shibbolethdeny,allow
         Allow from all
         AuthType shibboleth
         ShibRequireSession On
         # Please note that setting ShibUseHeaders to "On" is a potential security risk. 
         # You may wish to set it to "Off". See the mod_shib docs for details about this setting:
         # https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPApacheConfig#NativeSPApacheConfig-AuthConfigOptions
         # Here's a good guide to configuring Apache + Tomcat when this setting is "Off": 
         # https://www.switch.ch/de/aai/support/serviceproviders/sp-access-rules.html#javaapplications 
         ShibUseHeaders On
         requireRequire valid-usershibboleth
       </Location>
         
       # Ensure /Shibboleth.sso path (in Apache) can be accessed
       # By default it may be inaccessible if your Apache security is tight.
       <Location "/Shibboleth.ssoIf a user attempts to access the DSpace login endpoint, ensure Shibboleth is supported but other auth methods can be too.
       <Location "/server/api/authn/login">
          Order deny,allow
          Allow from all
         # AlsoAuthType ensure Shibboleth/mod_shib responds to this path
shibboleth
          # For DSpace, this SetHandleris shib
required to be off otherwise the  </Location>
 
       # Finally, you may need to ensure requests to /Shibboleth.sso are NOT redirected 
available auth methods will be not visible
          ShibRequireSession Off
          # toPlease Tomcatnote (asthat theysetting needShibUseHeaders to "On" beis handleda bypotential mod_shib instead)security risk.
       # NOTE: THIS SETTING# ISYou LIKELYmay ONLYwish NEEDEDto IFset YOUit ARE USINGto "Off". See the mod_proxyshib TOdocs REDIRECT
for details about this setting:
   # ALL REQUESTS TO TOMCAT (e.g. ProxyPass /# ajphttps://localhost:8009/)wiki.shibboleth.net/confluence/display/SHIB2/NativeSPApacheConfig#NativeSPApacheConfig-AuthConfigOptions
       # ProxyPass /Shibboleth.sso !
   </IfModule>
 
   ...
 
</VirtualHost>
Sample shibboleth2.xml Configuration

In addition, here's a sample "ApplicationOverride" configuration for "shibboleth2.xml". This particular "ApplicationOverride" is configured to use the Test IdP provided by http://www.testshib.org/ and is just meant as an example.  In order to enable it for testing purposes, you must specify ShibRequestSetting applicationId testshib in your Apach mod_shib configuration (see above).

Code Block
   # Here's a good guide to configuring Apache + Tomcat when this setting is "Off":
          # https://www.switch.ch/de/aai/support/serviceproviders/sp-access-rules.html#javaapplications
         <!-- *** Sample Shibboleth Settings for http://www.testshib.org/ ***     -->
 ShibUseHeaders On
       </Location>
         
   <!-- This provides a simple# sample of how you could configure  Ensure /Shibboleth.sso path (in Apache) can be accessed
       # By default -->
it may be inaccessible if your Apache security <!-- shibboleth2.xml for DSpace sites.is tight.
       <Location "/Shibboleth.sso">
         Order deny,allow
         Allow from all
         -->
# Also ensure Shibboleth/mod_shib responds to this path
 <!-- TO ENABLE: You'd need to specify "applicationId" as "testshib" inSetHandler shib
    -->
   </Location>
 
     <!-- your mod_shib# settingsFinally, e.g.you may need to ensure requests to /Shibboleth.sso are NOT redirected 
       # to Tomcat (as they need to be handled by mod_shib instead).
       # NOTE: THIS SETTING -->
IS LIKELY ONLY NEEDED IF YOU ARE  <!-- <Location />USING mod_proxy TO REDIRECT
       # ALL REQUESTS TO TOMCAT (e.g. ProxyPass /server ajp://localhost:8009/server)
       ProxyPass /Shibboleth.sso !
   </IfModule>
 
   ...


   # You will likely need Proxy settings to ensure Apache is proxying requests to Tomcat for the DSpace REST API
   # -->
The below is just an example of proxying <!--for REST API   only... It requires installing & enabling "mod_proxy" and "mod_proxy_ajp"
   ## Proxy / Forwarding Settings ##
   <Proxy *>
      AddDefaultCharset Off
      Order allow,deny
      Allow from all
   </Proxy>

   # Proxy all requests to /server to Tomcat via AJP
   ProxyPass  -->/server ajp://localhost:8009/server
   ProxyPassReverse /server ajp://localhost:8009/server

   # Optionally, also proxy Angular UI (if on same server). This requires "mod_proxy_http"
   #ProxyPass / http://localhost:4000/
   #ProxyPassReverse / http://localhost:4000/
</VirtualHost>


Sample shibboleth2.xml Configuration

In addition, here's a sample "ApplicationOverride" configuration for "shibboleth2.xml". This particular "ApplicationOverride" is configured to use the Test IdP provided by https://samltest.id/ and is just meant as an example.  In order to enable it for testing purposes, you must specify ShibRequestSetting applicationId samltest in your Apach mod_shib configuration (see above).  An additional, more detailed example is provided in our "dspace-shibboleth" Docker configurations at https://github.com/DSpace/DSpace/blob/main/dspace/src/main/docker/dspace-shibboleth/shibboleth2.xml

Code Block
        <!-- *** Sample Shibboleth Settings for  https://samltest.id/  ***     -->
        <!-- This provides a simple sample of how you could configure            -->
        <!-- shibboleth2.xml for DSpace sites.                                   -->
        <!-- TO ENABLE: You'd need to specify "applicationId" as "samltest" in   -->
        <!-- your mod_shib settings, e.g.                                        -->
        <!-- <Location />                                                        -->
        <!--     ...                                                             -->
        <!--     ShibRequestSetting applicationId samltest                       -->
        <!-- </Location>                                                         -->
        <ApplicationOverride id="samltest" entityID="http://[mydspace.edu]/shibboleth" REMOTE_USER="eppn persistent-id targeted-id">

            <!-- We'll use a TEST IdP, hosted by the awesome  https://samltest.id/  testing service. -->
     <!--     ShibRequestSetting applicationId testshib                       -->
        <!-- </Location>                                See also: https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPServiceSSO -->
            <!-- DSPACE 7 requires Shibboleth to use "SameSite=None" property for its Cookies -->
            <Sessions lifetime="28800" timeout="3600" checkAddress="false" relayState="ss:mem" handlerSSL="true" cookieProps="; path=/; SameSite=None; secure; HttpOnly">
               <SSO entityID="https://samltest.id/saml/idp">
          -->
       SAML2 <ApplicationOverride id="testshib" entityID="http://mydspace.edu/shibboleth" REMOTE_USER="principal-id">

SAML1
               <!-- We'll use a TEST IdP, hosted by the awesome http://www.testshib.org/ testing service. -->/SSO>
            </Sessions>

            <!-- See also: https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPServiceSSO -->
            <Sessions lifetime="28800" timeout="3600" checkAddress="false" relayState="ss:mem" handlerSSL="true">
Loads and trusts a metadata file that describes the IdP and how to communicate with it. -->
            <!-- By default, metadata is retrieved from the TEST IdP <SSOat entityID="https://idp.testshib.org/idp/shibboleth"/samltest.id/ -->
            <!-- and is cached in a local  SAML2 SAML1file named "samltest-metadata.xml". -->
            <!-- See  </SSO>also: https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPMetadataProvider -->
            </Sessions>

 <MetadataProvider type="XML" uri="https://samltest.id/saml/idp"
           <!-- Loads and trusts a metadata file that describes the IdP and how to communicate with it. -->
  backingFilePath="samltest-metadata.xml" reloadInterval="180000"/>
           <!-- By default, metadata is retrieved from the TEST IdP at </ApplicationOverride>


Sample attribute-map.xml Configuration (for samltest.id)

In order to use the above example for https://samltest.id/, you may also need to modify your attribute-map.xml to support their attributes. Again, a more complete example is in our "dspace-shibboleth" Docker configurations at https://github.com/DSpace/DSpace/blob/main/dspace/src/main/docker/dspace-shibboleth/attribute-map.xml

Code Block
<Attributes xmlns="urn:mace:shibboleth:2.0:attribute-map" xmlns:xsi="http://www.testshibw3.org --/2001/XMLSchema-instance">
    <!-- Custom Attributes specific to     <!samltest.id -->
 and is cached in a local file named "testshib-idp-metadata.xml". --<Attribute name="urn:oid:0.9.2342.19200300.100.1.1" id="uid"/>
    <Attribute name="urn:oid:0.9.2342.19200300.100.1.3" id="mail"/>
      <!-- See also: https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPMetadataProvider --<Attribute name="urn:oid:2.5.4.4" id="sn"/>
    <Attribute   name="urn:oid:2.16.840.1.113730.3.1.241" id="displayName"/>
    <Attribute <MetadataProvider typename="XMLurn:oid:2.5.4.20" uriid="telephoneNumber"http://www.testshib.org/metadata/testshib-providers.xml"/>
    <Attribute name="urn:oid:2.5.4.42" id="givenName"/>
                    backingFilePath="testshib-idp-metadata.xml" reloadInterval="180000<Attribute name="https://samltest.id/attributes/role" id="role"/>
  
      ...

</ApplicationOverride>Attributes>


DSpace Shibboleth Configuration Options

...

If you want to give any special privileges to LDAP users, create a stackable authentication method to automatically put people who have a netid into a special group. You might also want to give certain email addresses special privileges. Refer to the Custom Authentication Code section below for more information about how to do this.

...

Configuration File:

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

Property:

authentication-ldap.enable

Example Value:

authentication-ldap.enable = false

Informational Note:

This setting will enable or disable LDAP authentication in DSpace. With the setting off, users will be required to register and login with their email address. With this setting on, users will be able to login and register with their LDAP user ids and passwords.

Property:

authentication-ldap.autoregister

Example Value:

authentication-ldap.autoregister = true

Informational Note:

This will turn LDAP autoregistration on or off. With this on, a new EPerson object will be created for any user who successfully authenticates against the LDAP server when they first login. With this setting off, the user must first register to get an EPerson object by entering their ldap username and password and filling out the forms.

Property:

authentication-ldap.provider_url

Example Value:

authentication-ldap.provider_url = ldap://ldap.myu.edu/o=myu.edu\,ou=mydept

Informational Note:

This is the url to your institution's LDAP server. You may or may not need the /o=myu.edu part at the end. Your server may also require the ldaps:// protocol. (This field has no default value)

NOTE: As of DSpace 6, commas (,) are now a special character in the Configuration system. Therefore, be careful to escape any required commas in this configuration by adding a backslash (\) before each comma, e.g. "\,"

Property:

authentication-ldap.starttls

Example Value:authentication-ldap.starttls = false
Informational Note:

Should we issue StartTLS after establishing TCP connection in order to initiate an encrypted connection?
Note: This (TLS) is different from LDAPS:

  • TLS is a tunnel for plain LDAP and is typically recognized on the same port (standard LDAP port: 389)
  • LDAPS is a separate protocol, deprecated in favor of the standard TLS method. (standard LDAPS port: 636)

Property:

authentication-ldap.id_field

Example Value:

authentication-ldap.id_field = uid

Explanation:

This is the unique identifier field in the LDAP directory where the username is stored. (This field has no default value)

Property:

authentication-ldap.object_context

Example Value:

authentication-ldap.object_context = ou=people\,o=myu.edu

Informational Note:

This is the LDAP object context to use when authenticating the user. By default, DSpace will use this value to create the user's DN in order to attempt to authenticate them. It is appended to the id_field and username. For example uid=username\,ou=people\,o=myu.edu. You will need to modify this to match your LDAP configuration. (This field has no default value)

If your users do NOT all exist under a single "object_context" in LDAP, then you should ignore this setting and INSTEAD use the Hierarchical LDAP Authentication settings below (especially see "search.user" or "search.anonymous")

NOTE: As of DSpace 6, commas (,) are now a special character in the Configuration system. Therefore, be careful to escape any required commas in this configuration by adding a backslash (\) before each comma, e.g. "\,"

Property:

authentication-ldap.search_context

Example Value:

authentication-ldap.search_context = ou=people

Informational Note:

This is the search context used when looking up a user's LDAP object to retrieve their data for autoregistering. With autoregister=true, when a user authenticates without an EPerson object we search the LDAP directory to get their name (id_field) and email address (email_field) so that we can create one for them. So after we have authenticated against uid=username,ou=people,o=byu.edu we now search in ou=people for filtering on [uid=username]. Often the search_context is the same as the object_context parameter. But again this depends on your LDAP server configuration. (This field has no default value, and it MUST be specified when either search.anonymous=true or search.user is specified)

NOTE: As of DSpace 6, commas (,) are now a special character in the Configuration system. Therefore, be careful to escape any required commas in this configuration by adding a backslash (\) before each comma, e.g. "\,"

Property:

authentication-ldap.email_field

Example Value:

authentication-ldap.email_field = mail

Informational Note:

This is the LDAP object field where the user's email address is stored. "mail" is the most common for LDAP servers. (This field has no default value)

If the "email_field" is unspecified, or the user has no email address in LDAP, his/her username (id_field value) will be saved as the email in DSpace (or appended to netid_email_domain, when specified)

Property:authentication-ldap.netid_email_domain
Example Value:authentication-ldap.netid_email_domain = @example.com
Informational Note:

If your LDAP server does not hold an email address for a user (i.e. no email_field), you can use the following field to specify your email domain. This value is appended to the netid (id_field) in order to make an email address (which is then stored in the DSpace EPerson). For example, a netid of 'user' and netid_email_domain as @example.com would set the email of the user to be user@example.com

Please note: this field will only be used if "email_field" is unspecified OR the user in question has no email address stored in LDAP. If both "email_field" and "netid_email_domain" are unspecified, then the "id_field" will be used as the email address.

Property:

authentication-ldap.surname_field

Example Value:

authentication-ldap.surname_field = sn

Informational Note:

This is the LDAP object field where the user's last name is stored. "sn" is the most common for LDAP servers. If the field is not found the field will be left blank in the new eperson object. (This field has no default value)

Property:

authentication-ldap.givenname_field

Example Value:

authentication-ldap.givenname_field = givenName

Informational Note:

This is the LDAP object field where the user's given names are stored. I'm not sure how common the givenName field is in different LDAP instances. If the field is not found the field will be left blank in the new eperson object. (This field has no default value)

Property:

authentication-ldap.phone_field

Example Value:

authentication-ldap.phone_field = telephoneNumber

Informational Note:

This is the field where the user's phone number is stored in the LDAP directory. If the field is not found the field will be left blank in the new eperson object. (This field has no default value)

Property:

authentication-ldap.login.specialgroup

Example Value:

authentication-ldap.login.specialgroup = group-name

Informational Note:

If specified, all user sessions successfully logged in via LDAP will automatically become members of this DSpace Group (for the remainder of their current, logged in session). This DSpace Group must already exist (it will not be automatically created).
This is useful if you want a DSpace Group made up of all internal authenticated users. This DSpace Group can then be used to bestow special permissions on any users who have authenticated via LDAP (e.g. you could allow anyone authenticated via LDAP to view special, on campus only collections or similar)

Property:
Anchor
login.groupmap
login.groupmap
login.groupmap.*
Example Value:authentication-ldap.login.groupmap.1 = ou=Students:ALL_STUDENTS 
authentication-ldap.login.groupmap.2 = ou=Employees:ALL_EMPLOYEES 
authentication-ldap.login.groupmap.3 = ou=Faculty:ALL_FACULTY 
Informational Note:

The left part of the value (before the ":") must correspond to a portion of a user's DN (unless "login.group.attribute" is specified..please see below). The right part of the value corresponds to the name of an existing DSpace group.

For example, if the authenticated user's DN in LDAP is in the following form:

cn=jdoe,OU=Students,OU=Users,dc=example,dc=edu

that user would get assigned to the ALL_STUDENTS DSpace group for the remainder of their current session.

However, if that same user later graduates and is employed by the university, their DN in LDAP may change to:

cn=jdoe,OU=Employees,OU=Users,dc=example,dc=edu

Upon logging into DSpace after that DN change, the authenticated user would now be assigned to the ALL_EMPLOYEES DSpace group for the remainder of their current session.

Note: This option can be used independently from the login.specialgroup option, which will put all LDAP users into a single DSpace group. Both options may be used together.

Property:authentication-ldap.login.groupmap.attribute
Example Value:authentication-ldap.login.groupmap.attribute = group
Informational Note:

The value of the "authentication-ldap.login.groupmap.attribute" should specify the name of a single LDAP attribute. If this property is uncommented, it changes the meaning of the left part of "authentication-ldap.login.groupmap.*" (see above) as follows:

  • If the authenticated user has this LDAP attribute, look up the value of this LDAP attribute in the left part (before the ":") of the authentication-ldap.login.groupmap.* value
  • If that LDAP value is found in any "authentication-ldap.login.groupmap.*" field, assign this authenticated user to the DSpace Group specified by the right part (after the ":") of the authentication-ldap.login.groupmap.* value.

For example:

  • authentication-ldap.login.groupmap.attribute = group
  • authentication-ldap.login.groupmap.1 = mathematics:Mathematics_Group

The above would ensure that any authenticated users where their LDAP "group" attribute equals "mathematics" would be added to the DSpace Group named "Mathematics_Group" for the remainder of their current session. However, if that same user logged in later with a new LDAP "group" value of "computer science", he/she would no longer be a member of the "Mathematics_Group" in DSpace.

...

Hierarchical LDAP Authentication shares all the above standard LDAP configurations, but has some additional settings.

...