Editing Archive:Webserver authentication (section)

== Configuration ==
=== Exclude a resource from EPrints proper ===
Add the name of the resource where webserver authentication should happen to the end of <tt>archives/[repo_id]/cfg/cfg.d/[[20_baseurls.pl]]</tt>, e.g.:
 $c->{rewrite_exceptions} = ['/shibboleth'];
After a <tt>service httpd reload</tt> EPrints should ''not'' present the usual, nicely formatted error message when trying to access this resource (compare with any other non-existing request URI). Instead you should see an ordinary HTTP 404 "File not found" error.

=== Add the login script ===
There are two example scripts provided in the package:
* <tt>login-noprovisioning</tt>, which failes logins for users not found in your EPrints instance and simply redirects them to a page of your choice. Provisioning user accounts needs to happen via some other process (e.g. manually, batch processes, etc.)
* <tt>login-autocreate</tt>, which automatically creates local EPrints users (of type "user") after successful external authentication.
Both variants can be extended according to local needs and capabilities, e.g. if your authentication system does not provide additional profile info (name, email, etc.) you could add a lookup from an LDAP directory or database to the code.

Decide on a variant of the login script. We'll be assuming <tt>login-autocreate</tt> since it's more practically useful for a new install (which is what we're describing here). Create a directory in your EPrints directory and copy your choice of login script there, naming it <tt>login</tt>. (Again, non-RPM based installs will possibly need to adjust user, paths and file ownership):
 su - eprints
 cd /usr/share/eprints/
 mkdir shibboleth
 cp /path/to/login shibboleth/
 chown eprints:eprints shibboleth/login
 chmod +x shibboleth/login

=== Tell httpd about the login scipt ===
Next include the content of the file <tt>eprints-httpd-auth.conf</tt> inside your SSL vhost webserver configuration in <tt>/etc/httpd/conf.d/ssl.conf</tt>, adapting file system paths as necessary:

 <VirtualHost _default_:443>
 ServerName https://your.hostname.example.org:443
 [...]
 Alias /shibboleth /usr/share/eprints/shibboleth
 <Directory "/usr/share/eprints/shibboleth">
    SetHandler perl-script
    PerlHandler ModPerl::Registry
    PerlSendHeader Off
    Options ExecCGI FollowSymLinks
    
    AuthType shibboleth
    ShibRequestSetting requireSession 1
    require valid-user
 </Directory>

'''or''' copy <tt>eprints-httpd-auth.conf</tt> to <tt>/etc/httpd/conf/</tt> (for example) and only reference it inside your SSL vhost with an include directive. Then you only have two includes in your otherwise unmodified (as far as EPrints is concerned) SSL config:

 Include /etc/httpd/conf/eprints-httpd-auth.conf
 Include /usr/share/eprints/cfg/apache_ssl.conf

Either way, there's an <tt>Alias</tt> directive that makes the directory created before available in URL space as <tt>/shibboleth</tt>, then a content handler is defined for everything in this <tt><Directory></tt>, and finally authentication and autorization is enforced, using Shibboleth only as an example.

With Shibboleth you could restrict logins to specific groups of people. e.g. only faculty and staff from your institution, but not students, or, if you're part of an [https://refeds.org/ Identity Federation] maybe you need to limit logins to members of specific institutions for some reason. You'd then replace <tt>require valid-user</tt> (which means anyone authenticated is also authorized to access the resource) with something like:
 require affiliation ~ ^(faculty|staff)@example\.edu$
There are [https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPhtaccess examples of the syntax in the Shibboleth documentation].

For other WebSSO or authentication systems that don't provide any data about the subject to the webserver other than <tt>REMOTE_USER</tt> (e.g. [http://weblogin.org/ CoSign] or systems using Kerberos) you can combine some of them with authorization in the webserver, e.g. via [http://httpd.apache.org/docs/2.2/en/mod/mod_authnz_ldap.html mod_authnz_ldap].

Finally, instead of also including this config inside the non-SSL vhost we simply redirect all plain HTTP requests matching our resource to the SSL vhost, where authentication then kicks in. To do that we modify the auto-generated webserver config for EPrints in <tt>/usr/share/eprints/cfg/apache/[repo_id].conf</tt> and add three Rewrite directives (assuming <tt>mod_rewrite</tt> is available and has been loaded by the webserver, which usually is the default):

 [...]
 ServerAdmin you@example.org
 
 RewriteEngine On
 RewriteCond %{REQUEST_URI} ^/shibboleth/
 RewriteRule ^(.+)$ https://your.hostname.example.org$1 [R]
 
 <Location "">
 [...]

'''Alternatively''', to avoid any unintentional changes to the auto-generated config file, which could be overwritten by careless use of <tt>epadmin</tt>, you could assemble a config file for the non-SSL vhost yourself, based on the series of Includes starting with <tt>/etc/httpd/conf.d/eprints.conf</tt> and include that within your httpd config instead.

=== Activate the new authentication method ===
To finally activate the switch to webserver-based authentication copy <tt>auth.pl</tt> to <tt>archives/[repo_id]/cfg/cfg.d/</tt> and reload httpd.
Conversely, to deactivate webserver-based authentication and restore EPrints' default authentication method either remove the file or wrap the whole file's content in a <tt>while(0){</tt> and <tt>}</tt> block (Perl's approximation of a block comment) and reload httpd.

[[Category:Authentication]]