# DSpace -- Apache installation

## Why we use Apache as web server ?

We choose to use *Apache* as webserver instead of popular *Nginx* alternative due to *Shibboleth* authentication system that we need to use for DSpace.

DSpace (at this time - 2023/10/05) doesn't provide any offical documentation/support to connect Shibboleth through Nginx. Although a nginx module exists, nginx need to be compiled with this module, it's not so easy. This module also need to work with FastCGI on the server ; and I never found solution to transfer Shibboleth headers until the DSpace application. It seems headers are "lost" into FastCGI or Nginx ; they never arrive until Tomcat.

Using "Apache" is more easy because installation steps are well documented on offical DSpace site : https://wiki.lyrasis.org/display/DSDOC7x/Authentication+Plugins#AuthenticationPlugins-ShibbolethAuthentication

## Apache install/configuration

Install and enable some modules on Apache, then restart Apache

$ sudo apt-get install apache2 libapache2-mod-shib
$ sudo a2enmod headers proxy proxy_http proxy_ajp ssl rewrite shib
$ sudo service apache2 restart
$ sudo apachectl -M | grep headers
>>> headers_module (shared)
$ sudo apachectl -M | grep proxy
>>> proxy_module (shared)
>>> proxy_ajp_module (shared)
>>> proxy_http_module (shared)
$ sudo apachectl -M | grep shib
>>> mod_shib (shared)
$ sudo apachectl -M | grep ssl
>>> ssl_module (shared)

Configure sites and SSL configuration for your server.
To use Shibboleth authentication we need to have a "site configuration file" with these info inside :

<IfModule mod_shib>
	UseCanonicalName 		On

       <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 endpoint, force them to authenticate via Shib.
       <Location "/server/api/authn/shibboleth">
	 Order	deny,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
         Require shibboleth
       </Location>

       # If 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
          AuthType shibboleth
          # For DSpace, this is required to be off otherwise the available auth methods will be not visible
          ShibRequireSession Off
          # 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
       </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
         SetHandler shib
       </Location>

       # Finally, 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 USING mod_proxy TO REDIRECT
       # ALL REQUESTS TO TOMCAT (e.g. ProxyPass /server ajp://localhost:8009/server)
       ProxyPass /Shibboleth.sso !

</IfModule>

## Shibboleth configuration
We need to adapt the server shibboleth configuration because we use an AJP connection between Apache and Tomcat. This configuration should be part of *shibboleth2.xml" file

<ApplicationDefaults
    entityID="..."
    REMOTE_USER="..."
    cipherSuites="..."
    signing="false" 
    encryption="false"
    attributePrefix="AJP_">

Don't forget to restart *shibd* :

sudo service shibd restart

## Tomcat configuration

We will configure an AJP connector on *Tomcat* application server. This connector will be only used to link Apache and Tomcat toghether.

<Connector protocol="AJP/1.3"
           port="8009" 
           redirectPort="8443" 
           URIEncoding="UTF-8" 
           secretRequired="false"
           maxHeaderCount="-1"
           allowedRequestAttributesPattern=".*"  
/>
#maxHeaderCount :: Shibboleth could return a lot of headers depending of the IdProvider configuration.
#allowedRequestAttributesPattern :: Accept all headers (because IdProvider seems cleaned "shib_*" header to return only header canonical name)

and restart Tomcat

$ sudo service tomcat restart

## DSpace configuration

We need to activate the Shibboleth autentication for our DSpace repository.
We just need to activate this into `[dspace-dir]/config/modules/authentication.cfg`

plugin.sequence.org.dspace.authenticate.AuthenticationMethod

And update configuration into `[dspace-dir]/config/modules/authentication-shibboleth.cfg`

authentication-shibboleth.lazysession = true
authentication-shibboleth.lazysession.loginurl = /Shibboleth.sso/Login
authentication-shibboleth.lazysession.secure = true
...
authentication-shibboleth.netid-header = uid
authentication-shibboleth.email-header = mail
authentication-shibboleth.email-use-tomcat-remote-user = false
...
authentication-shibboleth.firstname-header = givenName
authentication-shibboleth.lastname-header = sn
...
authentication-shibboleth.role-header = unscoped-affiliation
authentication-shibboleth.role.staff = Staff
authentication-shibboleth.role.student = Student

We need to restart tomcat to apply these changes.