EPrints Documentation - User contributions [en-gb]

Webserver authentication

2012-06-30T15:13:44Z

Sp: /* Prerequisites */ $v++

How to '''configure EPrints for authentication via the webserver'''. This enables/provides for
* re-use of externally managed ("enterprise") user accounts,
* automated Just-In-Time provisioning ("on-access provisioning"), instead of Just-In-Case (seperately managed batch processes)
* Web Single Sign-On to EPrints (with Shibboleth, CAS/<tt>mod_cas</tt>, Kerberos or just about any <tt>mod_auth_*</tt> Module for Apache httpd).
With small changes (not included below) EPrints user types (<tt>User</tt>, <tt>Editor</tt>, <tt>Repository Administrator</tt>) could also be assigned dynamically, based on data from an external authoritative source (e.g. an LDAP directory via <tt>Net::LDAP</tt> or an RDBMS via <tt>DBI</tt>) or recieved as SAML attributes (in case of Shibboleth).

== Conceptual overview ==
Here's how this integration works conceptually (not in order of steps performed). Filenames in parentheses refer to the files from http://files.eprints.org/738/
# Enable [[HTTPS]] for your webserver and the EPrints instance.
# Configure EPrints to send requests requiring authentication to a specific resource/URL, we'll assume <tt>/shibboleth/login</tt> below but this could be any string of your choice. (<tt>auth.pl</tt>)
# Make EPrints proper ignore these requests (<tt>archives/[repo_id]/cfg/cfg.d/[[20_baseurls.pl]]</tt>)
# Require authentication (and possibly also authorization) in the webserver for access to this resource (<tt>eprints-httpd-auth.conf</tt>)
# Add code to the installation which handles those pre-authenticated requests, creates new users and sessions, and returns to the originally requested resource. (<tt>login</tt>)

Note that the recipe below does '''not''' provide a parallel authentication method for EPrints -- it completely replaces the default authentication method and login prompt. You can disable the new authentication method to change the user type of some (possibly newly created) user account to "repository administrator" afterwards (when logging in as eprints admin with local/database authentication). Alternatively make sure that a user account already exists within EPrints that is of user type "repository adminstrator" and has a username that can authenticate to the external authentication system (with Shibboleth you'd also need to make sure that this username is returned from the SAML Identity Provider and that the correct, i.e., matching username is being mapped to httpd's <tt>REMOTE_USER</tt> variable).

A consequence of external authentication is that no self-registration of user accounts within EPrints is possible (or necessary, as many would see it) anymore, unless the system providing external authentication itself offers self-registration.

A word of warning: Don't enable this in a production EPrints instance unless either all existing users have matching usernames in your external authentication system, or you can live with the consequences of any and all users being auto-created (again) with different usernames (thereby possibly losing access to all their data, roles, etc.). Updating usernames in EPrints or other migration strategies are ''not'' considered below. Conversely make sure that none of the external usernames ''unintendedly'' match any local EPrints accounts with admin or "repository administrator" or "editor" privileges -- unless you expressly want them to have those privileges.

== Prerequisites ==
The EPrints instance this has been tested with was deployed from the latest [[Installing EPrints 3 on RedHat Enterprise 5|EPrints RPMs]] (which, at the time of writing, was at 3.3.10) on a newly installed RHEL6 machine. All paths and file names are hence based on an RPM install on RHEL5/6 and will need to be adapted to your webserver and EPrints installation and configuration.

Download the files from http://files.eprints.org/738/ and unpack them to a directory of choice, e.g.
cd /tmp
wget http://files.eprints.org/738/1/webserver-auth.tgz
tar xvzf webserver-auth.tgz
cd webserver-auth

=== TLS/SSL ===
[[:Category:Authentication|SSL and HTTPS and Secure logins]] have been covered numerous times in this wiki, but most of the material is outdated and some seems horribly cumbersome (or both). Still, there's no point in creating ''yet another'' how-to for this so we'll keep this brief. TLS/SSL was enabled in the webserver by first installing the <tt>mod_ssl</tt> package and configuring a key pair in <tt>/etc/httpd/conf.d/ssl.conf</tt>.

When running <tt>[[Getting Started with EPrints 3|epadmin create]]</tt> supply a hostname for https connections. ''Contrary'' to a statement from [[Getting Started with EPrints 3]] ("If you will use https for your user pages (including login) enter the https hostname - ''No doubt, for secure usage you need another name''", my emphasis) this can and probably should be your main EPrints hostname also used for plain HTTP.

(To change this after installation either edit <tt>archives/[repo_id]/cfg/cfg.d/10_core.pl</tt> or do as suggested in this file and run <tt>epadmin config_core [repo_id]</tt>. Note that leaving this to <tt>epadmin</tt> does ''not'' set or change any of the <tt>*root</tt> or <tt>*cgiroot</tt> statements which are mentioned [[HTTPS|in the wiki]]. Only <tt>$c->{securehost}</tt> seems to be needed.)

Since the EPrints RPM already containes <tt>/etc/httpd/conf.d/eprints.conf</tt> EPrints should already be working fine over plain HTTP. To make EPrints available over TLS/SSL as well include the auto-generated SSL-specific config ''inside'' httpd's existing SSL-vhost as defined in <tt>/etc/httpd/conf.d/ssl.conf</tt>:
Include /usr/share/eprints/cfg/apache_ssl.conf
Check httpd's config for syntax errors (<tt>apachtectl -t</tt>) and restart httpd.
EPrints should now work over both http and https.

=== Webserver authentication ===
To keep this document short(er) and generally useful, please refer to your webserver's or authentication system's documentation for installation and configuration. (Note: For Shibboleth you can [https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPLinuxRPMInstall install from RPMs] as well). We'll assume you have the desired unique identifier for a user available in httpd's <tt>REMOTE_USER</tt> variable, no matter what authentication system used.

== 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]]

Webserver authentication

2012-06-30T15:12:09Z

Sp: /* Conceptual overview */

How to '''configure EPrints for authentication via the webserver'''. This enables/provides for
* re-use of externally managed ("enterprise") user accounts,
* automated Just-In-Time provisioning ("on-access provisioning"), instead of Just-In-Case (seperately managed batch processes)
* Web Single Sign-On to EPrints (with Shibboleth, CAS/<tt>mod_cas</tt>, Kerberos or just about any <tt>mod_auth_*</tt> Module for Apache httpd).
With small changes (not included below) EPrints user types (<tt>User</tt>, <tt>Editor</tt>, <tt>Repository Administrator</tt>) could also be assigned dynamically, based on data from an external authoritative source (e.g. an LDAP directory via <tt>Net::LDAP</tt> or an RDBMS via <tt>DBI</tt>) or recieved as SAML attributes (in case of Shibboleth).

== Conceptual overview ==
Here's how this integration works conceptually (not in order of steps performed). Filenames in parentheses refer to the files from http://files.eprints.org/738/
# Enable [[HTTPS]] for your webserver and the EPrints instance.
# Configure EPrints to send requests requiring authentication to a specific resource/URL, we'll assume <tt>/shibboleth/login</tt> below but this could be any string of your choice. (<tt>auth.pl</tt>)
# Make EPrints proper ignore these requests (<tt>archives/[repo_id]/cfg/cfg.d/[[20_baseurls.pl]]</tt>)
# Require authentication (and possibly also authorization) in the webserver for access to this resource (<tt>eprints-httpd-auth.conf</tt>)
# Add code to the installation which handles those pre-authenticated requests, creates new users and sessions, and returns to the originally requested resource. (<tt>login</tt>)

Note that the recipe below does '''not''' provide a parallel authentication method for EPrints -- it completely replaces the default authentication method and login prompt. You can disable the new authentication method to change the user type of some (possibly newly created) user account to "repository administrator" afterwards (when logging in as eprints admin with local/database authentication). Alternatively make sure that a user account already exists within EPrints that is of user type "repository adminstrator" and has a username that can authenticate to the external authentication system (with Shibboleth you'd also need to make sure that this username is returned from the SAML Identity Provider and that the correct, i.e., matching username is being mapped to httpd's <tt>REMOTE_USER</tt> variable).

A consequence of external authentication is that no self-registration of user accounts within EPrints is possible (or necessary, as many would see it) anymore, unless the system providing external authentication itself offers self-registration.

A word of warning: Don't enable this in a production EPrints instance unless either all existing users have matching usernames in your external authentication system, or you can live with the consequences of any and all users being auto-created (again) with different usernames (thereby possibly losing access to all their data, roles, etc.). Updating usernames in EPrints or other migration strategies are ''not'' considered below. Conversely make sure that none of the external usernames ''unintendedly'' match any local EPrints accounts with admin or "repository administrator" or "editor" privileges -- unless you expressly want them to have those privileges.

== Prerequisites ==
The EPrints instance this has been tested with was deployed from the latest [[Installing EPrints 3 on RedHat Enterprise 5|EPrints RPMs]] (which, at the time of writing, was at 3.3.7) on a newly installed RHEL6 machine. All paths and file names are hence based on an RPM install on RHEL5/6 and will need to be adapted to your webserver and EPrints installation and configuration.

Download the files from http://files.eprints.org/738/ and unpack them to a directory of choice, e.g.
cd /tmp
wget http://files.eprints.org/738/1/webserver-auth.tgz
tar xvzf webserver-auth.tgz
cd webserver-auth

=== TLS/SSL ===
[[:Category:Authentication|SSL and HTTPS and Secure logins]] have been covered numerous times in this wiki, but most of the material is outdated and some seems horribly cumbersome (or both). Still, there's no point in creating ''yet another'' how-to for this so we'll keep this brief. TLS/SSL was enabled in the webserver by first installing the <tt>mod_ssl</tt> package and configuring a key pair in <tt>/etc/httpd/conf.d/ssl.conf</tt>.

When running <tt>[[Getting Started with EPrints 3|epadmin create]]</tt> supply a hostname for https connections. ''Contrary'' to a statement from [[Getting Started with EPrints 3]] ("If you will use https for your user pages (including login) enter the https hostname - ''No doubt, for secure usage you need another name''", my emphasis) this can and probably should be your main EPrints hostname also used for plain HTTP.

(To change this after installation either edit <tt>archives/[repo_id]/cfg/cfg.d/10_core.pl</tt> or do as suggested in this file and run <tt>epadmin config_core [repo_id]</tt>. Note that leaving this to <tt>epadmin</tt> does ''not'' set or change any of the <tt>*root</tt> or <tt>*cgiroot</tt> statements which are mentioned [[HTTPS|in the wiki]]. Only <tt>$c->{securehost}</tt> seems to be needed.)

Since the EPrints RPM already containes <tt>/etc/httpd/conf.d/eprints.conf</tt> EPrints should already be working fine over plain HTTP. To make EPrints available over TLS/SSL as well include the auto-generated SSL-specific config ''inside'' httpd's existing SSL-vhost as defined in <tt>/etc/httpd/conf.d/ssl.conf</tt>:
Include /usr/share/eprints/cfg/apache_ssl.conf
Check httpd's config for syntax errors (<tt>apachtectl -t</tt>) and restart httpd.
EPrints should now work over both http and https.

=== Webserver authentication ===
To keep this document short(er) and generally useful, please refer to your webserver's or authentication system's documentation for installation and configuration. (Note: For Shibboleth you can [https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPLinuxRPMInstall install from RPMs] as well). We'll assume you have the desired unique identifier for a user available in httpd's <tt>REMOTE_USER</tt> variable, no matter what authentication system used.

== 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]]

Webserver authentication

2012-06-30T15:10:48Z

Sp: /* Conceptual overview */

How to '''configure EPrints for authentication via the webserver'''. This enables/provides for
* re-use of externally managed ("enterprise") user accounts,
* automated Just-In-Time provisioning ("on-access provisioning"), instead of Just-In-Case (seperately managed batch processes)
* Web Single Sign-On to EPrints (with Shibboleth, CAS/<tt>mod_cas</tt>, Kerberos or just about any <tt>mod_auth_*</tt> Module for Apache httpd).
With small changes (not included below) EPrints user types (<tt>User</tt>, <tt>Editor</tt>, <tt>Repository Administrator</tt>) could also be assigned dynamically, based on data from an external authoritative source (e.g. an LDAP directory via <tt>Net::LDAP</tt> or an RDBMS via <tt>DBI</tt>) or recieved as SAML attributes (in case of Shibboleth).

== Conceptual overview ==
Here's how this integration works conceptually (not in order of steps performed). Filenames in parentheses refer to the files from http://files.eprints.org/738/
# Enable [[HTTPS]] for your webserver and the EPrints instance.
# Configure EPrints to send requests requiring authentication to a specific resource/URL, we'll assume <tt>/shibboleth/login</tt> below but this could be any string of your choice. (<tt>auth.pl</tt>)
# Make EPrints proper ignore these requests (<tt>archives/[repo_id]/cfg/cfg.d/[[20_baseurls.pl]]</tt>)
# Require authentication (and possibly also authorization) in the webserver for access to this resource (<tt>eprints-httpd-auth.conf</tt>)
# Add code to the installation which handles those pre-authenticated requests, creates new users and sessions, and returns to the originally requested resource. (<tt>login</tt>)

Note that the recipe below does '''not''' provide a parallel authentication method for EPrints -- it completely replaces the default authentication method and login prompt. You can disable the new authentication method to change the user type of some (possibly newly created) user account to "repository administrator" afterwards (when logging in as eprints admin with local/database authentication). Alternatively make sure that a user account already exists within EPrints that is of user type "repository adminstrator" and has a username that can authenticate to the external authentication system (with Shibboleth you'd also need to make sure that this username is returned from the SAML Identity Provider and that the right, i.e., matching username is being mapped to httpd's <tt>REMOTE_USER</tt> variable).

A consequence of external authentication is that no self-registration of user accounts within EPrints is possible (or necessary, as many would see it) anymore, unless the system providing external authentication itself offers self-registration.

A word of warning: Don't enable this in a production EPrints instance unless either all existing users have matching usernames in your external authentication system, or you can live with the consequences of any and all users being auto-created (again) with different usernames (thereby possibly losing access to all their data, roles, etc.). Updating usernames in EPrints or other migration strategies are ''not'' considered below. Conversely make sure that none of the external usernames ''unintendedly'' match any local EPrints accounts with admin or "repository administrator" or "editor" privileges -- unless you expressly want them to have those privileges.

== Prerequisites ==
The EPrints instance this has been tested with was deployed from the latest [[Installing EPrints 3 on RedHat Enterprise 5|EPrints RPMs]] (which, at the time of writing, was at 3.3.7) on a newly installed RHEL6 machine. All paths and file names are hence based on an RPM install on RHEL5/6 and will need to be adapted to your webserver and EPrints installation and configuration.

Download the files from http://files.eprints.org/738/ and unpack them to a directory of choice, e.g.
cd /tmp
wget http://files.eprints.org/738/1/webserver-auth.tgz
tar xvzf webserver-auth.tgz
cd webserver-auth

=== TLS/SSL ===
[[:Category:Authentication|SSL and HTTPS and Secure logins]] have been covered numerous times in this wiki, but most of the material is outdated and some seems horribly cumbersome (or both). Still, there's no point in creating ''yet another'' how-to for this so we'll keep this brief. TLS/SSL was enabled in the webserver by first installing the <tt>mod_ssl</tt> package and configuring a key pair in <tt>/etc/httpd/conf.d/ssl.conf</tt>.

When running <tt>[[Getting Started with EPrints 3|epadmin create]]</tt> supply a hostname for https connections. ''Contrary'' to a statement from [[Getting Started with EPrints 3]] ("If you will use https for your user pages (including login) enter the https hostname - ''No doubt, for secure usage you need another name''", my emphasis) this can and probably should be your main EPrints hostname also used for plain HTTP.

(To change this after installation either edit <tt>archives/[repo_id]/cfg/cfg.d/10_core.pl</tt> or do as suggested in this file and run <tt>epadmin config_core [repo_id]</tt>. Note that leaving this to <tt>epadmin</tt> does ''not'' set or change any of the <tt>*root</tt> or <tt>*cgiroot</tt> statements which are mentioned [[HTTPS|in the wiki]]. Only <tt>$c->{securehost}</tt> seems to be needed.)

Since the EPrints RPM already containes <tt>/etc/httpd/conf.d/eprints.conf</tt> EPrints should already be working fine over plain HTTP. To make EPrints available over TLS/SSL as well include the auto-generated SSL-specific config ''inside'' httpd's existing SSL-vhost as defined in <tt>/etc/httpd/conf.d/ssl.conf</tt>:
Include /usr/share/eprints/cfg/apache_ssl.conf
Check httpd's config for syntax errors (<tt>apachtectl -t</tt>) and restart httpd.
EPrints should now work over both http and https.

=== Webserver authentication ===
To keep this document short(er) and generally useful, please refer to your webserver's or authentication system's documentation for installation and configuration. (Note: For Shibboleth you can [https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPLinuxRPMInstall install from RPMs] as well). We'll assume you have the desired unique identifier for a user available in httpd's <tt>REMOTE_USER</tt> variable, no matter what authentication system used.

== 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]]

Webserver authentication

2012-06-30T15:09:53Z

Sp: /* Conceptual overview */

How to '''configure EPrints for authentication via the webserver'''. This enables/provides for
* re-use of externally managed ("enterprise") user accounts,
* automated Just-In-Time provisioning ("on-access provisioning"), instead of Just-In-Case (seperately managed batch processes)
* Web Single Sign-On to EPrints (with Shibboleth, CAS/<tt>mod_cas</tt>, Kerberos or just about any <tt>mod_auth_*</tt> Module for Apache httpd).
With small changes (not included below) EPrints user types (<tt>User</tt>, <tt>Editor</tt>, <tt>Repository Administrator</tt>) could also be assigned dynamically, based on data from an external authoritative source (e.g. an LDAP directory via <tt>Net::LDAP</tt> or an RDBMS via <tt>DBI</tt>) or recieved as SAML attributes (in case of Shibboleth).

== Conceptual overview ==
Here's how this integration works conceptually (not in order of steps performed). Filenames in parentheses refer to the files from http://files.eprints.org/738/
# Enable [[HTTPS]] for your webserver and the EPrints instance.
# Configure EPrints to send requests requiring authentication to a specific resource/URL, we'll assume <tt>/shibboleth/login</tt> below but this could be any string of your choice. (<tt>auth.pl</tt>)
# Make EPrints proper ignore these requests (<tt>archives/[repo_id]/cfg/cfg.d/[[20_baseurls.pl]]</tt>)
# Require authentication (and possibly also authorization) in the webserver for access to this resource (<tt>eprints-httpd-auth.conf</tt>)
# Add code to the installation which handles those pre-authenticated requests (<tt>login</tt>), creates new users and sessions, and returns to the originally requested resource.

Note that the recipe below does '''not''' provide a parallel authentication method for EPrints -- it completely replaces the default authentication method and login prompt. You can disable the new authentication method to change the user type of some (possibly newly created) user account to "repository administrator" afterwards (when logging in as eprints admin with local/database authentication). Alternatively make sure that a user account already exists within EPrints that is of user type "repository adminstrator" and has a username that can authenticate to the external authentication system (with Shibboleth you'd also need to make sure that this username is returned from the SAML Identity Provider and that the right, i.e., matching username is being mapped to httpd's <tt>REMOTE_USER</tt> variable).

A consequence of external authentication is that no self-registration of user accounts within EPrints is possible (or necessary, as many would see it) anymore, unless the system providing external authentication itself offers self-registration.

A word of warning: Don't enable this in a production EPrints instance unless either all existing users have matching usernames in your external authentication system, or you can live with the consequences of any and all users being auto-created (again) with different usernames (thereby possibly losing access to all their data, roles, etc.). Updating usernames in EPrints or other migration strategies are ''not'' considered below. Conversely make sure that none of the external usernames ''unintendedly'' match any local EPrints accounts with admin or "repository administrator" or "editor" privileges -- unless you expressly want them to have those privileges.

== Prerequisites ==
The EPrints instance this has been tested with was deployed from the latest [[Installing EPrints 3 on RedHat Enterprise 5|EPrints RPMs]] (which, at the time of writing, was at 3.3.7) on a newly installed RHEL6 machine. All paths and file names are hence based on an RPM install on RHEL5/6 and will need to be adapted to your webserver and EPrints installation and configuration.

Download the files from http://files.eprints.org/738/ and unpack them to a directory of choice, e.g.
cd /tmp
wget http://files.eprints.org/738/1/webserver-auth.tgz
tar xvzf webserver-auth.tgz
cd webserver-auth

=== TLS/SSL ===
[[:Category:Authentication|SSL and HTTPS and Secure logins]] have been covered numerous times in this wiki, but most of the material is outdated and some seems horribly cumbersome (or both). Still, there's no point in creating ''yet another'' how-to for this so we'll keep this brief. TLS/SSL was enabled in the webserver by first installing the <tt>mod_ssl</tt> package and configuring a key pair in <tt>/etc/httpd/conf.d/ssl.conf</tt>.

When running <tt>[[Getting Started with EPrints 3|epadmin create]]</tt> supply a hostname for https connections. ''Contrary'' to a statement from [[Getting Started with EPrints 3]] ("If you will use https for your user pages (including login) enter the https hostname - ''No doubt, for secure usage you need another name''", my emphasis) this can and probably should be your main EPrints hostname also used for plain HTTP.

(To change this after installation either edit <tt>archives/[repo_id]/cfg/cfg.d/10_core.pl</tt> or do as suggested in this file and run <tt>epadmin config_core [repo_id]</tt>. Note that leaving this to <tt>epadmin</tt> does ''not'' set or change any of the <tt>*root</tt> or <tt>*cgiroot</tt> statements which are mentioned [[HTTPS|in the wiki]]. Only <tt>$c->{securehost}</tt> seems to be needed.)

Since the EPrints RPM already containes <tt>/etc/httpd/conf.d/eprints.conf</tt> EPrints should already be working fine over plain HTTP. To make EPrints available over TLS/SSL as well include the auto-generated SSL-specific config ''inside'' httpd's existing SSL-vhost as defined in <tt>/etc/httpd/conf.d/ssl.conf</tt>:
Include /usr/share/eprints/cfg/apache_ssl.conf
Check httpd's config for syntax errors (<tt>apachtectl -t</tt>) and restart httpd.
EPrints should now work over both http and https.

=== Webserver authentication ===
To keep this document short(er) and generally useful, please refer to your webserver's or authentication system's documentation for installation and configuration. (Note: For Shibboleth you can [https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPLinuxRPMInstall install from RPMs] as well). We'll assume you have the desired unique identifier for a user available in httpd's <tt>REMOTE_USER</tt> variable, no matter what authentication system used.

== 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]]

Webserver authentication

2012-06-06T16:53:57Z

Sp: /* Exclude a resource from EPrints proper */

How to '''configure EPrints for authentication via the webserver'''. This enables/provides for
* re-use of externally managed ("enterprise") user accounts,
* automated Just-In-Time provisioning ("on-access provisioning"), instead of Just-In-Case (seperately managed batch processes)
* Web Single Sign-On to EPrints (with Shibboleth, CAS/<tt>mod_cas</tt>, Kerberos or just about any <tt>mod_auth_*</tt> Module for Apache httpd).
With small changes (not included below) EPrints user types (<tt>User</tt>, <tt>Editor</tt>, <tt>Repository Administrator</tt>) could also be assigned dynamically, based on data from an external authoritative source (e.g. an LDAP directory via <tt>Net::LDAP</tt> or an RDBMS via <tt>DBI</tt>) or recieved as SAML attributes (in case of Shibboleth).

== Conceptual overview ==
Here's how this integration works conceptually (not in order of steps performed). Filenames in parentheses refer to the files from http://files.eprints.org/738/
# Enable [[HTTPS]] for your webserver and the EPrints instance.
# Configure EPrints to send requests requiring authentication to a specific resource/URL, we'll assume <tt>/shibboleth/login</tt> below but this could be any string of your choice and is ''not'' visible to people logging in! (<tt>auth.pl</tt>)
# Make EPrints proper ignore these requests (<tt>archives/[repo_id]/cfg/cfg.d/[[20_baseurls.pl]]</tt>)
# Require authentication (and possibly also authorization) in the webserver for access to this resource (<tt>eprints-httpd-auth.conf</tt>)
# Add code to the installation which handles those pre-authenticated requests (<tt>login</tt>), creates new users and sessions, and returns to the originally requested resource.

Note that the recipe below does '''not''' provide a parallel authentication method for EPrints -- it completely replaces the default authentication method and login prompt. You can disable the new authentication method to change the user type of some (possibly newly created) user account to "repository administrator" afterwards (when logging in as eprints admin with local/database authentication). Alternatively make sure that a user account already exists within EPrints that is of user type "repository adminstrator" and has a username that can authenticate to the external authentication system (with Shibboleth you'd also need to make sure that this username is returned from the SAML Identity Provider and that the right, i.e., matching username is being mapped to httpd's <tt>REMOTE_USER</tt> variable).

A consequence of external authentication is that no self-registration of user accounts within EPrints is possible (or necessary, as many would see it) anymore, unless the system providing external authentication itself offers self-registration.

A word of warning: Don't enable this in a production EPrints instance unless either all existing users have matching usernames in your external authentication system, or you can live with the consequences of any and all users being auto-created (again) with different usernames (thereby possibly losing access to all their data, roles, etc.). Updating usernames in EPrints or other migration strategies are ''not'' considered below. Conversely make sure that none of the external usernames ''unintendedly'' match any local EPrints accounts with admin or "repository administrator" or "editor" privileges -- unless you expressly want them to have those privileges.

== Prerequisites ==
The EPrints instance this has been tested with was deployed from the latest [[Installing EPrints 3 on RedHat Enterprise 5|EPrints RPMs]] (which, at the time of writing, was at 3.3.7) on a newly installed RHEL6 machine. All paths and file names are hence based on an RPM install on RHEL5/6 and will need to be adapted to your webserver and EPrints installation and configuration.

Download the files from http://files.eprints.org/738/ and unpack them to a directory of choice, e.g.
cd /tmp
wget http://files.eprints.org/738/1/webserver-auth.tgz
tar xvzf webserver-auth.tgz
cd webserver-auth

=== TLS/SSL ===
[[:Category:Authentication|SSL and HTTPS and Secure logins]] have been covered numerous times in this wiki, but most of the material is outdated and some seems horribly cumbersome (or both). Still, there's no point in creating ''yet another'' how-to for this so we'll keep this brief. TLS/SSL was enabled in the webserver by first installing the <tt>mod_ssl</tt> package and configuring a key pair in <tt>/etc/httpd/conf.d/ssl.conf</tt>.

When running <tt>[[Getting Started with EPrints 3|epadmin create]]</tt> supply a hostname for https connections. ''Contrary'' to a statement from [[Getting Started with EPrints 3]] ("If you will use https for your user pages (including login) enter the https hostname - ''No doubt, for secure usage you need another name''", my emphasis) this can and probably should be your main EPrints hostname also used for plain HTTP.

(To change this after installation either edit <tt>archives/[repo_id]/cfg/cfg.d/10_core.pl</tt> or do as suggested in this file and run <tt>epadmin config_core [repo_id]</tt>. Note that leaving this to <tt>epadmin</tt> does ''not'' set or change any of the <tt>*root</tt> or <tt>*cgiroot</tt> statements which are mentioned [[HTTPS|in the wiki]]. Only <tt>$c->{securehost}</tt> seems to be needed.)

Since the EPrints RPM already containes <tt>/etc/httpd/conf.d/eprints.conf</tt> EPrints should already be working fine over plain HTTP. To make EPrints available over TLS/SSL as well include the auto-generated SSL-specific config ''inside'' httpd's existing SSL-vhost as defined in <tt>/etc/httpd/conf.d/ssl.conf</tt>:
Include /usr/share/eprints/cfg/apache_ssl.conf
Check httpd's config for syntax errors (<tt>apachtectl -t</tt>) and restart httpd.
EPrints should now work over both http and https.

=== Webserver authentication ===
To keep this document short(er) and generally useful, please refer to your webserver's or authentication system's documentation for installation and configuration. (Note: For Shibboleth you can [https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPLinuxRPMInstall install from RPMs] as well). We'll assume you have the desired unique identifier for a user available in httpd's <tt>REMOTE_USER</tt> variable, no matter what authentication system used.

== 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]]

Webserver authentication

2012-06-06T16:29:42Z

Sp: /* TLS/SSL */ formatting

How to '''configure EPrints for authentication via the webserver'''. This enables/provides for
* re-use of externally managed ("enterprise") user accounts,
* automated Just-In-Time provisioning ("on-access provisioning"), instead of Just-In-Case (seperately managed batch processes)
* Web Single Sign-On to EPrints (with Shibboleth, CAS/<tt>mod_cas</tt>, Kerberos or just about any <tt>mod_auth_*</tt> Module for Apache httpd).
With small changes (not included below) EPrints user types (<tt>User</tt>, <tt>Editor</tt>, <tt>Repository Administrator</tt>) could also be assigned dynamically, based on data from an external authoritative source (e.g. an LDAP directory via <tt>Net::LDAP</tt> or an RDBMS via <tt>DBI</tt>) or recieved as SAML attributes (in case of Shibboleth).

== Conceptual overview ==
Here's how this integration works conceptually (not in order of steps performed). Filenames in parentheses refer to the files from http://files.eprints.org/738/
# Enable [[HTTPS]] for your webserver and the EPrints instance.
# Configure EPrints to send requests requiring authentication to a specific resource/URL, we'll assume <tt>/shibboleth/login</tt> below but this could be any string of your choice and is ''not'' visible to people logging in! (<tt>auth.pl</tt>)
# Make EPrints proper ignore these requests (<tt>archives/[repo_id]/cfg/cfg.d/[[20_baseurls.pl]]</tt>)
# Require authentication (and possibly also authorization) in the webserver for access to this resource (<tt>eprints-httpd-auth.conf</tt>)
# Add code to the installation which handles those pre-authenticated requests (<tt>login</tt>), creates new users and sessions, and returns to the originally requested resource.

Note that the recipe below does '''not''' provide a parallel authentication method for EPrints -- it completely replaces the default authentication method and login prompt. You can disable the new authentication method to change the user type of some (possibly newly created) user account to "repository administrator" afterwards (when logging in as eprints admin with local/database authentication). Alternatively make sure that a user account already exists within EPrints that is of user type "repository adminstrator" and has a username that can authenticate to the external authentication system (with Shibboleth you'd also need to make sure that this username is returned from the SAML Identity Provider and that the right, i.e., matching username is being mapped to httpd's <tt>REMOTE_USER</tt> variable).

A consequence of external authentication is that no self-registration of user accounts within EPrints is possible (or necessary, as many would see it) anymore, unless the system providing external authentication itself offers self-registration.

A word of warning: Don't enable this in a production EPrints instance unless either all existing users have matching usernames in your external authentication system, or you can live with the consequences of any and all users being auto-created (again) with different usernames (thereby possibly losing access to all their data, roles, etc.). Updating usernames in EPrints or other migration strategies are ''not'' considered below. Conversely make sure that none of the external usernames ''unintendedly'' match any local EPrints accounts with admin or "repository administrator" or "editor" privileges -- unless you expressly want them to have those privileges.

== Prerequisites ==
The EPrints instance this has been tested with was deployed from the latest [[Installing EPrints 3 on RedHat Enterprise 5|EPrints RPMs]] (which, at the time of writing, was at 3.3.7) on a newly installed RHEL6 machine. All paths and file names are hence based on an RPM install on RHEL5/6 and will need to be adapted to your webserver and EPrints installation and configuration.

Download the files from http://files.eprints.org/738/ and unpack them to a directory of choice, e.g.
cd /tmp
wget http://files.eprints.org/738/1/webserver-auth.tgz
tar xvzf webserver-auth.tgz
cd webserver-auth

=== TLS/SSL ===
[[:Category:Authentication|SSL and HTTPS and Secure logins]] have been covered numerous times in this wiki, but most of the material is outdated and some seems horribly cumbersome (or both). Still, there's no point in creating ''yet another'' how-to for this so we'll keep this brief. TLS/SSL was enabled in the webserver by first installing the <tt>mod_ssl</tt> package and configuring a key pair in <tt>/etc/httpd/conf.d/ssl.conf</tt>.

When running <tt>[[Getting Started with EPrints 3|epadmin create]]</tt> supply a hostname for https connections. ''Contrary'' to a statement from [[Getting Started with EPrints 3]] ("If you will use https for your user pages (including login) enter the https hostname - ''No doubt, for secure usage you need another name''", my emphasis) this can and probably should be your main EPrints hostname also used for plain HTTP.

(To change this after installation either edit <tt>archives/[repo_id]/cfg/cfg.d/10_core.pl</tt> or do as suggested in this file and run <tt>epadmin config_core [repo_id]</tt>. Note that leaving this to <tt>epadmin</tt> does ''not'' set or change any of the <tt>*root</tt> or <tt>*cgiroot</tt> statements which are mentioned [[HTTPS|in the wiki]]. Only <tt>$c->{securehost}</tt> seems to be needed.)

Since the EPrints RPM already containes <tt>/etc/httpd/conf.d/eprints.conf</tt> EPrints should already be working fine over plain HTTP. To make EPrints available over TLS/SSL as well include the auto-generated SSL-specific config ''inside'' httpd's existing SSL-vhost as defined in <tt>/etc/httpd/conf.d/ssl.conf</tt>:
Include /usr/share/eprints/cfg/apache_ssl.conf
Check httpd's config for syntax errors (<tt>apachtectl -t</tt>) and restart httpd.
EPrints should now work over both http and https.

=== Webserver authentication ===
To keep this document short(er) and generally useful, please refer to your webserver's or authentication system's documentation for installation and configuration. (Note: For Shibboleth you can [https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPLinuxRPMInstall install from RPMs] as well). We'll assume you have the desired unique identifier for a user available in httpd's <tt>REMOTE_USER</tt> variable, no matter what authentication system used.

== 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 a 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]]

Webserver authentication

2012-03-16T10:14:45Z

Sp: slight rephrasing of headings

How to '''configure EPrints for authentication via the webserver'''. This enables/provides for
* re-use of externally managed ("enterprise") user accounts,
* automated Just-In-Time provisioning ("on-access provisioning"), instead of Just-In-Case (seperately managed batch processes)
* Web Single Sign-On to EPrints (with Shibboleth, CAS/<tt>mod_cas</tt>, Kerberos or just about any <tt>mod_auth_*</tt> Module for Apache httpd).
With small changes (not included below) EPrints user types (<tt>User</tt>, <tt>Editor</tt>, <tt>Repository Administrator</tt>) could also be assigned dynamically, based on data from an external authoritative source (e.g. an LDAP directory via <tt>Net::LDAP</tt> or an RDBMS via <tt>DBI</tt>) or recieved as SAML attributes (in case of Shibboleth).

== Conceptual overview ==
Here's how this integration works conceptually (not in order of steps performed). Filenames in parentheses refer to the files from http://files.eprints.org/738/
# Enable [[HTTPS]] for your webserver and the EPrints instance.
# Configure EPrints to send requests requiring authentication to a specific resource/URL, we'll assume <tt>/shibboleth/login</tt> below but this could be any string of your choice and is ''not'' visible to people logging in! (<tt>auth.pl</tt>)
# Make EPrints proper ignore these requests (<tt>archives/[repo_id]/cfg/cfg.d/[[20_baseurls.pl]]</tt>)
# Require authentication (and possibly also authorization) in the webserver for access to this resource (<tt>eprints-httpd-auth.conf</tt>)
# Add code to the installation which handles those pre-authenticated requests (<tt>login</tt>), creates new users and sessions, and returns to the originally requested resource.

Note that the recipe below does '''not''' provide a parallel authentication method for EPrints -- it completely replaces the default authentication method and login prompt. You can disable the new authentication method to change the user type of some (possibly newly created) user account to "repository administrator" afterwards (when logging in as eprints admin with local/database authentication). Alternatively make sure that a user account already exists within EPrints that is of user type "repository adminstrator" and has a username that can authenticate to the external authentication system (with Shibboleth you'd also need to make sure that this username is returned from the SAML Identity Provider and that the right, i.e., matching username is being mapped to httpd's <tt>REMOTE_USER</tt> variable).

A consequence of external authentication is that no self-registration of user accounts within EPrints is possible (or necessary, as many would see it) anymore, unless the system providing external authentication itself offers self-registration.

A word of warning: Don't enable this in a production EPrints instance unless either all existing users have matching usernames in your external authentication system, or you can live with the consequences of any and all users being auto-created (again) with different usernames (thereby possibly losing access to all their data, roles, etc.). Updating usernames in EPrints or other migration strategies are ''not'' considered below. Conversely make sure that none of the external usernames ''unintendedly'' match any local EPrints accounts with admin or "repository administrator" or "editor" privileges -- unless you expressly want them to have those privileges.

== Prerequisites ==
The EPrints instance this has been tested with was deployed from the latest [[Installing EPrints 3 on RedHat Enterprise 5|EPrints RPMs]] (which, at the time of writing, was at 3.3.7) on a newly installed RHEL6 machine. All paths and file names are hence based on an RPM install on RHEL5/6 and will need to be adapted to your webserver and EPrints installation and configuration.

Download the files from http://files.eprints.org/738/ and unpack them to a directory of choice, e.g.
cd /tmp
wget http://files.eprints.org/738/1/webserver-auth.tgz
tar xvzf webserver-auth.tgz
cd webserver-auth

=== TLS/SSL ===
[[:Category:Authentication|SSL and HTTPS and Secure logins]] have been covered numerous times in this wiki, but most of the material is outdated and some seems horribly cumbersome (or both). Still, there's no point in creating ''yet another'' how-to for this so we'll keep this brief. TLS/SSL was enabled in the webserver by first installing the <tt>mod_ssl</tt> package and configuring a key pair in <tt>/etc/httpd/conf.d/ssl.conf</tt>.

When running <tt>[[Getting Started with EPrints 3|epadmin create]]</tt> supply a hostname for https connections. ''Contrary'' to a statement from [[Getting Started with EPrints 3]] ("If you will use https for your user pages (including login) enter the https hostname - '''No doubt, for secure usage you need another name'''", my emphasis) this can and probably should be your main EPrints hostname also used for plain HTTP.

(To change this after installation either edit <tt>archives/[repo_id]/cfg/cfg.d/10_core.pl</tt> or do as suggested in this file and run <tt>epadmin config_core [repo_id]</tt>. Note that leaving this to <tt>epadmin</tt> does ''not'' set or change any of the <tt>*root</tt> or <tt>*cgiroot</tt> statements which are mentioned [[HTTPS|in the wiki]]. Only <tt>$c->{securehost}</tt> seems to be needed.)

Since the EPrints RPM already containes <tt>/etc/httpd/conf.d/eprints.conf</tt> EPrints should already be working fine over plain HTTP. To make EPrints available over TLS/SSL as well include the auto-generated SSL-specific config ''inside'' httpd's existing SSL-vhost as defined in <tt>/etc/httpd/conf.d/ssl.conf</tt>:
Include /usr/share/eprints/cfg/apache_ssl.conf
Check httpd's config for syntax errors (<tt>apachtectl -t</tt>) and restart httpd.
EPrints should now work over both http and https.

=== Webserver authentication ===
To keep this document short(er) and generally useful, please refer to your webserver's or authentication system's documentation for installation and configuration. (Note: For Shibboleth you can [https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPLinuxRPMInstall install from RPMs] as well). We'll assume you have the desired unique identifier for a user available in httpd's <tt>REMOTE_USER</tt> variable, no matter what authentication system used.

== 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 a 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]]

Webserver authentication

2012-03-16T10:08:05Z

Sp:

How to '''configure EPrints for authentication via the webserver'''. This enables/provides for
* re-use of externally managed ("enterprise") user accounts,
* automated Just-In-Time provisioning ("on-access provisioning"), instead of Just-In-Case (seperately managed batch processes)
* Web Single Sign-On to EPrints (with Shibboleth, CAS/<tt>mod_cas</tt>, Kerberos or just about any <tt>mod_auth_*</tt> Module for Apache httpd).
With small changes (not included below) EPrints user types (<tt>User</tt>, <tt>Editor</tt>, <tt>Repository Administrator</tt>) could also be assigned dynamically, based on data from an external authoritative source (e.g. an LDAP directory via <tt>Net::LDAP</tt> or an RDBMS via <tt>DBI</tt>) or recieved as SAML attributes (in case of Shibboleth).

== Conceptual overview ==
Here's how this integration works conceptually (not in order of steps performed). Filenames in parentheses refer to the files from http://files.eprints.org/738/
# Enable [[HTTPS]] for your webserver and the EPrints instance.
# Configure EPrints to send requests requiring authentication to a specific resource/URL, we'll assume <tt>/shibboleth/login</tt> below but this could be any string of your choice and is ''not'' visible to people logging in! (<tt>auth.pl</tt>)
# Make EPrints proper ignore these requests (<tt>archives/[repo_id]/cfg/cfg.d/[[20_baseurls.pl]]</tt>)
# Require authentication (and possibly also authorization) in the webserver for access to this resource (<tt>eprints-httpd-auth.conf</tt>)
# Add code to the installation which handles those pre-authenticated requests (<tt>login</tt>), creates new users and sessions, and returns to the originally requested resource.

Note that the recipe below does '''not''' provide a parallel authentication method for EPrints -- it completely replaces the default authentication method and login prompt. You can disable the new authentication method to change the user type of some (possibly newly created) user account to "repository administrator" afterwards (when logging in as eprints admin with local/database authentication). Alternatively make sure that a user account already exists within EPrints that is of user type "repository adminstrator" and has a username that can authenticate to the external authentication system (with Shibboleth you'd also need to make sure that this username is returned from the SAML Identity Provider and that the right, i.e., matching username is being mapped to httpd's <tt>REMOTE_USER</tt> variable).

A consequence of external authentication is that no self-registration of user accounts within EPrints is possible (or necessary, as many would see it) anymore, unless the system providing external authentication itself offers self-registration.

A word of warning: Don't enable this in a production EPrints instance unless either all existing users have matching usernames in your external authentication system, or you can live with the consequences of any and all users being auto-created (again) with different usernames (thereby possibly losing access to all their data, roles, etc.). Updating usernames in EPrints or other migration strategies are ''not'' considered below. Conversely make sure that none of the external usernames ''unintendedly'' match any local EPrints accounts with admin or "repository administrator" or "editor" privileges -- unless you expressly want them to have those privileges.

== Prerequisites ==
The EPrints instance this has been tested with was deployed from the latest [[Installing EPrints 3 on RedHat Enterprise 5|EPrints RPMs]] (which, at the time of writing, was at 3.3.7) on a newly installed RHEL6 machine. All paths and file names are hence based on an RPM install on RHEL5/6 and will need to be adapted to your webserver and EPrints installation and configuration.

Download the files from http://files.eprints.org/738/ and unpack them to a directory of choice, e.g.
cd /tmp
wget http://files.eprints.org/738/1/webserver-auth.tgz
tar xvzf webserver-auth.tgz
cd webserver-auth

=== TLS/SSL ===
[[:Category:Authentication|SSL and HTTPS and Secure logins]] have been covered numerous times in this wiki, but most of the material is outdated and some seems horribly cumbersome (or both). Still, there's no point in creating ''yet another'' how-to for this so we'll keep this brief. TLS/SSL was enabled in the webserver by first installing the <tt>mod_ssl</tt> package and configuring a key pair in <tt>/etc/httpd/conf.d/ssl.conf</tt>.

When running <tt>[[Getting Started with EPrints 3|epadmin create]]</tt> supply a hostname for https connections. ''Contrary'' to a statement from [[Getting Started with EPrints 3]] ("If you will use https for your user pages (including login) enter the https hostname - '''No doubt, for secure usage you need another name'''", my emphasis) this can and probably should be your main EPrints hostname also used for plain HTTP.

(To change this after installation either edit <tt>archives/[repo_id]/cfg/cfg.d/10_core.pl</tt> or do as suggested in this file and run <tt>epadmin config_core [repo_id]</tt>. Note that leaving this to <tt>epadmin</tt> does ''not'' set or change any of the <tt>*root</tt> or <tt>*cgiroot</tt> statements which are mentioned [[HTTPS|in the wiki]]. Only <tt>$c->{securehost}</tt> seems to be needed.)

Since the EPrints RPM already containes <tt>/etc/httpd/conf.d/eprints.conf</tt> EPrints should already be working fine over plain HTTP. To make EPrints available over TLS/SSL as well include the auto-generated SSL-specific config ''inside'' httpd's existing SSL-vhost as defined in <tt>/etc/httpd/conf.d/ssl.conf</tt>:
Include /usr/share/eprints/cfg/apache_ssl.conf
Check httpd's config for syntax errors (<tt>apachtectl -t</tt>) and restart httpd.
EPrints should now work over both http and https.

=== Webserver authentication ===
To keep this document short(er) and generally useful, please refer to your webserver's or authentication system's documentation for installation and configuration. (Note: For Shibboleth you can [https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPLinuxRPMInstall install from RPMs] as well). We'll assume you have the desired unique identifier for a user available in httpd's <tt>REMOTE_USER</tt> variable, no matter what authentication system used.

== Configuration ==
=== Exclude 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 a 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 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 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.

=== Tell EPrints about it ===
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]]

Files/EPrints webserver authentication

2012-03-16T09:46:22Z

Sp: Redirected page to Webserver authentication

#REDIRECT [[Webserver authentication]]

Webserver authentication

2012-03-15T20:54:36Z

Sp: /* Exclude resource from EPrints proper */ link 20_baseurls.pl

How to '''configure EPrints for authentication via the webserver'''. This enables/provides for
* re-use of externally managed ("enterprise") user accounts,
* automated Just-In-Time provisioning ("on-access provisioning"), instead of Just-In-Case (seperately managed batch processes)
* Web Single Sign-On to EPrints (with Shibboleth, CAS/<tt>mod_cas</tt>, Kerberos or just about any <tt>mod_auth_*</tt> Module for Apache httpd).
With small changes (not yet included below) EPrints user types (<tt>User</tt>, <tt>Editor</tt>, <tt>Repository Administrator</tt>) could also be assigned dynamically, based on data from an external authoritative source (e.g. an LDAP directory via <tt>Net::LDAP</tt> or an RDBMS via <tt>DBI</tt>) or recieved as SAML attributes (in case of Shibboleth).

== Conceptual overview ==
Here's how this integration works conceptually (not in order of steps performed). Filenames in parentheses refer to the files from http://files.eprints.org/738/
# Enable [[HTTPS]] for your webserver and the EPrints instance.
# Configure EPrints to send requests requiring authentication to a specific resource/URL, we'll assume <tt>/shibboleth/login</tt> below but this could be any string of your choice and is ''not'' visible to people logging in! (<tt>auth.pl</tt>)
# Make EPrints proper ignore these requests (<tt>archives/[repo_id]/cfg/cfg.d/[[20_baseurls.pl]]</tt>)
# Require authentication (and possibly also authorization) in the webserver for access to this resource (<tt>eprints-httpd-auth.conf</tt>)
# Add code to the installation which handles those pre-authenticated requests (<tt>login</tt>), creates new users and sessions, and returns to the originally requested resource.

Note that the recipe below does '''not''' provide a parallel authentication method for EPrints -- it completely replaces the default authentication method and login prompt. You can disable the new authentication method to change the user type of some (possibly newly created) user account to "repository administrator" afterwards (when logging in as eprints admin with local/database authentication). Alternatively make sure that a user account already exists within EPrints that is of user type "repository adminstrator" and has a username that can authenticate to the external authentication system (with Shibboleth you'd also need to make sure that this username is returned from the SAML Identity Provider and that the right, i.e., matching username is being mapped to httpd's <tt>REMOTE_USER</tt> variable).

A consequence of external authentication is that no self-registration of user accounts within EPrints is possible (or necessary, as many would see it) anymore, unless the system providing external authentication itself offers self-registration.

A word of warning: Don't enable this in a production EPrints instance unless either all existing users have matching usernames in your external authentication system, or you can live with the consequences of any and all users being auto-created (again) with different usernames (thereby possibly losing access to all their data, roles, etc.). Updating usernames in EPrints or other migration strategies are ''not'' considered below. Conversely make sure that none of the external usernames ''unintendedly'' match any local EPrints accounts with admin or "repository administrator" or "editor" privileges -- unless you expressly want them to have those privileges.

== Prerequisites ==
The EPrints instance this has been tested with was deployed from the latest [[Installing EPrints 3 on RedHat Enterprise 5|EPrints RPMs]] (which, at the time of writing, was at 3.3.7) on a newly installed RHEL6 machine. All paths and file names are hence based on an RPM install on RHEL5/6 and will need to be adapted to your webserver and EPrints installation and configuration.

Download the files from http://files.eprints.org/738/ and unpack them to a directory of choice, e.g.
cd /tmp
wget http://files.eprints.org/738/1/webserver-auth.tgz
tar xvzf webserver-auth.tgz
cd webserver-auth

=== TLS/SSL ===
[[:Category:Authentication|SSL and HTTPS and Secure logins]] have been covered numerous times in this wiki, but most of the material is outdated and some seems horribly cumbersome (or both). Still, there's no point in creating ''yet another'' how-to for this so we'll keep this brief. TLS/SSL was enabled in the webserver by first installing the <tt>mod_ssl</tt> package and configuring a key pair in <tt>/etc/httpd/conf.d/ssl.conf</tt>.

When running <tt>[[Getting Started with EPrints 3|epadmin create]]</tt> supply a hostname for https connections. ''Contrary'' to a statement from [[Getting Started with EPrints 3]] ("If you will use https for your user pages (including login) enter the https hostname - '''No doubt, for secure usage you need another name'''", my emphasis) this can and probably should be your main EPrints hostname also used for plain HTTP.

(To change this after installation either edit <tt>archives/[repo_id]/cfg/cfg.d/10_core.pl</tt> or do as suggested in this file and run <tt>epadmin config_core [repo_id]</tt>. Note that leaving this to <tt>epadmin</tt> does ''not'' set or change any of the <tt>*root</tt> or <tt>*cgiroot</tt> statements which are mentioned [[HTTPS|in the wiki]]. Only <tt>$c->{securehost}</tt> seems to be needed.)

Since the EPrints RPM already containes <tt>/etc/httpd/conf.d/eprints.conf</tt> EPrints should already be working fine over plain HTTP. To make EPrints available over TLS/SSL as well include the auto-generated SSL-specific config ''inside'' httpd's existing SSL-vhost as defined in <tt>/etc/httpd/conf.d/ssl.conf</tt>:
Include /usr/share/eprints/cfg/apache_ssl.conf
Check httpd's config for syntax errors (<tt>apachtectl -t</tt>) and restart httpd.
EPrints should now work over both http and https.

=== Webserver authentication ===
To keep this document short(er) and generally useful, please refer to your webserver's or authentication system's documentation for installation and configuration. (Note: For Shibboleth you can [https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPLinuxRPMInstall install from RPMs] as well). We'll assume you have the desired unique identifier for a user available in httpd's <tt>REMOTE_USER</tt> variable, no matter what authentication system used.

== Configuration ==
=== Exclude 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 a 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 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 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.

=== Tell EPrints about it ===
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]]

Webserver authentication

2012-03-15T20:54:02Z

Sp: /* Conceptual overview */link 20_baseurls.pl

How to '''configure EPrints for authentication via the webserver'''. This enables/provides for
* re-use of externally managed ("enterprise") user accounts,
* automated Just-In-Time provisioning ("on-access provisioning"), instead of Just-In-Case (seperately managed batch processes)
* Web Single Sign-On to EPrints (with Shibboleth, CAS/<tt>mod_cas</tt>, Kerberos or just about any <tt>mod_auth_*</tt> Module for Apache httpd).
With small changes (not yet included below) EPrints user types (<tt>User</tt>, <tt>Editor</tt>, <tt>Repository Administrator</tt>) could also be assigned dynamically, based on data from an external authoritative source (e.g. an LDAP directory via <tt>Net::LDAP</tt> or an RDBMS via <tt>DBI</tt>) or recieved as SAML attributes (in case of Shibboleth).

== Conceptual overview ==
Here's how this integration works conceptually (not in order of steps performed). Filenames in parentheses refer to the files from http://files.eprints.org/738/
# Enable [[HTTPS]] for your webserver and the EPrints instance.
# Configure EPrints to send requests requiring authentication to a specific resource/URL, we'll assume <tt>/shibboleth/login</tt> below but this could be any string of your choice and is ''not'' visible to people logging in! (<tt>auth.pl</tt>)
# Make EPrints proper ignore these requests (<tt>archives/[repo_id]/cfg/cfg.d/[[20_baseurls.pl]]</tt>)
# Require authentication (and possibly also authorization) in the webserver for access to this resource (<tt>eprints-httpd-auth.conf</tt>)
# Add code to the installation which handles those pre-authenticated requests (<tt>login</tt>), creates new users and sessions, and returns to the originally requested resource.

Note that the recipe below does '''not''' provide a parallel authentication method for EPrints -- it completely replaces the default authentication method and login prompt. You can disable the new authentication method to change the user type of some (possibly newly created) user account to "repository administrator" afterwards (when logging in as eprints admin with local/database authentication). Alternatively make sure that a user account already exists within EPrints that is of user type "repository adminstrator" and has a username that can authenticate to the external authentication system (with Shibboleth you'd also need to make sure that this username is returned from the SAML Identity Provider and that the right, i.e., matching username is being mapped to httpd's <tt>REMOTE_USER</tt> variable).

A consequence of external authentication is that no self-registration of user accounts within EPrints is possible (or necessary, as many would see it) anymore, unless the system providing external authentication itself offers self-registration.

A word of warning: Don't enable this in a production EPrints instance unless either all existing users have matching usernames in your external authentication system, or you can live with the consequences of any and all users being auto-created (again) with different usernames (thereby possibly losing access to all their data, roles, etc.). Updating usernames in EPrints or other migration strategies are ''not'' considered below. Conversely make sure that none of the external usernames ''unintendedly'' match any local EPrints accounts with admin or "repository administrator" or "editor" privileges -- unless you expressly want them to have those privileges.

== Prerequisites ==
The EPrints instance this has been tested with was deployed from the latest [[Installing EPrints 3 on RedHat Enterprise 5|EPrints RPMs]] (which, at the time of writing, was at 3.3.7) on a newly installed RHEL6 machine. All paths and file names are hence based on an RPM install on RHEL5/6 and will need to be adapted to your webserver and EPrints installation and configuration.

Download the files from http://files.eprints.org/738/ and unpack them to a directory of choice, e.g.
cd /tmp
wget http://files.eprints.org/738/1/webserver-auth.tgz
tar xvzf webserver-auth.tgz
cd webserver-auth

=== TLS/SSL ===
[[:Category:Authentication|SSL and HTTPS and Secure logins]] have been covered numerous times in this wiki, but most of the material is outdated and some seems horribly cumbersome (or both). Still, there's no point in creating ''yet another'' how-to for this so we'll keep this brief. TLS/SSL was enabled in the webserver by first installing the <tt>mod_ssl</tt> package and configuring a key pair in <tt>/etc/httpd/conf.d/ssl.conf</tt>.

When running <tt>[[Getting Started with EPrints 3|epadmin create]]</tt> supply a hostname for https connections. ''Contrary'' to a statement from [[Getting Started with EPrints 3]] ("If you will use https for your user pages (including login) enter the https hostname - '''No doubt, for secure usage you need another name'''", my emphasis) this can and probably should be your main EPrints hostname also used for plain HTTP.

(To change this after installation either edit <tt>archives/[repo_id]/cfg/cfg.d/10_core.pl</tt> or do as suggested in this file and run <tt>epadmin config_core [repo_id]</tt>. Note that leaving this to <tt>epadmin</tt> does ''not'' set or change any of the <tt>*root</tt> or <tt>*cgiroot</tt> statements which are mentioned [[HTTPS|in the wiki]]. Only <tt>$c->{securehost}</tt> seems to be needed.)

Since the EPrints RPM already containes <tt>/etc/httpd/conf.d/eprints.conf</tt> EPrints should already be working fine over plain HTTP. To make EPrints available over TLS/SSL as well include the auto-generated SSL-specific config ''inside'' httpd's existing SSL-vhost as defined in <tt>/etc/httpd/conf.d/ssl.conf</tt>:
Include /usr/share/eprints/cfg/apache_ssl.conf
Check httpd's config for syntax errors (<tt>apachtectl -t</tt>) and restart httpd.
EPrints should now work over both http and https.

=== Webserver authentication ===
To keep this document short(er) and generally useful, please refer to your webserver's or authentication system's documentation for installation and configuration. (Note: For Shibboleth you can [https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPLinuxRPMInstall install from RPMs] as well). We'll assume you have the desired unique identifier for a user available in httpd's <tt>REMOTE_USER</tt> variable, no matter what authentication system used.

== Configuration ==
=== Exclude 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 a 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 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 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.

=== Tell EPrints about it ===
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]]

Webserver authentication

2012-03-15T20:28:08Z

Sp: (provisional) URL for code and configuration

How to '''configure EPrints for authentication via the webserver'''. This enables/provides for
* re-use of externally managed ("enterprise") user accounts,
* automated Just-In-Time provisioning ("on-access provisioning"), instead of Just-In-Case (seperately managed batch processes)
* Web Single Sign-On to EPrints (with Shibboleth, CAS/<tt>mod_cas</tt>, Kerberos or just about any <tt>mod_auth_*</tt> Module for Apache httpd).
With small changes (not yet included below) EPrints user types (<tt>User</tt>, <tt>Editor</tt>, <tt>Repository Administrator</tt>) could also be assigned dynamically, based on data from an external authoritative source (e.g. an LDAP directory via <tt>Net::LDAP</tt> or an RDBMS via <tt>DBI</tt>) or recieved as SAML attributes (in case of Shibboleth).

== Conceptual overview ==
Here's how this integration works conceptually (not in order of steps performed). Filenames in parentheses refer to the files from http://files.eprints.org/738/
# Enable [[HTTPS]] for your webserver and the EPrints instance.
# Configure EPrints to send requests requiring authentication to a specific resource/URL, we'll assume <tt>/shibboleth/login</tt> below but this could be any string of your choice and is ''not'' visible to people logging in! (<tt>auth.pl</tt>)
# Make EPrints proper ignore these requests (<tt>archives/[repo_id]/cfg/cfg.d/20_baseurls.pl</tt>)
# Require authentication (and possibly also authorization) in the webserver for access to this resource (<tt>eprints-httpd-auth.conf</tt>)
# Add code to the installation which handles those pre-authenticated requests (<tt>login</tt>), creates new users and sessions, and returns to the originally requested resource.

Note that the recipe below does '''not''' provide a parallel authentication method for EPrints -- it completely replaces the default authentication method and login prompt. You can disable the new authentication method to change the user type of some (possibly newly created) user account to "repository administrator" afterwards (when logging in as eprints admin with local/database authentication). Alternatively make sure that a user account already exists within EPrints that is of user type "repository adminstrator" and has a username that can authenticate to the external authentication system (with Shibboleth you'd also need to make sure that this username is returned from the SAML Identity Provider and that the right, i.e., matching username is being mapped to httpd's <tt>REMOTE_USER</tt> variable).

A consequence of external authentication is that no self-registration of user accounts within EPrints is possible (or necessary, as many would see it) anymore, unless the system providing external authentication itself offers self-registration.

A word of warning: Don't enable this in a production EPrints instance unless either all existing users have matching usernames in your external authentication system, or you can live with the consequences of any and all users being auto-created (again) with different usernames (thereby possibly losing access to all their data, roles, etc.). Updating usernames in EPrints or other migration strategies are ''not'' considered below. Conversely make sure that none of the external usernames ''unintendedly'' match any local EPrints accounts with admin or "repository administrator" or "editor" privileges -- unless you expressly want them to have those privileges.

== Prerequisites ==
The EPrints instance this has been tested with was deployed from the latest [[Installing EPrints 3 on RedHat Enterprise 5|EPrints RPMs]] (which, at the time of writing, was at 3.3.7) on a newly installed RHEL6 machine. All paths and file names are hence based on an RPM install on RHEL5/6 and will need to be adapted to your webserver and EPrints installation and configuration.

Download the files from http://files.eprints.org/738/ and unpack them to a directory of choice, e.g.
cd /tmp
wget http://files.eprints.org/738/1/webserver-auth.tgz
tar xvzf webserver-auth.tgz
cd webserver-auth

=== TLS/SSL ===
[[:Category:Authentication|SSL and HTTPS and Secure logins]] have been covered numerous times in this wiki, but most of the material is outdated and some seems horribly cumbersome (or both). Still, there's no point in creating ''yet another'' how-to for this so we'll keep this brief. TLS/SSL was enabled in the webserver by first installing the <tt>mod_ssl</tt> package and configuring a key pair in <tt>/etc/httpd/conf.d/ssl.conf</tt>.

When running <tt>[[Getting Started with EPrints 3|epadmin create]]</tt> supply a hostname for https connections. ''Contrary'' to a statement from [[Getting Started with EPrints 3]] ("If you will use https for your user pages (including login) enter the https hostname - '''No doubt, for secure usage you need another name'''", my emphasis) this can and probably should be your main EPrints hostname also used for plain HTTP.

(To change this after installation either edit <tt>archives/[repo_id]/cfg/cfg.d/10_core.pl</tt> or do as suggested in this file and run <tt>epadmin config_core [repo_id]</tt>. Note that leaving this to <tt>epadmin</tt> does ''not'' set or change any of the <tt>*root</tt> or <tt>*cgiroot</tt> statements which are mentioned [[HTTPS|in the wiki]]. Only <tt>$c->{securehost}</tt> seems to be needed.)

Since the EPrints RPM already containes <tt>/etc/httpd/conf.d/eprints.conf</tt> EPrints should already be working fine over plain HTTP. To make EPrints available over TLS/SSL as well include the auto-generated SSL-specific config ''inside'' httpd's existing SSL-vhost as defined in <tt>/etc/httpd/conf.d/ssl.conf</tt>:
Include /usr/share/eprints/cfg/apache_ssl.conf
Check httpd's config for syntax errors (<tt>apachtectl -t</tt>) and restart httpd.
EPrints should now work over both http and https.

=== Webserver authentication ===
To keep this document short(er) and generally useful, please refer to your webserver's or authentication system's documentation for installation and configuration. (Note: For Shibboleth you can [https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPLinuxRPMInstall install from RPMs] as well). We'll assume you have the desired unique identifier for a user available in httpd's <tt>REMOTE_USER</tt> variable, no matter what authentication system used.

== Configuration ==
=== Exclude 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 a 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 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 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.

=== Tell EPrints about it ===
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]]

Webserver authentication

2012-03-15T20:04:52Z

Sp: /* Tell EPrints about it */ deactive, more clearly

How to '''configure EPrints for authentication via the webserver'''. This enables/provides for
* re-use of externally managed ("enterprise") user accounts,
* automated Just-In-Time provisioning ("on-access provisioning"), instead of Just-In-Case (seperately managed batch processes)
* Web Single Sign-On to EPrints (with Shibboleth, CAS/<tt>mod_cas</tt>, Kerberos or just about any <tt>mod_auth_*</tt> Module for Apache httpd).
With small changes (not yet included below) EPrints user types (<tt>User</tt>, <tt>Editor</tt>, <tt>Repository Administrator</tt>) could also be assigned dynamically, based on data from an external authoritative source (e.g. an LDAP directory via <tt>Net::LDAP</tt> or an RDBMS via <tt>DBI</tt>) or recieved as SAML attributes (in case of Shibboleth).

== Conceptual overview ==
Here's how this integration works conceptually (not in order of steps performed). Filenames in parentheses refer to the files in/from FIXME:
# Enable [[HTTPS]] for your webserver and the EPrints instance.
# Configure EPrints to send requests requiring authentication to a specific resource/URL, we'll assume <tt>/shibboleth/login</tt> below but this could be any string of your choice and is ''not'' visible to people logging in! (<tt>auth.pl</tt>)
# Make EPrints proper ignore these requests (<tt>archives/[repo_id]/cfg/cfg.d/20_baseurls.pl</tt>)
# Require authentication (and possibly also authorization) in the webserver for access to this resource (<tt>eprints-httpd-auth.conf</tt>)
# Add code to the installation which handles those pre-authenticated requests (<tt>login</tt>), creates new users and sessions, and returns to the originally requested resource.

Note that the recipe below does '''not''' provide a parallel authentication method for EPrints -- it completely replaces the default authentication method and login prompt. You can disable the new authentication method to change the user type of some (possibly newly created) user account to "repository administrator" afterwards (when logging in as eprints admin with local/database authentication). Alternatively make sure that a user account already exists within EPrints that is of user type "repository adminstrator" and has a username that can authenticate to the external authentication system (with Shibboleth you'd also need to make sure that this username is returned from the SAML Identity Provider and that the right, i.e., matching username is being mapped to httpd's <tt>REMOTE_USER</tt> variable).

A consequence of external authentication is that no self-registration of user accounts within EPrints is possible (or necessary, as many would see it) anymore, unless the system providing external authentication itself offers self-registration.

A word of warning: Don't enable this in a production EPrints instance unless either all existing users have matching usernames in your external authentication system, or you can live with the consequences of any and all users being auto-created (again) with different usernames (thereby possibly losing access to all their data, roles, etc.). Updating usernames in EPrints or other migration strategies are ''not'' considered below. Conversely make sure that none of the external usernames ''unintendedly'' match any local EPrints accounts with admin or "repository administrator" or "editor" privileges -- unless you expressly want them to have those privileges.

== Prerequisites ==
The EPrints instance this has been tested with was deployed from the latest [[Installing EPrints 3 on RedHat Enterprise 5|EPrints RPMs]] (which, at the time of writing, was at 3.3.7) on a newly installed RHEL6 machine. All paths and file names are hence based on an RPM install on RHEL5/6 and will need to be adapted to your webserver and EPrints installation and configuration.

=== TLS/SSL ===
[[:Category:Authentication|SSL and HTTPS and Secure logins]] have been covered numerous times in this wiki, but most of the material is outdated and some seems horribly cumbersome (or both). Still, there's no point in creating ''yet another'' how-to for this so we'll keep this brief. TLS/SSL was enabled in the webserver by first installing the <tt>mod_ssl</tt> package and configuring a key pair in <tt>/etc/httpd/conf.d/ssl.conf</tt>.

When running <tt>[[Getting Started with EPrints 3|epadmin create]]</tt> supply a hostname for https connections. ''Contrary'' to a statement from [[Getting Started with EPrints 3]] ("If you will use https for your user pages (including login) enter the https hostname - '''No doubt, for secure usage you need another name'''", my emphasis) this can and probably should be your main EPrints hostname also used for plain HTTP.

(To change this after installation either edit <tt>archives/[repo_id]/cfg/cfg.d/10_core.pl</tt> or do as suggested in this file and run <tt>epadmin config_core [repo_id]</tt>. Note that leaving this to <tt>epadmin</tt> does ''not'' set or change any of the <tt>*root</tt> or <tt>*cgiroot</tt> statements which are mentioned [[HTTPS|in the wiki]]. Only <tt>$c->{securehost}</tt> seems to be needed.)

Since the EPrints RPM already containes <tt>/etc/httpd/conf.d/eprints.conf</tt> EPrints should already be working fine over plain HTTP. To make EPrints available over TLS/SSL as well include the auto-generated SSL-specific config ''inside'' httpd's existing SSL-vhost as defined in <tt>/etc/httpd/conf.d/ssl.conf</tt>:
Include /usr/share/eprints/cfg/apache_ssl.conf
Check httpd's config for syntax errors (<tt>apachtectl -t</tt>) and restart httpd.
EPrints should now work over both http and https.

=== Webserver authentication ===
To keep this document short(er) and generally useful, please refer to your webserver's or authentication system's documentation for installation and configuration. (Note: For Shibboleth you can [https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPLinuxRPMInstall install from RPMs] as well). We'll assume you have the desired unique identifier for a user available in httpd's <tt>REMOTE_USER</tt> variable, no matter what authentication system used.

== Configuration ==
=== Exclude 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 a 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 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 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.

=== Tell EPrints about it ===
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]]

Webserver authentication

2012-03-15T19:54:06Z

Sp: more disclaimers, choice of two login scripts, state use of RPM-based paths once

How to '''configure EPrints for authentication via the webserver'''. This enables/provides for
* re-use of externally managed ("enterprise") user accounts,
* automated Just-In-Time provisioning ("on-access provisioning"), instead of Just-In-Case (seperately managed batch processes)
* Web Single Sign-On to EPrints (with Shibboleth, CAS/<tt>mod_cas</tt>, Kerberos or just about any <tt>mod_auth_*</tt> Module for Apache httpd).
With small changes (not yet included below) EPrints user types (<tt>User</tt>, <tt>Editor</tt>, <tt>Repository Administrator</tt>) could also be assigned dynamically, based on data from an external authoritative source (e.g. an LDAP directory via <tt>Net::LDAP</tt> or an RDBMS via <tt>DBI</tt>) or recieved as SAML attributes (in case of Shibboleth).

== Conceptual overview ==
Here's how this integration works conceptually (not in order of steps performed). Filenames in parentheses refer to the files in/from FIXME:
# Enable [[HTTPS]] for your webserver and the EPrints instance.
# Configure EPrints to send requests requiring authentication to a specific resource/URL, we'll assume <tt>/shibboleth/login</tt> below but this could be any string of your choice and is ''not'' visible to people logging in! (<tt>auth.pl</tt>)
# Make EPrints proper ignore these requests (<tt>archives/[repo_id]/cfg/cfg.d/20_baseurls.pl</tt>)
# Require authentication (and possibly also authorization) in the webserver for access to this resource (<tt>eprints-httpd-auth.conf</tt>)
# Add code to the installation which handles those pre-authenticated requests (<tt>login</tt>), creates new users and sessions, and returns to the originally requested resource.

Note that the recipe below does '''not''' provide a parallel authentication method for EPrints -- it completely replaces the default authentication method and login prompt. You can disable the new authentication method to change the user type of some (possibly newly created) user account to "repository administrator" afterwards (when logging in as eprints admin with local/database authentication). Alternatively make sure that a user account already exists within EPrints that is of user type "repository adminstrator" and has a username that can authenticate to the external authentication system (with Shibboleth you'd also need to make sure that this username is returned from the SAML Identity Provider and that the right, i.e., matching username is being mapped to httpd's <tt>REMOTE_USER</tt> variable).

A consequence of external authentication is that no self-registration of user accounts within EPrints is possible (or necessary, as many would see it) anymore, unless the system providing external authentication itself offers self-registration.

A word of warning: Don't enable this in a production EPrints instance unless either all existing users have matching usernames in your external authentication system, or you can live with the consequences of any and all users being auto-created (again) with different usernames (thereby possibly losing access to all their data, roles, etc.). Updating usernames in EPrints or other migration strategies are ''not'' considered below. Conversely make sure that none of the external usernames ''unintendedly'' match any local EPrints accounts with admin or "repository administrator" or "editor" privileges -- unless you expressly want them to have those privileges.

== Prerequisites ==
The EPrints instance this has been tested with was deployed from the latest [[Installing EPrints 3 on RedHat Enterprise 5|EPrints RPMs]] (which, at the time of writing, was at 3.3.7) on a newly installed RHEL6 machine. All paths and file names are hence based on an RPM install on RHEL5/6 and will need to be adapted to your webserver and EPrints installation and configuration.

=== TLS/SSL ===
[[:Category:Authentication|SSL and HTTPS and Secure logins]] have been covered numerous times in this wiki, but most of the material is outdated and some seems horribly cumbersome (or both). Still, there's no point in creating ''yet another'' how-to for this so we'll keep this brief. TLS/SSL was enabled in the webserver by first installing the <tt>mod_ssl</tt> package and configuring a key pair in <tt>/etc/httpd/conf.d/ssl.conf</tt>.

When running <tt>[[Getting Started with EPrints 3|epadmin create]]</tt> supply a hostname for https connections. ''Contrary'' to a statement from [[Getting Started with EPrints 3]] ("If you will use https for your user pages (including login) enter the https hostname - '''No doubt, for secure usage you need another name'''", my emphasis) this can and probably should be your main EPrints hostname also used for plain HTTP.

(To change this after installation either edit <tt>archives/[repo_id]/cfg/cfg.d/10_core.pl</tt> or do as suggested in this file and run <tt>epadmin config_core [repo_id]</tt>. Note that leaving this to <tt>epadmin</tt> does ''not'' set or change any of the <tt>*root</tt> or <tt>*cgiroot</tt> statements which are mentioned [[HTTPS|in the wiki]]. Only <tt>$c->{securehost}</tt> seems to be needed.)

Since the EPrints RPM already containes <tt>/etc/httpd/conf.d/eprints.conf</tt> EPrints should already be working fine over plain HTTP. To make EPrints available over TLS/SSL as well include the auto-generated SSL-specific config ''inside'' httpd's existing SSL-vhost as defined in <tt>/etc/httpd/conf.d/ssl.conf</tt>:
Include /usr/share/eprints/cfg/apache_ssl.conf
Check httpd's config for syntax errors (<tt>apachtectl -t</tt>) and restart httpd.
EPrints should now work over both http and https.

=== Webserver authentication ===
To keep this document short(er) and generally useful, please refer to your webserver's or authentication system's documentation for installation and configuration. (Note: For Shibboleth you can [https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPLinuxRPMInstall install from RPMs] as well). We'll assume you have the desired unique identifier for a user available in httpd's <tt>REMOTE_USER</tt> variable, no matter what authentication system used.

== Configuration ==
=== Exclude 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 a 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 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 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.

=== Tell EPrints about it ===
To finally activate (and deactivate, if you need to) the switch to webserver-based authentication copy <tt>auth.pl</tt> to <tt>archives/[repo_id]/cfg/cfg.d/</tt> and reload httpd.

[[Category:Authentication]]

Webserver authentication

2012-03-15T19:32:28Z

Sp: Created page with 'How to '''configure EPrints for authentication via the webserver'''. This enables/provides for * re-use of externally managed ("enterprise") user accounts, * automated Just-In-Ti…'

How to '''configure EPrints for authentication via the webserver'''. This enables/provides for
* re-use of externally managed ("enterprise") user accounts,
* automated Just-In-Time provisioning ("on-access provisioning"), instead of Just-In-Case (seperately managed batch processes)
* Web Single Sign-On to EPrints (with Shibboleth, CAS/<tt>mod_cas</tt>, Kerberos or just about any <tt>mod_auth_*</tt> Module for Apache httpd).
With small changes (not yet included below) EPrints user types (<tt>User</tt>, <tt>Editor</tt>, <tt>Repository Administrator</tt>) could also be assigned dynamically, based on data from an external authoritative source (e.g. an LDAP directory via <tt>Net::LDAP</tt> or an RDBMS via <tt>DBI</tt>) or recieved as SAML attributes (in case of Shibboleth).

== Conceptual overview ==
Here's how this integration works conceptually (not in order of steps performed). Filenames in parentheses refer to the files in/from FIXME:
# Enable [[HTTPS]] for your webserver and the EPrints instance.
# Configure EPrints to send requests requiring authentication to a specific resource/URL, we'll assume <tt>/shibboleth/login</tt> below but this could be any string of your choice and is ''not'' visible to people logging in! (<tt>auth.pl</tt>)
# Make EPrints proper ignore these requests (<tt>archives/[repo_id]/cfg/cfg.d/20_baseurls.pl</tt>)
# Require authentication (and possibly also authorization) in the webserver for access to this resource (<tt>eprints-httpd-auth.conf</tt>)
# Add code to the installation which handles those pre-authenticated requests (<tt>login</tt>), creates new users and sessions, and returns to the originally requested resource.

Note that the recipe below does '''not''' provide a parallel authentication method for EPrints -- it completely replaces the default authentication method and login prompt. You can disable the new authentication method to change the user type of some (possibly newly created) user account to "repository administrator" afterwards (when logging in as eprints admin with local/database authentication). Alternatively make sure that a user account already exists within EPrints that is of user type "repository adminstrator" and has a username that can authenticate to the external authentication system (with Shibboleth you'd also need to make sure that this username is returned from the SAML Identity Provider and that the right, i.e., matching username is being mapped to httpd's <tt>REMOTE_USER</tt> variable).

A word of warning: Don't enable this in a production EPrints instance unless either all existing users have matching usernames in your external authentication system, or you can live with the consequences of any and all users being auto-created (again) with different usernames (thereby possibly losing access to all their data, roles, etc.). Updating usernames in EPrints or other migration strategies are ''not'' considered below. Conversely make sure that none of the external usernames ''unintendedly'' match any local EPrints accounts with admin or "repository administrator" or "editor" privileges -- unless you expressly want them to have those privileges.

== Prerequisites ==
The EPrints instance this has been tested with was deployed from the latest [[Installing EPrints 3 on RedHat Enterprise 5|EPrints RPMs]] (which, at the time of writing, was at 3.3.7) on a newly installed RHEL6 machine.

=== TLS/SSL ===
[[:Category:Authentication|SSL and HTTPS and Secure logins]] have been covered numerous times in this wiki, but most of the material is outdated and some seems horribly cumbersome (or both). Still, there's no point in creating ''yet another'' how-to for this so we'll keep this brief. TLS/SSL was enabled in the webserver by first installing the <tt>mod_ssl</tt> package and configuring a key pair in <tt>/etc/httpd/conf.d/ssl.conf</tt>.

When running <tt>[[Getting Started with EPrints 3|epadmin create]]</tt> supply a hostname for https connections. ''Contrary'' to a statement from [[Getting Started with EPrints 3]] ("If you will use https for your user pages (including login) enter the https hostname - '''No doubt, for secure usage you need another name'''", my emphasis) this can and probably should be your main EPrints hostname also used for plain HTTP.

(To change this after installation either edit <tt>archives/[repo_id]/cfg/cfg.d/10_core.pl</tt> or do as suggested in this file and run <tt>epadmin config_core [repo_id]</tt>. Note that leaving this to <tt>epadmin</tt> does ''not'' set or change any of the <tt>*root</tt> or <tt>*cgiroot</tt> statements which are mentioned [[HTTPS|in the wiki]]. Only <tt>$c->{securehost}</tt> seems to be needed.)

Since the EPrints RPM already containes <tt>/etc/httpd/conf.d/eprints.conf</tt> EPrints should already be working fine over plain HTTP. To make EPrints available over TLS/SSL as well include the auto-generated SSL-specific config ''inside'' httpd's existing SSL-vhost as defined in <tt>/etc/httpd/conf.d/ssl.conf</tt> (assuming an RPM-based EPrints install):
Include /usr/share/eprints/cfg/apache_ssl.conf
Check httpd's config for syntax errors (<tt>apachtectl -t</tt>) and restart httpd.
EPrints should now work over both http and https.

=== Webserver authentication ===
To keep this document short(er) and generally useful, please refer to your webserver's or authentication system's documentation for installation and configuration. (Note: For Shibboleth you can [https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPLinuxRPMInstall install from RPMs] as well). We'll assume you have the desired unique identifier for a user available in httpd's <tt>REMOTE_USER</tt> variable, no matter what authentication system used.

== Configuration ==
=== Exclude 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 a 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 login script ===
Create a directory in your EPrints directory and copy the <tt>login</tt> script there (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 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 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.

=== Tell EPrints about it ===
To finally activate (and deactivate, if you need to) the switch to webserver-based authentication copy <tt>auth.pl</tt> to <tt>archives/[repo_id]/cfg/cfg.d/</tt> and reload httpd.

[[Category:Authentication]]

LDAP

2012-03-06T20:00:22Z

Sp: /* LDAP Authentication with On-Demand Creation of Users */ as reported by joel.rosental@imdea.org on Wed, 13 Jul 2011 via eprints-tech@ecs.soton.ac.uk

[[Category:Authentication]]

==LDAP Authentication==

===LDAP and User Roles===

It is recommended that certain user rights are removed when using LDAP for login. The user should not be allowed to change their password or their email address. It is also suggested that the user not be allowed to edit their profile, however I have found certain fields that I would like the user to edit. To set the rights edit the file :

vi /opt/eprints3/archives/yourarchivename/cfg/cfg.d/user_roles.pl

######################################################################
#
# User Roles
#
# Here you can configure which different types of user are
# parts of the system they are allowed to use.
#
######################################################################
$c->{user_roles}->{user} = [qw/
general
edit-own-record
saved-searches
deposit
/],
$c->{user_roles}->{editor} = [qw/
general
edit-own-record
saved-searches
deposit
editor
view-status
staff-view
/],
$c->{user_roles}->{admin} = [qw/
general
edit-own-record
saved-searches
set-password
deposit
change-email
editor
view-status
staff-view
admin
/],
#$c->{user_roles}->{minuser} = [qw/
# saved-searches
# set-password
# change-email
# change-user
# no_edit_own_record
# lock-username-to-email
#/];

After editing restart Apache.

===LDAP Authentication with Bulk Import of Users===

This recipe enables authenticating passwords against an LDAP directory for all users (including administrators). The users will need to already exist in EPrints, most likely created by a bulk import from your LDAP server.

The recommendation for EPrints is not to allow users to alter email and passwords, as these changes are not at present written back to the LDAP database.

====LDAP Configuration====

All changes for LDAP authentication can be made in a single file, the file contains useful notes on configuration. Here is an example from my site, I have configured a standard Samba Domain using LDAP for authentication, if you have similar then this config may work for you :

See [[user_login.pl]] for general information on check_user_password.

Edit the file :

vi /opt/eprints3/archives/yourarchivename/cfg/cfg.d/user_login.pl

# This function allows you to override the default username/password
# authentication. For example, you could apply different authentication rules to
# different types of user.
#
# Example: LDAP Authentication (Quick Start)
#
# Tip: use the test script to determine your LDAP parameters first!
# Tip: remove the set-password priviledge from users and editors in
# user_roles.pl. Also consider removing edit-own-record and
# change-email.
#
use Net::LDAP; # IO::Socket::SSL also required
use Net::LDAP::Util;

$c->{check_user_password} = sub {
my( $repo, $username, $password ) = @_;

my $user = $repo->user_by_username( $username );
return unless $user;

$username = $user->value( "username" );

my $user_type = $user->get_type;
if( $user_type eq "admin" )
{
# internal authentication for "admin" type
return $repo->database->valid_login( $username, $password );
}

# LDAP authentication for "user" and "editor" types
#
# LDAP hostname (and port if not the default)
my $ldap_host = "ldap.yourdomain.ac.uk";
#my $ldap_host = "ldap.host.name:1234";
#my $ldap_host = "ldaps://ldap.host.name"; # if server supports LDAPS

# Distinguished name for this user
# The distinguished name is a unique name for an LDAP entry.
# e.g. "cn=John Smith, ou=staff, dc=eprints, dc=org"
# You will need to derive this from the username or user metadata
my $ldap_dn = sprintf("uid=%s,ou=People,dc=example,dc=org",
Net::LDAP::Util::escape_dn_value($username)
);

my $ldap = Net::LDAP->new ( $ldap_host, version => 3 );
unless( $ldap )
{
$repo->log( "LDAP error: $@" );
return;
}

# Start secure connection (not needed if using LDAPS)
my $ssl = $ldap->start_tls( sslversion => "sslv3" );
if( $ssl->code() )
{
$repo->log( "LDAP SSL error: " . $ssl->error() );
return;
}
# Check password
my $mesg = $ldap->bind( $ldap_dn, password => $password );
if( $mesg->code() )
{
return;
}

return $username;
}
# Advanced LDAP Configuration
#
# 1. It is also possible to define additional user types, each with a different
# authentication mechanism. For example, you could keep the default user,
# editor and admin types and add ldapuser, ldapeditor and ldapadmin types with
# LDAP authentication - this would suit an arrangement where internal staff are
# authenticated against the LDAP server but user accounts can still be granted
# to external users.
#
# 2. Sometimes the distinguished name of the user is not computable from the
# username. You may need to use values from the user metadata (e.g. name_given,
# name_family):
#
# my $name = $user->get_value( "name" );
# my $ldap_dn = $name->{family} . ", " . $name->{given} .", ou=yourorg, dc=yourdomain";
#
# or perform an LDAP lookup to determine it (more complicated):
#
# my $base = "ou=yourorg, dc=yourdomain";
# my $result = $ldap->search (
# base => "$base",
# scope => "sub",
# filter => "cn=$username",
# attrs => ['DN'],
# sizelimit=>1
# );
#
# my $entr = $result->pop_entry;
# unless( defined $entr )
# {
# return 0;
# }
# my $ldap_dn = $entr->dn
#
# Alternatively, you could store the distinguished name as part of the user
# metadata when the user account is imported print STDERR "LDAP SSL error: " . $ssl->error() . "\n";

After editing restart Apache.

====LDAP Import====

You can use the [http://files.eprints.org/27/1/update_users update_users script] and apply the following patch to make it work with eprints3:

<pre>
--- update_users.orig 2007-04-23 16:22:26.000000000 +0200
+++ update_users 2007-04-24 21:16:40.000000000 +0200
@@ -1,6 +1,6 @@
-#!/usr/bin/perl -w -I/opt/eprints2/perl_lib
+#!/usr/bin/perl -w -I/opt/eprints3/perl_lib

-use EPrints::User;
+use EPrints::DataObj::User;
use EPrints::Session;
use Net::LDAP;
use strict;
@@ -16,6 +16,7 @@

# Start connection
my $ldap = Net::LDAP->new( "ldap.host.name", version => 3 );
+$ldap->start_tls();
unless( $ldap )
{
print STDERR "LDAP error: $@\n";
@@ -74,7 +75,7 @@
# New account
if( $forreal )
{
- $user = EPrints::User::create_user( $session, "ldapuser" );
+ $user = EPrints::DataObj::User::create( $session, "user" );
$user->set_value( "username", $username );
print "CREATING: $username\n";
}
@@ -118,7 +119,7 @@
print "FAMILY = " . $entr->get_value( "sn" ) . "\n";
print "GIVEN = " . $entr->get_value( "givenName" ) . "\n";
print "EMAIL = " . $entr->get_value( "mail" ) . "\n";
- print "DN = " . $entr->get_value( "distinguishedName" ) . "\n";
+ print "DN = " . $entr->dn . "\n";

}

</pre>

===LDAP Authentication with On-Demand Creation of Users===

Here's an example of a customized <tt>/opt/eprints3/archives/ARCHIVEID/cfg/cfg.d/user_login.pl</tt>

* allowing LDAP accounts to login, using the "Advanced LDAP Configuration" example
* allowing the local eprints admin account to login w/ database authentication
* creating eprints accounts for all successfully authenticated LDAP users ''on the fly''

Most of the code is from the default <tt>user_login.pl</tt> and from the [http://files.eprints.org/27/1/update_users update_users] script (which does not seem to exist anymore, but code & text below seem to have been written by [[User:Sp]] not later than May 7th 2007).

Be sure to only use this over [[HTTPS]]!

$c->{check_user_password} = sub {
my( $session, $username, $password ) = @_;

# LDAP authentication for "user", "editor" and "admin" types (roles)

use Net::LDAP; # IO::Socket::SSL also required

# LDAP tunables
my $ldap_host = "ldap.example.org";
my $base = "dc=example,dc=org";
my $dn = "cn=someProxyAccount,ou=accounts,$base";

my $ldap = Net::LDAP->new ( $ldap_host, version => 3 );
unless( $ldap )
{
print STDERR "LDAP error: $@\n";
return 0;
}

# Start secure connection (not needed if using LDAPS)
my $ssl = $ldap->start_tls();
if( $ssl->code() )
{
print STDERR "LDAP SSL error: " . $ssl->error() . "\n";
return 0;
}

# Get password for the search-bind-account
my $repository = $session->get_repository;
my $id = $repository->get_id;
my $ldappass = `cat /opt/eprints3/archives/$id/cfg/ldap.passwd`;
chomp($ldappass);

my $mesg = $ldap->bind( $dn, password=>$ldappass );
if( $mesg->code() )
{
print STDERR "LDAP Bind error: " . $mesg->error() . "\n";
return 0;
}

# Distinguished name (and attribues needed later on) for this user
my $result = $ldap->search (
base => "$base",
scope => "sub",
filter => "(&(uid=$username)(objectclass=inetOrgPerson))",
attrs => ['1.1', 'uid', 'sn', 'givenname', 'mail'],
sizelimit=>1
);
my $entr = $result->pop_entry;
unless( defined $entr )
{
# Allow local EPrints authentication for admins (accounts not found in LDAP)
my $user = EPrints::DataObj::User::user_with_username( $session, $username );
return 0 unless $user;

my $user_type = $user->get_type;
if( $user_type eq "admin" )
{
# internal authentication for "admin" type
return $session->get_database->valid_login( $username, $password );
}
return 0;
}
my $ldap_dn = $entr->dn;

# Check password
my $mesg = $ldap->bind( $ldap_dn, password => $password );
if( $mesg->code() )
{
return 0;
}

# Does account already exist?
my $user = EPrints::DataObj::User::user_with_username( $session, $username );
if( !defined $user )
{
# New account
$user = EPrints::DataObj::User::create( $session, "user" );
$user->set_value( "username", $username );
}

# Set metadata
my $name = {};
$name->{family} = $entr->get_value( "sn" );
$name->{given} = $entr->get_value( "givenName" );
$user->set_value( "name", $name );
$user->set_value( "username", $username );
$user->set_value( "email", $entr->get_value( "mail" ) );
$user->commit();

$ldap->unbind if $ldap;

return 1;
}

====Things to note====

* This script uses a dedicated proxy account which must exist in your LDAP tree and has appropriate permissions (ACL settings) to search for users and read their <tt>uid,givenname,sn,mail</tt> attributes.
* It gets this proxy accounts' password from a file inside the repository configuration. this file needs to have read permissions for the user your webserver runs as (e.g. <tt>www-data</tt> on Debian). Use file system permissions to protect this (e.g. <tt>chmod 400 ldap.passwd</tt>).
* It changes the flow of <tt>user_login.pl</tt> a little to only check for local ''admin'' accounts (no users or editors; we have them all in our LDAP tree) and only when no user is found for ldap authentication. This allows you to have your admins in LDAP (if you want) but still use the local admin for "promoting" other users to admins, among other things (which could also be done with a simple SQL <code>update</code> directly in the RDBMS). If you don't need the local admin, remove those lines and just <tt>return 0</tt> since no user was found in LDAP.
* you could change the default role for generated user accounts from <tt>user</tt>, if you really wanted.

====Possible enhancements====

Currently this script does not remove local eprints accounts from the database: when accounts get deleted from the LDAP database the corresponding local EPrints accounts sit around forever. But since login isn't possible anymore this is not a risk or of high priority.

Depending on your situation it may be enough to run some kind of cleanup script, e.g. once a year, that get's a list of all local EPrints accounts, loops over them and <code>$user->remove</code>s all those, which cannot be found in LDAP anymore (except for those where <code>$user_type eq 'admin'</code>, so you don't risk losing your local admins).

LDAP

2010-04-28T13:26:02Z

Sp: /* LDAP Authentication with On-Demand Creation of Users */ wiki edits removed all authorship info

See [[Integrating EPrints with LDAP]] for instructions for Eprints 2.*

==LDAP and User Roles==

It is recommended that certain user rights are removed when using LDAP for login. The user should not be allowed to change their password or their email address. It is also suggested that the user not be allowed to edit their profile, however I have found certain fields that I would like the user to edit. To set the rights edit the file :

vi /opt/eprints3/archives/yourarchivename/cfg/cfg.d/user_roles.pl

######################################################################
#
# User Roles
#
# Here you can configure which different types of user are
# parts of the system they are allowed to use.
#
######################################################################
$c->{user_roles}->{user} = [qw/
general
edit-own-record
saved-searches
deposit
/],
$c->{user_roles}->{editor} = [qw/
general
edit-own-record
saved-searches
deposit
editor
view-status
staff-view
/],
$c->{user_roles}->{admin} = [qw/
general
edit-own-record
saved-searches
set-password
deposit
change-email
editor
view-status
staff-view
admin
/],
#$c->{user_roles}->{minuser} = [qw/
# saved-searches
# set-password
# change-email
# change-user
# no_edit_own_record
# lock-username-to-email
#/];

After editing restart Apache.

==LDAP Authentication with Bulk Import of Users==

This recipe enables authenticating passwords against an LDAP directory for all users (including administrators). The users will need to already exist in EPrints, most likely created by a bulk import from your LDAP server.

The recommendation for EPrints is not to allow users to alter email and passwords, as these changes are not at present written back to the LDAP database.

===LDAP Configuration===

All changes for LDAP authentication can be made in a single file, the file contains useful notes on configuration. Here is an example from my site, I have configured a standard Samba Domain using LDAP for authentication, if you have similar then this config may work for you :

Edit the file :

vi /opt/eprints3/archives/yourarchivename/cfg/cfg.d/user_login.pl

# This function allows you to override the default username/password
# authentication. For example, you could apply different authentication rules to
# different types of user.
#
# Example: LDAP Authentication (Quick Start)
#
# Tip: use the test script to determine your LDAP parameters first!
# Tip: remove the set-password priviledge from users and editors in
# user_roles.pl. Also consider removing edit-own-record and
# change-email.
#
$c->{check_user_password} = sub {
my( $session, $username, $password ) = @_;
my $user = EPrints::DataObj::User::user_with_username( $session, $username );
return 0 unless $user;
my $user_type = $user->get_type;
if( $user_type eq "admin" )
{
# internal authentication for "admin" type
# return EPrints::Apache::Login::valid_login( $session, $username, $password );
return $session->get_database->valid_login( $username, $password );
}
# LDAP authentication for "user" and "editor" types
#
# LDAP hostname (and port if not the default)
my $ldap_host = "ldap.yourdomain.ac.uk";
# #my $ldap_host = "ldap.host.name:1234";
# #my $ldap_host = "ldaps://ldap.host.name"; # if server supports LDAPS
#
# Distinguished name for this user
# The distinguished name is a unique name for an LDAP entry.
# e.g. "cn=John Smith, ou=staff, dc=eprints, dc=org"
# You will need to derive this from the username or user metadata
my $ldap_dn = "uid=$username,ou=People,dc=yourdomain,dc=ac,dc=uk";
#
use Net::LDAP; # IO::Socket::SSL also required
#
my $ldap = Net::LDAP->new ( $ldap_host, version => 3 );
unless( $ldap )
{
print STDERR "LDAP error: $@\n";
return 0;
}
#
# Start secure connection (not needed if using LDAPS)
my $ssl = $ldap->start_tls( sslversion => "sslv3" );
if( $ssl->code() )
{
print STDERR "LDAP SSL error: " . $ssl->error() . "\n";
return 0;
}
# Check password
my $mesg = $ldap->bind( $ldap_dn, password => $password );
if( $mesg->code() )
{
return 0;
}
return 1;
}
# Advanced LDAP Configuration
#
# 1. It is also possible to define additional user types, each with a different
# authentication mechanism. For example, you could keep the default user,
# editor and admin types and add ldapuser, ldapeditor and ldapadmin types with
# LDAP authentication - this would suit an arrangement where internal staff are
# authenticated against the LDAP server but user accounts can still be granted
# to external users.
#
# 2. Sometimes the distinguished name of the user is not computable from the
# username. You may need to use values from the user metadata (e.g. name_given,
# name_family):
#
# my $name = $user->get_value( "name" );
# my $ldap_dn = $name->{family} . ", " . $name->{given} .", ou=yourorg, dc=yourdomain";
#
# or perform an LDAP lookup to determine it (more complicated):
#
# my $base = "ou=yourorg, dc=yourdomain";
# my $result = $ldap->search (
# base => "$base",
# scope => "sub",
# filter => "cn=$username",
# attrs => ['DN'],
# sizelimit=>1
# );
#
# my $entr = $result->pop_entry;
# unless( defined $entr )
# {
# return 0;
# }
# my $ldap_dn = $entr->dn
#
# Alternatively, you could store the distinguished name as part of the user
# metadata when the user account is imported print STDERR "LDAP SSL error: " . $ssl->error() . "\n";

After editing restart Apache.

===LDAP Import===

You can use the [http://files.eprints.org/27/1/update_users update_users script] and apply the following patch to make it work with eprints3:

<pre>
--- update_users.orig 2007-04-23 16:22:26.000000000 +0200
+++ update_users 2007-04-24 21:16:40.000000000 +0200
@@ -1,6 +1,6 @@
-#!/usr/bin/perl -w -I/opt/eprints2/perl_lib
+#!/usr/bin/perl -w -I/opt/eprints3/perl_lib

-use EPrints::User;
+use EPrints::DataObj::User;
use EPrints::Session;
use Net::LDAP;
use strict;
@@ -16,6 +16,7 @@

# Start connection
my $ldap = Net::LDAP->new( "ldap.host.name", version => 3 );
+$ldap->start_tls();
unless( $ldap )
{
print STDERR "LDAP error: $@\n";
@@ -74,7 +75,7 @@
# New account
if( $forreal )
{
- $user = EPrints::User::create_user( $session, "ldapuser" );
+ $user = EPrints::DataObj::User::create( $session, "user" );
$user->set_value( "username", $username );
print "CREATING: $username\n";
}
@@ -118,7 +119,7 @@
print "FAMILY = " . $entr->get_value( "sn" ) . "\n";
print "GIVEN = " . $entr->get_value( "givenName" ) . "\n";
print "EMAIL = " . $entr->get_value( "mail" ) . "\n";
- print "DN = " . $entr->get_value( "distinguishedName" ) . "\n";
+ print "DN = " . $entr->dn . "\n";

}

</pre>

==LDAP Authentication with On-Demand Creation of Users==

Here's an example of a customized <tt>/opt/eprints3/archives/ARCHIVEID/cfg/cfg.d/user_login.pl</tt>

* allowing LDAP accounts to login, using the "Advanced LDAP Configuration" example
* allowing the local eprints admin account to login w/ database authentication
* creating eprints accounts for all successfully authenticated LDAP users ''on the fly''

Most of the code is from the default <tt>user_login.pl</tt> and from the [http://files.eprints.org/27/1/update_users update_users] script (which does not seem to exist anymore, but code & text below seem to have been written by [[User:Sp]] not later than May 7th 2007).

Be sure to only use this over [[HTTPS]]!

$c->{check_user_password} = sub {
my( $session, $username, $password ) = @_;

# LDAP authentication for "user", "editor" and "admin" types (roles)

use Net::LDAP; # IO::Socket::SSL also required

# LDAP tunables
my $ldap_host = "ldap.example.org";
my $base = "dc=example,dc=org";
my $dn = "cn=someProxyAccount,ou=accounts,$base";

my $ldap = Net::LDAP->new ( $ldap_host, version => 3 );
unless( $ldap )
{
print STDERR "LDAP error: $@\n";
return 0;
}

# Start secure connection (not needed if using LDAPS)
my $ssl = $ldap->start_tls();
if( $ssl->code() )
{
print STDERR "LDAP SSL error: " . $ssl->error() . "\n";
return 0;
}

# Get password for the search-bind-account
my $repository = $session->get_repository;
my $id = $repository->get_id;
my $ldappass = `cat /opt/eprints3/archives/$id/cfg/ldap.passwd`;
chomp($ldappass);

my $mesg = $ldap->bind( $dn, password=>$password );
if( $mesg->code() )
{
print STDERR "LDAP Bind error: " . $mesg->error() . "\n";
return 0;
}

# Distinguished name (and attribues needed later on) for this user
my $result = $ldap->search (
base => "$base",
scope => "sub",
filter => "(&(uid=$username)(objectclass=inetOrgPerson))",
attrs => ['1.1', 'uid', 'sn', 'givenname', 'mail'],
sizelimit=>1
);
my $entr = $result->pop_entry;
unless( defined $entr )
{
# Allow local EPrints authentication for admins (accounts not found in LDAP)
my $user = EPrints::DataObj::User::user_with_username( $session, $username );
return 0 unless $user;

my $user_type = $user->get_type;
if( $user_type eq "admin" )
{
# internal authentication for "admin" type
return $session->get_database->valid_login( $username, $password );
}
return 0;
}
my $ldap_dn = $entr->dn;

# Check password
my $mesg = $ldap->bind( $ldap_dn, password => $password );
if( $mesg->code() )
{
return 0;
}

# Does account already exist?
my $user = EPrints::DataObj::User::user_with_username( $session, $username );
if( !defined $user )
{
# New account
$user = EPrints::DataObj::User::create( $session, "user" );
$user->set_value( "username", $username );
}

# Set metadata
my $name = {};
$name->{family} = $entr->get_value( "sn" );
$name->{given} = $entr->get_value( "givenName" );
$user->set_value( "name", $name );
$user->set_value( "username", $username );
$user->set_value( "email", $entr->get_value( "mail" ) );
$user->commit();

$ldap->unbind if $ldap;

return 1;
}

=== things to note ===

* This script uses a dedicated proxy account which must exist in your LDAP tree and has appropriate permissions (ACL settings) to search for users and read their <tt>uid,givenname,sn,mail</tt> attributes.
* It gets this proxy accounts' password from a file inside the repository configuration. this file needs to have read permissions for the user your webserver runs as (e.g. <tt>www-data</tt> on Debian). Use file system permissions to protect this (e.g. <tt>chmod 400 ldap.passwd</tt>).
* It changes the flow of <tt>user_login.pl</tt> a little to only check for local ''admin'' accounts (no users or editors; we have them all in our LDAP tree) and only when no user is found for ldap authentication. This allows you to have your admins in LDAP (if you want) but still use the local admin for "promoting" other users to admins, among other things (which could also be done with a simple SQL <code>update</code> directly in the RDBMS). If you don't need the local admin, remove those lines and just <tt>return 0</tt> since no user was found in LDAP.
* you could change the default role for generated user accounts from <tt>user</tt>, if you really wanted.

=== possible enhancements ===

Currently this script does not remove local eprints accounts from the database: when accounts get deleted from the LDAP database the corresponding local EPrints accounts sit around forever. But since login isn't possible anymore this is not a risk or of high priority.

Depending on your situation it may be enough to run some kind of cleanup script, e.g. once a year, that get's a list of all local EPrints accounts, loops over them and <code>$user->remove</code>s all those, which cannot be found in LDAP anymore (except for those where <code>$user_type eq 'admin'</code>, so you don't risk losing your local admins).

[[Category:Authentication]]

LDAP user login.pl

2007-04-24T22:52:24Z

Sp: bootstrapping admins: use SQL

== LDAP Authentication and Provisioning example ==
Here's an example of a customized <tt>/opt/eprints3/archives/ARCHIVEID/cfg/cfg.d/user_login.pl</tt>
* allowing LDAP accounts to login, using the "Advanced LDAP Configuration" example
* allowing the local eprints admin account to login w/ database authentication
* creating eprints accounts for all successfully authenticated LDAP users ''on the fly''
Most of the code is from the default <tt>user_login.pl</tt> and from the [http://files.eprints.org/27/1/update_users update_users] script.

Be sure to only use this over [[HTTPS]]!

$c->{check_user_password} = sub {
my( $session, $username, $password ) = @_;

# LDAP authentication for "user", "editor" and "admin" types (roles)

use Net::LDAP; # IO::Socket::SSL also required

# LDAP tunables
my $ldap_host = "ldap.example.org";
my $base = "dc=example,dc=org";
my $dn = "cn=someProxyAccount,ou=accounts,$base";

my $ldap = Net::LDAP->new ( $ldap_host, version => 3 );
unless( $ldap )
{
print STDERR "LDAP error: $@\n";
return 0;
}

# Start secure connection (not needed if using LDAPS)
my $ssl = $ldap->start_tls();
if( $ssl->code() )
{
print STDERR "LDAP SSL error: " . $ssl->error() . "\n";
return 0;
}

# Get password for the search-bind-account
my $repository = $session->get_repository;
my $id = $repository->get_id;
my $ldappass = `cat /opt/eprints3/archives/$id/cfg/ldap.passwd`;
chomp($ldappass);

my $mesg = $ldap->bind( $dn, password=>$password );
if( $mesg->code() )
{
print STDERR "LDAP Bind error: " . $mesg->error() . "\n";
return 0;
}

# Distinguished name (and attribues needed later on) for this user
my $result = $ldap->search (
base => "$base",
scope => "sub",
filter => "(&(uid=$username)(objectclass=inetOrgPerson))",
attrs => ['1.1', 'uid', 'sn', 'givenname', 'mail'],
sizelimit=>1
);
my $entr = $result->pop_entry;
unless( defined $entr )
{
# Allow local EPrints authentication for admins (accounts not found in LDAP)
my $user = EPrints::DataObj::User::user_with_username( $session, $username );
return 0 unless $user;

my $user_type = $user->get_type;
if( $user_type eq "admin" )
{
# internal authentication for "admin" type
return $session->get_database->valid_login( $username, $password );
}
return 0;
}
my $ldap_dn = $entr->dn;

# Check password
my $mesg = $ldap->bind( $ldap_dn, password => $password );
if( $mesg->code() )
{
return 0;
}

# Does account already exist?
my $user = EPrints::DataObj::User::user_with_username( $session, $username );
if( !defined $user )
{
# New account
$user = EPrints::DataObj::User::create( $session, "user" );
$user->set_value( "username", $username );
}

# Set metadata
my $name = {};
$name->{family} = $entr->get_value( "sn" );
$name->{given} = $entr->get_value( "givenName" );
$user->set_value( "name", $name );
$user->set_value( "username", $username );
$user->set_value( "email", $entr->get_value( "mail" ) );
$user->commit();

$ldap->unbind if $ldap;

return 1;
}

== things to note ==
* This script uses a dedicated proxy account which must exist in your LDAP tree and has appropriate permissions (ACL settings) to search for users and read their <tt>uid,givenname,sn,mail</tt> attributes.
* It get's this proxy accounts' password from a file inside the repository configuration. this file needs to have read permissions for the user your webserver runs as (e.g. <tt>www-data</tt> on Debian). Use file system permissions to protect this (e.g. <tt>chmod 400 ldap.passwd</tt>).
* It changes the flow of <tt>user_login.pl</tt> a little to only check for local ''admin'' accounts (no users or editors; we have them all in our LDAP tree) and only when no user is found for ldap authentication. This allows you to have your admins in LDAP (if you want) but still use the local admin for "promoting" other users to admins, among other things (which could also be done with a simple SQL <code>update</code> directly in the RDBMS). If you don't need the local admin, remove those lines and just <tt>return 0</tt> since no user was found in LDAP.
* you could change the default role for generated user accounts from <tt>user</tt>, if you really wanted.

== possible enhancements ==
=== removing stale accounts ===
Currently this script does not remove local eprints accounts from the database: when accounts get deleted from the LDAP database the corresponding local EPrints accounts sit around forever. But since login isn't possible anymore this is not a risk or of high priority.

Depending on your situation it may be enough to run some kind of cleanup script, e.g. once a year, that get's a list of all local EPrints accounts, loops over them and <code>$user->remove</code>s all those, which cannot be found in LDAP anymore (except for those where <code>$user_type eq 'admin'</code>, so you don't risk losing your local admins).

LDAP user login.pl

2007-04-24T22:48:44Z

Sp: /* possible enhancements */ more relevant use case

== LDAP Authentication and Provisioning example ==
Here's an example of a customized <tt>/opt/eprints3/archives/ARCHIVEID/cfg/cfg.d/user_login.pl</tt>
* allowing LDAP accounts to login, using the "Advanced LDAP Configuration" example
* allowing the local eprints admin account to login w/ database authentication
* creating eprints accounts for all successfully authenticated LDAP users ''on the fly''
Most of the code is from the default <tt>user_login.pl</tt> and from the [http://files.eprints.org/27/1/update_users update_users] script.

Be sure to only use this over [[HTTPS]]!

$c->{check_user_password} = sub {
my( $session, $username, $password ) = @_;

# LDAP authentication for "user", "editor" and "admin" types (roles)

use Net::LDAP; # IO::Socket::SSL also required

# LDAP tunables
my $ldap_host = "ldap.example.org";
my $base = "dc=example,dc=org";
my $dn = "cn=someProxyAccount,ou=accounts,$base";

my $ldap = Net::LDAP->new ( $ldap_host, version => 3 );
unless( $ldap )
{
print STDERR "LDAP error: $@\n";
return 0;
}

# Start secure connection (not needed if using LDAPS)
my $ssl = $ldap->start_tls();
if( $ssl->code() )
{
print STDERR "LDAP SSL error: " . $ssl->error() . "\n";
return 0;
}

# Get password for the search-bind-account
my $repository = $session->get_repository;
my $id = $repository->get_id;
my $ldappass = `cat /opt/eprints3/archives/$id/cfg/ldap.passwd`;
chomp($ldappass);

my $mesg = $ldap->bind( $dn, password=>$password );
if( $mesg->code() )
{
print STDERR "LDAP Bind error: " . $mesg->error() . "\n";
return 0;
}

# Distinguished name (and attribues needed later on) for this user
my $result = $ldap->search (
base => "$base",
scope => "sub",
filter => "(&(uid=$username)(objectclass=inetOrgPerson))",
attrs => ['1.1', 'uid', 'sn', 'givenname', 'mail'],
sizelimit=>1
);
my $entr = $result->pop_entry;
unless( defined $entr )
{
# Allow local EPrints authentication for admins (accounts not found in LDAP)
my $user = EPrints::DataObj::User::user_with_username( $session, $username );
return 0 unless $user;

my $user_type = $user->get_type;
if( $user_type eq "admin" )
{
# internal authentication for "admin" type
return $session->get_database->valid_login( $username, $password );
}
return 0;
}
my $ldap_dn = $entr->dn;

# Check password
my $mesg = $ldap->bind( $ldap_dn, password => $password );
if( $mesg->code() )
{
return 0;
}

# Does account already exist?
my $user = EPrints::DataObj::User::user_with_username( $session, $username );
if( !defined $user )
{
# New account
$user = EPrints::DataObj::User::create( $session, "user" );
$user->set_value( "username", $username );
}

# Set metadata
my $name = {};
$name->{family} = $entr->get_value( "sn" );
$name->{given} = $entr->get_value( "givenName" );
$user->set_value( "name", $name );
$user->set_value( "username", $username );
$user->set_value( "email", $entr->get_value( "mail" ) );
$user->commit();

$ldap->unbind if $ldap;

return 1;
}

== things to note ==
* This script uses a dedicated proxy account which must exist in your LDAP tree and has appropriate permissions (ACL settings) to search for users and read their <tt>uid,givenname,sn,mail</tt> attributes.
* It get's this proxy accounts' password from a file inside the repository configuration. this file needs to have read permissions for the user your webserver runs as (e.g. <tt>www-data</tt> on Debian). Use file system permissions to protect this (e.g. <tt>chmod 400 ldap.passwd</tt>).
* It changes the flow of <tt>user_login.pl</tt> a little to only check for local ''admin'' accounts (no users or editors; we have them all in our LDAP tree) and only when no user is found for ldap authentication. This allows you to have your admins in LDAP (if you want) but still use the local admin for "promoting" other users to admins, among other things. If you don't need the local admin, remove those lines and just <tt>return 0</tt>.
* you could change the default role for generated user accounts from <tt>user</tt>, if you really wanted.

== possible enhancements ==
=== removing stale accounts ===
Currently this script does not remove local eprints accounts from the database: when accounts get deleted from the LDAP database the corresponding local EPrints accounts sit around forever. But since login isn't possible anymore this is not a risk or of high priority.

Depending on your situation it may be enough to run some kind of cleanup script, e.g. once a year, that get's a list of all local EPrints accounts, loops over them and <code>$user->remove</code>s all those, which cannot be found in LDAP anymore (except for those where <code>$user_type eq 'admin'</code>, so you don't risk losing your local admins).

Integrating EPrints with LDAP

2007-04-24T21:45:20Z

Sp: eprints2 specific warning

'''Note''': some things on this page are specific to EPrints2. EPrints3 comes with example code in <tt>archives/ARCHIVEID/cfg/cfg.d/user_login.pl</tt> that just needs to be uncommented (and maybe customised). See [[LDAP]] or [[LDAP_user_login.pl]] for examples.
You also do not ''have'' to create ldapuser, ldapeditor and ldapadmin, you may also use the plain variants if you plan on using ''only'' LDAP accounts.

==Install Prerequisites==

Install the <tt>Net::LDAP</tt> and <tt>IO::Socket::SSL</tt> modules.

==Determine LDAP Setup==

The first step is to get Perl talking to your LDAP server. Determine the following parameters:

* the LDAP server name
* if the server doesn't support anonymous binds, a distinguished name (e.g. <tt>OU=jsmith, OU=users, DC=somewhere, DC=edu</tt>) and password to bind with
* the base name of user accounts (e.g. <tt>OU=users, DC=somewhere, DC=edu</tt>)
* the name of the username field (e.g. <tt>samaccountname</tt>, <tt>cn</tt>)

The <tt>http://files.eprints.org/27/01/ldaplookup</tt> script should get you started. Add your LDAP parameters to the script.

When run with an username as its parameter, <tt>ldaplookup</tt> should dump all the information associated with that account:

$ ./ldaplookup jsmith
Using LDAP protocol version 3
LDAP_EXTENSION_START_TLS supported
------------------------------------------------------------------------
dn:CN=jsmith,OU=users,DC=somewhere,DC=edu
objectClass: top
person
organizationalPerson
user
cn: jsmith
sn: Smith
...

You will probably need to tweak the LDAP parameters to suit your setup. See <tt>perldoc Net::LDAP</tt>.

==Configure user authentication==

The EPrints configuration lets you specify any number of user types (the defaults are "user", "editor" and "admin") each of which can be authorised in a different way. Suppose we want to have user, editor and admin accounts that are authorised by our LDAP server (i.e. internal staff) and also user, editor and admin accounts that are local to EPrints and authorised in the usual way (i.e. external users).

==Create new user types==

In <tt>/opt/eprints2/archives/ARCHIVEID/cfg/metadata-types.xml</tt>, copy and paste the existing user, editor, and admin types and change their names to ldapuser, ldapeditor and ldapadmin:

<dataset name="user">
<type name="ldapuser" >
<field name="password" />
<field name="username" staffonly="yes"/>
...
</type>
<type name="ldapeditor" >
<field name="password" />
<field name="username" staffonly="yes"/>
...
</type>
<type name="ldapadmin" >
<field name="password" />
<field name="usertype" staffonly="yes" />
...
</type>
<type name="user" >
<field name="password" />
<field name="usertype" staffonly="yes"/>
...
</type>
<type name="editor" >
<field name="password" />
<field name="usertype" staffonly="yes" />
...
</type>
<type name="admin" >
<field name="password" />
<field name="username" staffonly="yes" />
...
</type>
</dataset>

==Define user citation styles==

Define citation styles for the new user types in <tt>/opt/eprints2/archives/ARCHIVEID/cfg/citations-en.xml</tt>:

Just copy and paste the citation types for user_user, user_editor and user_admin and rename them to user_ldapuser, user_ldapeditor and user_ldapadmin.

==Define user typenames==

Define typenames for the new user types in <tt>/opt/eprints2/archives/ARCHIVEID/cfg/phrases-en.xml</tt>:

Just copy and paste the phrases for user_typename_user, user_typename_editor and user_typename_admin and rename them to user_typename_ldapuser, user_typename_ldapeditor and user_typename_ldapadmin.

Then, adjust the three new phrases values, e.g., the phrase value for the user_typename_ldapuser could be changed from "User" to "LDAP User".

==Configure user authentication==

Now configure user authentication in <tt>/opt/eprints2/archives/ARCHIVEID/cfg/ArchiveConfig.pm</tt>:

my $LDAP = { handler => \&ldapauthen };

$c->{userauth} = {
user => {
auth => $CRYPTED_DBI,
priv => [ "subscription", "set-password", "deposit", "change-email", "change-user" ] },
editor => {
auth => $CRYPTED_DBI,
priv => [ "subscription", "set-password", "deposit", "change-email", "change-user",
"view-status", "editor", "staff-view" ] },
admin => {
auth => $CRYPTED_DBI,
priv => [ "subscription", "set-password", "deposit", "change-email", "change-user",
"view-status", "editor", "staff-view",
"edit-subject", "edit-user" ] },
ldapuser => {
auth => $LDAP,
priv => [ "subscription", "set-password", "deposit", "change-user","no_edit_own_record" ] },
ldapeditor => {
auth => $LDAP,
priv => [ "subscription", "set-password", "deposit", "change-user","no_edit_own_record",
"view-status", "editor", "staff-view" ] },
ldapadmin => {
auth => $LDAP,
priv => [ "subscription", "set-password", "deposit", "change-user",
"view-status", "editor", "staff-view", "edit-user" ] },
};

Here, the default user, editor and admin user types are still authenticated using the usual <tt>$CRYPTED_DBI</tt> construct, whereas ldapuser, ldapeditor and ldapadmin are authenticated by the <tt>$LDAP</tt> construct that we defined.

==Define LDAP authentication function==

Add the <tt>ldapauthen</tt> function to the end of <tt>ArchiveConfig.pm</tt>, filling in your LDAP settings:

use Net::LDAP;
BEGIN {
eval "use Apache::Const ':common'" || eval "use Apache2::Const ':common'";
}

sub ldapauthen
{
my ($r) = @_;
my ($key, $val, $dbh);

return OK unless $r->is_initial_req; # only the first internal request

my($res, $passwd_sent) = $r->get_basic_auth_pw;
return $res if $res; # e.g. HTTP_UNAUTHORIZED

# get username
my ($user_sent) = $r->user;

my $ldap = Net::LDAP->new ( "ldap.host.name", version=>3 );
$ldap->start_tls( sslversion=>'sslv2' );

unless( $ldap )
{
print STDERR "$@";
return SERVER_ERROR;
}

# If the distinguished name of the user is not
# computable from the username, perform a lookup
# to determine the distinguished name

my $mesg = $ldap->bind;
# If your LDAP server doesn't allow anonymous binds
# supply the dn/password of a valid account here
# (e.g. an 'eprints' account created specially for
# this purpose)
#my $dn = "";
#my $pword = "";
#my $mesg = $ldap->bind( $dn, password=>$pword );

my $base = "ou=user, dc=somewhere, dc=edu";
my $result = $ldap->search (
base => "$base",
scope => "sub",
filter => "cn=$user_sent",
attrs => ['DN'],
sizelimit=>1
);

my $entr = $result->pop_entry;
unless( defined $entr )
{
$r->note_basic_auth_failure;
return AUTH_REQUIRED;
}

# Bind with the distinguished name and password of the user
# If the distinguished name of the user is computable, this
# is the only step required
my $mesg2 = $ldap->bind( $entr->dn, password=>$passwd_sent );
if( $mesg2->code )
{
$r->note_basic_auth_failure;
return AUTH_REQUIRED;
}

return OK;
}

==Reload configuration==

Restart the apache server to reload the new configuration.

==Import user accounts from LDAP==

The final step is to import existing user accounts from the LDAP server.

The <tt>http://files.eprints.org/27/01/update_users</tt> script should get you started. Copy it to the <tt>/opt/eprints2/bin</tt> directory and add your LDAP settings.

Set <tt>$forreal</tt> to 1 to make changes to the database.

==Notes==

* If you see a "Sizelimit exceeded" error, you may need to import users in smaller batches, for example a faculty/dept at a time.
* <tt>update_users</tt> should be scheduled regularly using <tt>cron</tt> to keep EPrints in sync with the LDAP server
* For EPrints3 you will need to update two lines below;
*: <tt>Line 3:</tt> use EPrints::DataObj::User; #use EPrints::User;
*: <tt>Line 77:</tt> $user = EPrints::DataObj::User::create($session,"ldapuser"); #$user = EPrints::User::create_user( $session, "ldapuser" );

LDAP user login.pl

2007-04-24T21:26:31Z

Sp: /* LDAP Authentication and Provisioning example */ $id probably has not trailing \n

== LDAP Authentication and Provisioning example ==
Here's an example of a customized <tt>/opt/eprints3/archives/ARCHIVEID/cfg/cfg.d/user_login.pl</tt>
* allowing LDAP accounts to login, using the "Advanced LDAP Configuration" example
* allowing the local eprints admin account to login w/ database authentication
* creating eprints accounts for all successfully authenticated LDAP users ''on the fly''
Most of the code is from the default <tt>user_login.pl</tt> and from the [http://files.eprints.org/27/1/update_users update_users] script.

Be sure to only use this over [[HTTPS]]!

$c->{check_user_password} = sub {
my( $session, $username, $password ) = @_;

# LDAP authentication for "user", "editor" and "admin" types (roles)

use Net::LDAP; # IO::Socket::SSL also required

# LDAP tunables
my $ldap_host = "ldap.example.org";
my $base = "dc=example,dc=org";
my $dn = "cn=someProxyAccount,ou=accounts,$base";

my $ldap = Net::LDAP->new ( $ldap_host, version => 3 );
unless( $ldap )
{
print STDERR "LDAP error: $@\n";
return 0;
}

# Start secure connection (not needed if using LDAPS)
my $ssl = $ldap->start_tls();
if( $ssl->code() )
{
print STDERR "LDAP SSL error: " . $ssl->error() . "\n";
return 0;
}

# Get password for the search-bind-account
my $repository = $session->get_repository;
my $id = $repository->get_id;
my $ldappass = `cat /opt/eprints3/archives/$id/cfg/ldap.passwd`;
chomp($ldappass);

my $mesg = $ldap->bind( $dn, password=>$password );
if( $mesg->code() )
{
print STDERR "LDAP Bind error: " . $mesg->error() . "\n";
return 0;
}

# Distinguished name (and attribues needed later on) for this user
my $result = $ldap->search (
base => "$base",
scope => "sub",
filter => "(&(uid=$username)(objectclass=inetOrgPerson))",
attrs => ['1.1', 'uid', 'sn', 'givenname', 'mail'],
sizelimit=>1
);
my $entr = $result->pop_entry;
unless( defined $entr )
{
# Allow local EPrints authentication for admins (accounts not found in LDAP)
my $user = EPrints::DataObj::User::user_with_username( $session, $username );
return 0 unless $user;

my $user_type = $user->get_type;
if( $user_type eq "admin" )
{
# internal authentication for "admin" type
return $session->get_database->valid_login( $username, $password );
}
return 0;
}
my $ldap_dn = $entr->dn;

# Check password
my $mesg = $ldap->bind( $ldap_dn, password => $password );
if( $mesg->code() )
{
return 0;
}

# Does account already exist?
my $user = EPrints::DataObj::User::user_with_username( $session, $username );
if( !defined $user )
{
# New account
$user = EPrints::DataObj::User::create( $session, "user" );
$user->set_value( "username", $username );
}

# Set metadata
my $name = {};
$name->{family} = $entr->get_value( "sn" );
$name->{given} = $entr->get_value( "givenName" );
$user->set_value( "name", $name );
$user->set_value( "username", $username );
$user->set_value( "email", $entr->get_value( "mail" ) );
$user->commit();

$ldap->unbind if $ldap;

return 1;
}

== things to note ==
* This script uses a dedicated proxy account which must exist in your LDAP tree and has appropriate permissions (ACL settings) to search for users and read their <tt>uid,givenname,sn,mail</tt> attributes.
* It get's this proxy accounts' password from a file inside the repository configuration. this file needs to have read permissions for the user your webserver runs as (e.g. <tt>www-data</tt> on Debian). Use file system permissions to protect this (e.g. <tt>chmod 400 ldap.passwd</tt>).
* It changes the flow of <tt>user_login.pl</tt> a little to only check for local ''admin'' accounts (no users or editors; we have them all in our LDAP tree) and only when no user is found for ldap authentication. This allows you to have your admins in LDAP (if you want) but still use the local admin for "promoting" other users to admins, among other things. If you don't need the local admin, remove those lines and just <tt>return 0</tt>.
* you could change the default role for generated user accounts from <tt>user</tt>, if you really wanted.

== possible enhancements ==
* Currently this script does not remove local eprints accounts from the database. If you limited login to EPrints with an LDAP attribute (e.g. <tt>allowedServices=eprints</tt>) you could authenticate first (without filtering for this attribute) and in the case of successful authentication check for the existance of the <tt>allowedServices</tt> attribute. If it's missing delete the local eprints user account (e.g. <tt>$user->remove</tt>) and <tt>return 0</tt>.

LDAP

2007-04-24T21:25:36Z

Sp: /* Introduction */ importing done, computers can be filtered

See [[Integrating EPrints with LDAP]] for instructions for Eprints 2.*

==Introduction==

I decided that importing all users from my LDAP repository was not a good idea, I run Samba and an import would mean setting up 75 computers with access to eprints (when not filtering these out). I now create each user that requires access and use LDAP for authentication. This means that my users still only need to remember one password.

The recommendation for Eprints is not to allow users to alter email and passwords, as these changes are not at present written back to the LDAP database.

==LDAP Configuration==

All changes for LDAP authentication can be made in a single file, the file contains useful notes on configuration. Here is an example from my site, I have configured a standard Samba Domain using LDAP for authentication, if you have similar then this config may work for you :

Edit the file :

vi /var/lib/eprints3/archives/yourarchivename/cfg/cfg.d/user_login.pl

# This function allows you to override the default username/password
# authentication. For example, you could apply different authentication rules to
# different types of user.
#
# Example: LDAP Authentication (Quick Start)
#
# Tip: use the test script to determine your LDAP parameters first!
# Tip: remove the set-password priviledge from users and editors in
# user_roles.pl. Also consider removing edit-own-record and
# change-email.
#
$c->{check_user_password} = sub {
my( $session, $username, $password ) = @_;
my $user = EPrints::DataObj::User::user_with_username( $session, $username );
return 0 unless $user;
my $user_type = $user->get_type;
if( $user_type eq "admin" )
{
# internal authentication for "admin" type
# return EPrints::Apache::Login::valid_login( $session, $username, $password );
return $session->get_database->valid_login( $username, $password );
}
# LDAP authentication for "user" and "editor" types
#
# LDAP hostname (and port if not the default)
my $ldap_host = "ldap.yourdomain.ac.uk";
# #my $ldap_host = "ldap.host.name:1234";
# #my $ldap_host = "ldaps://ldap.host.name"; # if server supports LDAPS
#
# Distinguished name for this user
# The distinguished name is a unique name for an LDAP entry.
# e.g. "cn=John Smith, ou=staff, dc=eprints, dc=org"
# You will need to derive this from the username or user metadata
my $ldap_dn = "uid=$username,ou=People,dc=yourdomain,dc=ac,dc=uk";
#
use Net::LDAP; # IO::Socket::SSL also required
#
my $ldap = Net::LDAP->new ( $ldap_host, version => 3 );
unless( $ldap )
{
print STDERR "LDAP error: $@\n";
return 0;
}
#
# Start secure connection (not needed if using LDAPS)
my $ssl = $ldap->start_tls( sslversion => "sslv3" );
if( $ssl->code() )
{
print STDERR "LDAP SSL error: " . $ssl->error() . "\n";
return 0;
}
# Check password
my $mesg = $ldap->bind( $ldap_dn, password => $password );
if( $mesg->code() )
{
return 0;
}
return 1;
}
# Advanced LDAP Configuration
#
# 1. It is also possible to define additional user types, each with a different
# authentication mechanism. For example, you could keep the default user,
# editor and admin types and add ldapuser, ldapeditor and ldapadmin types with
# LDAP authentication - this would suit an arrangement where internal staff are
# authenticated against the LDAP server but user accounts can still be granted
# to external users.
#
# 2. Sometimes the distinguished name of the user is not computable from the
# username. You may need to use values from the user metadata (e.g. name_given,
# name_family):
#
# my $name = $user->get_value( "name" );
# my $ldap_dn = $name->{family} . ", " . $name->{given} .", ou=yourorg, dc=yourdomain";
#
# or perform an LDAP lookup to determine it (more complicated):
#
# my $base = "ou=yourorg, dc=yourdomain";
# my $result = $ldap->search (
# base => "$base",
# scope => "sub",
# filter => "cn=$username",
# attrs => ['DN'],
# sizelimit=>1
# );
#
# my $entr = $result->pop_entry;
# unless( defined $entr )
# {
# return 0;
# }
# my $ldap_dn = $entr->dn
#
# Alternatively, you could store the distinguished name as part of the user
# metadata when the user account is imported print STDERR "LDAP SSL error: " . $ssl->error() . "\n";

After editing restart Apache.

==LDAP and User Roles==

It is recommended that certain user rights are removed when using LDAP for login. The user should not be allowed to change their password or their email address. It is also suggested that the user not be allowed to edit their profile, however I have found certain fields that I would like the user to edit. To set the rights edit the file :

vi /var/lib/eprints3/archives/yourarchivename/cfg/cfg.d/user_roles.pl

######################################################################
#
# User Roles
#
# Here you can configure which different types of user are
# parts of the system they are allowed to use.
#
######################################################################
$c->{user_roles}->{user} = [qw/
general
edit-own-record
saved-searches
deposit
/],
$c->{user_roles}->{editor} = [qw/
general
edit-own-record
saved-searches
deposit
editor
view-status
staff-view
/],
$c->{user_roles}->{admin} = [qw/
general
edit-own-record
saved-searches
set-password
deposit
change-email
editor
view-status
staff-view
admin
/],
#$c->{user_roles}->{minuser} = [qw/
# saved-searches
# set-password
# change-email
# change-user
# no_edit_own_record
# lock-username-to-email
#/];

After editing restart Apache.

==LDAP Import==

[[LDAP_user_login.pl]] automagically creates eprints accounts on demand (i.e. after login), but you could also just use the [http://files.eprints.org/27/1/update_users update_users script] and apply the following patch to make it work with eprints3:

<pre>
--- update_users.orig 2007-04-23 16:22:26.000000000 +0200
+++ update_users 2007-04-24 21:16:40.000000000 +0200
@@ -1,6 +1,6 @@
-#!/usr/bin/perl -w -I/opt/eprints2/perl_lib
+#!/usr/bin/perl -w -I/opt/eprints3/perl_lib

-use EPrints::User;
+use EPrints::DataObj::User;
use EPrints::Session;
use Net::LDAP;
use strict;
@@ -16,6 +16,7 @@

# Start connection
my $ldap = Net::LDAP->new( "ldap.host.name", version => 3 );
+$ldap->start_tls();
unless( $ldap )
{
print STDERR "LDAP error: $@\n";
@@ -74,7 +75,7 @@
# New account
if( $forreal )
{
- $user = EPrints::User::create_user( $session, "ldapuser" );
+ $user = EPrints::DataObj::User::create( $session, "user" );
$user->set_value( "username", $username );
print "CREATING: $username\n";
}
@@ -118,7 +119,7 @@
print "FAMILY = " . $entr->get_value( "sn" ) . "\n";
print "GIVEN = " . $entr->get_value( "givenName" ) . "\n";
print "EMAIL = " . $entr->get_value( "mail" ) . "\n";
- print "DN = " . $entr->get_value( "distinguishedName" ) . "\n";
+ print "DN = " . $entr->dn . "\n";

}

</pre>

LDAP user login.pl

2007-04-24T19:18:54Z

Sp: https!

== LDAP Authentication and Provisioning example ==
Here's an example of a customized <tt>/opt/eprints3/archives/ARCHIVEID/cfg/cfg.d/user_login.pl</tt>
* allowing LDAP accounts to login, using the "Advanced LDAP Configuration" example
* allowing the local eprints admin account to login w/ database authentication
* creating eprints accounts for all successfully authenticated LDAP users ''on the fly''
Most of the code is from the default <tt>user_login.pl</tt> and from the [http://files.eprints.org/27/1/update_users update_users] script.

Be sure to only use this over [[HTTPS]]!

$c->{check_user_password} = sub {
my( $session, $username, $password ) = @_;

# LDAP authentication for "user", "editor" and "admin" types (roles)

use Net::LDAP; # IO::Socket::SSL also required

# LDAP tunables
my $ldap_host = "ldap.example.org";
my $base = "dc=example,dc=org";
my $dn = "cn=someProxyAccount,ou=accounts,$base";

my $ldap = Net::LDAP->new ( $ldap_host, version => 3 );
unless( $ldap )
{
print STDERR "LDAP error: $@\n";
return 0;
}

# Start secure connection (not needed if using LDAPS)
my $ssl = $ldap->start_tls();
if( $ssl->code() )
{
print STDERR "LDAP SSL error: " . $ssl->error() . "\n";
return 0;
}

# Get password for the search-bind-account
my $repository = $session->get_repository;
my $id = $repository->get_id;
chomp($id);
my $ldappass = `cat /opt/eprints3/archives/$id/cfg/ldap.passwd`;
chomp($ldappass);

my $mesg = $ldap->bind( $dn, password=>$password );
if( $mesg->code() )
{
print STDERR "LDAP Bind error: " . $mesg->error() . "\n";
return 0;
}

# Distinguished name (and attribues needed later on) for this user
my $result = $ldap->search (
base => "$base",
scope => "sub",
filter => "(&(uid=$username)(objectclass=inetOrgPerson))",
attrs => ['1.1', 'uid', 'sn', 'givenname', 'mail'],
sizelimit=>1
);
my $entr = $result->pop_entry;
unless( defined $entr )
{
# Allow local EPrints authentication for admins (accounts not found in LDAP)
my $user = EPrints::DataObj::User::user_with_username( $session, $username );
return 0 unless $user;

my $user_type = $user->get_type;
if( $user_type eq "admin" )
{
# internal authentication for "admin" type
return $session->get_database->valid_login( $username, $password );
}
return 0;
}
my $ldap_dn = $entr->dn;

# Check password
my $mesg = $ldap->bind( $ldap_dn, password => $password );
if( $mesg->code() )
{
return 0;
}

# Does account already exist?
my $user = EPrints::DataObj::User::user_with_username( $session, $username );
if( !defined $user )
{
# New account
$user = EPrints::DataObj::User::create( $session, "user" );
$user->set_value( "username", $username );
}

# Set metadata
my $name = {};
$name->{family} = $entr->get_value( "sn" );
$name->{given} = $entr->get_value( "givenName" );
$user->set_value( "name", $name );
$user->set_value( "username", $username );
$user->set_value( "email", $entr->get_value( "mail" ) );
$user->commit();

$ldap->unbind if $ldap;

return 1;
}

== things to note ==
* This script uses a dedicated proxy account which must exist in your LDAP tree and has appropriate permissions (ACL settings) to search for users and read their <tt>uid,givenname,sn,mail</tt> attributes.
* It get's this proxy accounts' password from a file inside the repository configuration. this file needs to have read permissions for the user your webserver runs as (e.g. <tt>www-data</tt> on Debian). Use file system permissions to protect this (e.g. <tt>chmod 400 ldap.passwd</tt>).
* It changes the flow of <tt>user_login.pl</tt> a little to only check for local ''admin'' accounts (no users or editors; we have them all in our LDAP tree) and only when no user is found for ldap authentication. This allows you to have your admins in LDAP (if you want) but still use the local admin for "promoting" other users to admins, among other things. If you don't need the local admin, remove those lines and just <tt>return 0</tt>.
* you could change the default role for generated user accounts from <tt>user</tt>, if you really wanted.

== possible enhancements ==
* Currently this script does not remove local eprints accounts from the database. If you limited login to EPrints with an LDAP attribute (e.g. <tt>allowedServices=eprints</tt>) you could authenticate first (without filtering for this attribute) and in the case of successful authentication check for the existance of the <tt>allowedServices</tt> attribute. If it's missing delete the local eprints user account (e.g. <tt>$user->remove</tt>) and <tt>return 0</tt>.

LDAP

2007-04-24T19:14:51Z

Sp: /* LDAP Import */ patching update_users for eprints3

See [[Integrating EPrints with LDAP]] for instructions for Eprints 2.*

==Introduction==

I am hoping that someone will add to this document regarding the importing of users. I decided that importing all users from my LDAP repository was not a good idea, I run Samba and an import would mean setting up 75 computers with access to eprints. I now create each user that requires access and use LDAP for authentication. This means that my users still only need to remember one password.

The recommendation for Eprints is not to allow users to alter email and passwords, as these changes are not at present written back to the LDAP database.

==LDAP Configuration==

All changes for LDAP authentication can be made in a single file, the file contains useful notes on configuration. Here is an example from my site, I have configured a standard Samba Domain using LDAP for authentication, if you have similar then this config may work for you :

Edit the file :

vi /var/lib/eprints3/archives/yourarchivename/cfg/cfg.d/user_login.pl

# This function allows you to override the default username/password
# authentication. For example, you could apply different authentication rules to
# different types of user.
#
# Example: LDAP Authentication (Quick Start)
#
# Tip: use the test script to determine your LDAP parameters first!
# Tip: remove the set-password priviledge from users and editors in
# user_roles.pl. Also consider removing edit-own-record and
# change-email.
#
$c->{check_user_password} = sub {
my( $session, $username, $password ) = @_;
my $user = EPrints::DataObj::User::user_with_username( $session, $username );
return 0 unless $user;
my $user_type = $user->get_type;
if( $user_type eq "admin" )
{
# internal authentication for "admin" type
# return EPrints::Apache::Login::valid_login( $session, $username, $password );
return $session->get_database->valid_login( $username, $password );
}
# LDAP authentication for "user" and "editor" types
#
# LDAP hostname (and port if not the default)
my $ldap_host = "ldap.yourdomain.ac.uk";
# #my $ldap_host = "ldap.host.name:1234";
# #my $ldap_host = "ldaps://ldap.host.name"; # if server supports LDAPS
#
# Distinguished name for this user
# The distinguished name is a unique name for an LDAP entry.
# e.g. "cn=John Smith, ou=staff, dc=eprints, dc=org"
# You will need to derive this from the username or user metadata
my $ldap_dn = "uid=$username,ou=People,dc=yourdomain,dc=ac,dc=uk";
#
use Net::LDAP; # IO::Socket::SSL also required
#
my $ldap = Net::LDAP->new ( $ldap_host, version => 3 );
unless( $ldap )
{
print STDERR "LDAP error: $@\n";
return 0;
}
#
# Start secure connection (not needed if using LDAPS)
my $ssl = $ldap->start_tls( sslversion => "sslv3" );
if( $ssl->code() )
{
print STDERR "LDAP SSL error: " . $ssl->error() . "\n";
return 0;
}
# Check password
my $mesg = $ldap->bind( $ldap_dn, password => $password );
if( $mesg->code() )
{
return 0;
}
return 1;
}
# Advanced LDAP Configuration
#
# 1. It is also possible to define additional user types, each with a different
# authentication mechanism. For example, you could keep the default user,
# editor and admin types and add ldapuser, ldapeditor and ldapadmin types with
# LDAP authentication - this would suit an arrangement where internal staff are
# authenticated against the LDAP server but user accounts can still be granted
# to external users.
#
# 2. Sometimes the distinguished name of the user is not computable from the
# username. You may need to use values from the user metadata (e.g. name_given,
# name_family):
#
# my $name = $user->get_value( "name" );
# my $ldap_dn = $name->{family} . ", " . $name->{given} .", ou=yourorg, dc=yourdomain";
#
# or perform an LDAP lookup to determine it (more complicated):
#
# my $base = "ou=yourorg, dc=yourdomain";
# my $result = $ldap->search (
# base => "$base",
# scope => "sub",
# filter => "cn=$username",
# attrs => ['DN'],
# sizelimit=>1
# );
#
# my $entr = $result->pop_entry;
# unless( defined $entr )
# {
# return 0;
# }
# my $ldap_dn = $entr->dn
#
# Alternatively, you could store the distinguished name as part of the user
# metadata when the user account is imported print STDERR "LDAP SSL error: " . $ssl->error() . "\n";

After editing restart Apache.

==LDAP and User Roles==

It is recommended that certain user rights are removed when using LDAP for login. The user should not be allowed to change their password or their email address. It is also suggested that the user not be allowed to edit their profile, however I have found certain fields that I would like the user to edit. To set the rights edit the file :

vi /var/lib/eprints3/archives/yourarchivename/cfg/cfg.d/user_roles.pl

######################################################################
#
# User Roles
#
# Here you can configure which different types of user are
# parts of the system they are allowed to use.
#
######################################################################
$c->{user_roles}->{user} = [qw/
general
edit-own-record
saved-searches
deposit
/],
$c->{user_roles}->{editor} = [qw/
general
edit-own-record
saved-searches
deposit
editor
view-status
staff-view
/],
$c->{user_roles}->{admin} = [qw/
general
edit-own-record
saved-searches
set-password
deposit
change-email
editor
view-status
staff-view
admin
/],
#$c->{user_roles}->{minuser} = [qw/
# saved-searches
# set-password
# change-email
# change-user
# no_edit_own_record
# lock-username-to-email
#/];

After editing restart Apache.

==LDAP Import==

[[LDAP_user_login.pl]] automagically creates eprints accounts on demand (i.e. after login), but you could also just use the [http://files.eprints.org/27/1/update_users update_users script] and apply the following patch to make it work with eprints3:

<pre>
--- update_users.orig 2007-04-23 16:22:26.000000000 +0200
+++ update_users 2007-04-24 21:16:40.000000000 +0200
@@ -1,6 +1,6 @@
-#!/usr/bin/perl -w -I/opt/eprints2/perl_lib
+#!/usr/bin/perl -w -I/opt/eprints3/perl_lib

-use EPrints::User;
+use EPrints::DataObj::User;
use EPrints::Session;
use Net::LDAP;
use strict;
@@ -16,6 +16,7 @@

# Start connection
my $ldap = Net::LDAP->new( "ldap.host.name", version => 3 );
+$ldap->start_tls();
unless( $ldap )
{
print STDERR "LDAP error: $@\n";
@@ -74,7 +75,7 @@
# New account
if( $forreal )
{
- $user = EPrints::User::create_user( $session, "ldapuser" );
+ $user = EPrints::DataObj::User::create( $session, "user" );
$user->set_value( "username", $username );
print "CREATING: $username\n";
}
@@ -118,7 +119,7 @@
print "FAMILY = " . $entr->get_value( "sn" ) . "\n";
print "GIVEN = " . $entr->get_value( "givenName" ) . "\n";
print "EMAIL = " . $entr->get_value( "mail" ) . "\n";
- print "DN = " . $entr->get_value( "distinguishedName" ) . "\n";
+ print "DN = " . $entr->dn . "\n";

}

</pre>

LDAP user login.pl

2007-04-24T19:06:25Z

Sp: example from vienna university

== LDAP Authentication and Provisioning example ==
Here's an example of a customized <tt>/opt/eprints3/archives/ARCHIVEID/cfg/cfg.d/user_login.pl</tt>
* allowing LDAP accounts to login, using the "Advanced LDAP Configuration" example
* allowing the local eprints admin account to login w/ database authentication
* creating eprints accounts for all successfully authenticated LDAP users ''on the fly''
Most of the code is from the default <tt>user_login.pl</tt> and from the [http://files.eprints.org/27/1/update_users update_users] script.

$c->{check_user_password} = sub {
my( $session, $username, $password ) = @_;

# LDAP authentication for "user", "editor" and "admin" types (roles)

use Net::LDAP; # IO::Socket::SSL also required

# LDAP tunables
my $ldap_host = "ldap.example.org";
my $base = "dc=example,dc=org";
my $dn = "cn=someProxyAccount,ou=accounts,$base";

my $ldap = Net::LDAP->new ( $ldap_host, version => 3 );
unless( $ldap )
{
print STDERR "LDAP error: $@\n";
return 0;
}

# Start secure connection (not needed if using LDAPS)
my $ssl = $ldap->start_tls();
if( $ssl->code() )
{
print STDERR "LDAP SSL error: " . $ssl->error() . "\n";
return 0;
}

# Get password for the search-bind-account
my $repository = $session->get_repository;
my $id = $repository->get_id;
chomp($id);
my $ldappass = `cat /opt/eprints3/archives/$id/cfg/ldap.passwd`;
chomp($ldappass);

my $mesg = $ldap->bind( $dn, password=>$password );
if( $mesg->code() )
{
print STDERR "LDAP Bind error: " . $mesg->error() . "\n";
return 0;
}

# Distinguished name (and attribues needed later on) for this user
my $result = $ldap->search (
base => "$base",
scope => "sub",
filter => "(&(uid=$username)(objectclass=inetOrgPerson))",
attrs => ['1.1', 'uid', 'sn', 'givenname', 'mail'],
sizelimit=>1
);
my $entr = $result->pop_entry;
unless( defined $entr )
{
# Allow local EPrints authentication for admins (accounts not found in LDAP)
my $user = EPrints::DataObj::User::user_with_username( $session, $username );
return 0 unless $user;

my $user_type = $user->get_type;
if( $user_type eq "admin" )
{
# internal authentication for "admin" type
return $session->get_database->valid_login( $username, $password );
}
return 0;
}
my $ldap_dn = $entr->dn;

# Check password
my $mesg = $ldap->bind( $ldap_dn, password => $password );
if( $mesg->code() )
{
return 0;
}

# Does account already exist?
my $user = EPrints::DataObj::User::user_with_username( $session, $username );
if( !defined $user )
{
# New account
$user = EPrints::DataObj::User::create( $session, "user" );
$user->set_value( "username", $username );
}

# Set metadata
my $name = {};
$name->{family} = $entr->get_value( "sn" );
$name->{given} = $entr->get_value( "givenName" );
$user->set_value( "name", $name );
$user->set_value( "username", $username );
$user->set_value( "email", $entr->get_value( "mail" ) );
$user->commit();

$ldap->unbind if $ldap;

return 1;
}

== things to note ==
* This script uses a dedicated proxy account which must exist in your LDAP tree and has appropriate permissions (ACL settings) to search for users and read their <tt>uid,givenname,sn,mail</tt> attributes.
* It get's this proxy accounts' password from a file inside the repository configuration. this file needs to have read permissions for the user your webserver runs as (e.g. <tt>www-data</tt> on Debian). Use file system permissions to protect this (e.g. <tt>chmod 400 ldap.passwd</tt>).
* It changes the flow of <tt>user_login.pl</tt> a little to only check for local ''admin'' accounts (no users or editors; we have them all in our LDAP tree) and only when no user is found for ldap authentication. This allows you to have your admins in LDAP (if you want) but still use the local admin for "promoting" other users to admins, among other things. If you don't need the local admin, remove those lines and just <tt>return 0</tt>.
* you could change the default role for generated user accounts from <tt>user</tt>, if you really wanted.

== possible enhancements ==
* Currently this script does not remove local eprints accounts from the database. If you limited login to EPrints with an LDAP attribute (e.g. <tt>allowedServices=eprints</tt>) you could authenticate first (without filtering for this attribute) and in the case of successful authentication check for the existance of the <tt>allowedServices</tt> attribute. If it's missing delete the local eprints user account (e.g. <tt>$user->remove</tt>) and <tt>return 0</tt>.

Installing GDOME

2007-04-12T18:46:42Z

Sp: /* See Also */

{{manual}}

Since EPrints 2.2 you may use either XML::DOM or XML::GDOME. XML::GDOME is recommended as it's faster and uses much less RAM, but it does require you to install a whole lot of extra libraries and perl modules. If you are running a pilot or demonstration service then XML::DOM is fine, and you can always switch over later by installing the required tools and setting the GDOME flag in perl_lib/EPrints/SystemSettings.pm

===Addional Libraries Required for GDOME support===

<code>
libxml2
libxml2-devel
</code>
either get the tarball from: ftp://ftp.gnome.org/pub/GNOME/sources/libxml2/

or the RPMs (but we have had problems with complex RPM dependencies):

<code>
http://rpmfind.net/linux/rpm2html/search.php?query=libxml2
http://rpmfind.net/linux/rpm2html/search.php?query=libxml2-devel
</code>
===The GDOME Library===
Obtain this from

<code>
http://gdome2.cs.unibo.it/#downloads
</code>
You may either use the RPMs (gdome2 and gdome2-devel) or the tarball.

===Additional Perl Modules Required for GDOME support===

<code>
XML-LibXML-Common
XML-NamespaceSupport
XML-GDOME
</code>
All of which are in http://www.cpan.org/modules/by-module/XML/

=== See Also ===

*[[Installing GDOME on Redhat 7]]
*[[Installing GDOME on Fedora Core 3]]
*[[Installing GDOME on Debian]]

User:Sp

2007-02-14T18:08:40Z

Sp:

Peter Schober, UNIX Sysadmin<br>
University of Vienna, Austria

Autocompletion

2007-02-13T23:53:07Z

Sp: /* The autocompletion instructions */ typo

{{reference}}

For a how-to, please see [[Autocompletion and Authority Files (Romeo Autocomplete)]]

Autocompletion in EPrints 3 consists of serveral stages.

* A field in the workflow is configured to say what autocompletion URL to use, plus any additional parameters to pass to the script. This URL must be on the same server (eg. foo.eprints.org) but does not have to be part of the EPrints system.
* The autocomplete script takes the text typed so far (and maybe the additional parameters) and returns a chunk of XML describing possible autocomplete options. This XML consists of a number of rows (how many is up to the script).
* Each row contains some HTML to show the person viewing plus a magic <nowiki><ul></nowiki> block which is hidden from display, but is used by the autocomplete javascript to autocomplete the page.

== Autocomplete Scripts ==

EPrints autocomplete scripts live in /opt/eprints3/cgi/users/lookup/ you can add your own here, or maybe elsewhere if, for example, you needed to use PHP.

There are several kinds of autocomplete scripts:
* thoses that just use the existing data in your repository (these are dead easy as they work out of the box)
* ones which use a file which you place in your repositories cfg/autocomplete/ directory.
* more clever ones.

You may be able to find new autocomplete scripts and authority files on http://files.eprints.org/

Scripts are in (rough) order of complexity to use...

=== journal_by_name ===

Can only be used on the "publication" field. Looks up the publication in the existing publications in the repository and autocompletes the publication. If ISSN and/or publisher exist in the same input component as the journal field they will also be completed if data is available.

=== journal_by_issn ===

As above, but attached to the ISSN field.

=== event_by_name ===

Similar to journal_by_name. Is attached to the event_title field and autocompletes from existing repository data. If they are in the same (multi) input component it will also try and autocomplete event_location, event_dates and event_type.

=== name ===

Attached to a multiple compound name/id field (eg. creators) looks up the name in the existing list in the repository. Can match on any id or given or family. Populates all parts of the current row it can.

=== title_duplicates ===

This is a slightly odd script as it doesn't actually provide any autocomplete data. What it does is search the list of existing titles to see if there is a match. It only searches if there are 5 or more characters entered so far.

If it finds any matches it lists them with a warning that they might be a problem, but does not assist autocompletion. If many matches are made then a short title only is shown, if the list is only 4 or lest then a full citation is shown.

This is set to "on" by default in the hope that it will reduce duplicate submissions.

=== simple_file ===

File needs an additional parameter to be passed to it. This is configured in the workflow. This parameter is the name of a file in the cfg/autocompete directory. This file contains a list of values which are searched (case insensitively) and matches returned. A second parameter of "mode=prefix" can be set to only match values which start with the text being typed, rather than contain it.

=== simple_sql ===

Similar to simple_file but gets its values from a database table.

The table must be in the eprints database used by this repository and start with "ac_". The script needs a param. passed from workflow to indicate the name of the table WITHOUT the ac_ prefix. Eg. if the table was "ac_badgers" the parameter would be "table=badgers". The only field used is "value" which works like the lines in the text file. If you want this to be blindingly fast you can make sure "value" is indexed, and set mode=prefix. With those set autocompleting from a dictionary of half a million words worked cheerfully.

=== romeo ===

(not included in 3.0, expected in 3.1) This script uses the EPrints/Romeo data to provide journal autocomplete data. Should be attached to the publication field. This is almost identical to file, but inserts the required Powered by Sherpa note.

=== url_name_value ===

This works like simple_sql except for the fact it uses three columns. url, name and value. It searches and autocompletes using value, but the human-readable description is supplied by "name" and if url is set then a (more info) link is shown. The link opens a new window to avoid mid-form trauma.

=== file ===

This is for more complex autocompletion authority files. It works like simple_file except that the file format is more complicated.

The file constists of lines which contan:
* a value to search, (eg. "African Journal of Agricultural Research")
* a tab
* a <nowiki><li></nowiki> autocomplete chunk. (with no line breaks) eg.
<nowiki> <li style='border-right: solid 50px #30FF30' >"African Journal of Agricultural
Research" published by "Academic Publishers"<br /><small>(a Green
publisher)</small>ISSN: 1991-637X<ul><li id="for:value:component:_publication">African
Journal of Agricultural Research</li><li id="for:value:component:_publisher">Academic
Publishers</li><li id="for:value:component:_issn">1991-637X</li></ul></li></nowiki>

See below for more information on the meaning of this arcane chunk!

=== sql ===

As for simple_sql except that a second column named "xml" is used to provide the actual results returned (value is still searched).

The xml column contains data in the autocomplete <nowiki><li></nowiki> format described below.

= Making a custom script =

Autocompletion scripts are configured to eprint fields within the workflow. If the field is multiple then the same script is attached to each input row.

The only parameter you need to look at is "q" which contains the text being autocompleted. For simple fields (eg. text), that is ones which only have one input-box per value. Not names, compound or pagerange etc.. the response should be of the format:
<nowiki>
<?xml version="1.0" encoding="UTF-8" ?>
<ul>
<li class="ep_first">Human Friendly Text <ul><li id='for:value:relative:'>text-to-insert</li></ul><li>
<li>Human Friendly Text <ul><li id='for:value:relative:'>text-to-insert</li></ul><li>
<li>Human Friendly Text <ul><li id='for:value:relative:'>text-to-insert</li></ul><li>
<li>Human Friendly Text <ul><li id='for:value:relative:'>text-to-insert</li></ul><li>
etc.
</ul></nowiki>

The ep_first isn't really needed, but it makes the rendering look a little nicer.

== Other useful CGI parameters ==

All parts of the field (or field row in multiple fields) get sent as CGI parameters. The name of these parameters is the ID of the HTML input element itself, but with the relative prefix removed (phew!).

Simple example: title field. One single value. It's not relevant, just use "q".

More complex example: pagerange field. While you were typing in the "to" box (the second one). It would send "?q=45&_from=12&_to=45". Obviously the numbers are made up. q= will always be the same as one of the values.

Even more complex example: creators field. Which is a multiple compound field. Parts sent would be q, _id, _name_given and _name_family.

For an explanation of how the id's are generated, and what a relative prefix is, see [[Understanding IDs in Workflow Forms]].

== The autocompletion instructions ==

The instructions for ''what'' to autocomplete if the row is selected is contained in the <ul> list inside the <li>.

Each item in the list is a single instruction.

Each item in the list has an id attribute containing instructions on what to autocomplete. (yes that means repeated id values which is bad XML and we'll fix it in a later version...)

The value inside the item describes what to insert, the id describes where and how.

The id looks like this:

"for:" + ("block" or "value") + ":" + ("relative" or "component" or "absolute") + ":" + freetext

Examples:

id="for:value:relative:"
id="for:value:relative:_name_family"
id="for:value:component:_issn"
id="for:block:absolute:my_special_id"

"value" means insert the value into an <input> element (with the indicated id).

"block" means replace the block with the indicated id.

"component" means that the freetext is the ID to modify, but missing the component prefix. For example "_issn" gives "id7_issn" (assuming id7 is the current component)

"relative" means the freetext is the ID to modify but missing the row prefix. For example in a multiple text field (foo) using "" for the free text would give an id of something like "id3_foo_4". For a single date field (birthday) a freetext of "_year" would give an id looking something like "id2_birthday_year".

"absolute" means that the freetext is the ID to modify. Absolute is a bit risky, as you can't rely on getting the same component prefix every time. It does, however, give you the chance to do Cool Stuff<sup>TM</sup>. For example add a XHTML input compontent just containing: <tt><nowiki><div id="special_comments"></div></nowiki></tt> and then make part of the autocomplete <tt><nowiki><li id="for:block:absolute:special_comments"><p>Hi Mom!</p></li></nowiki></tt> (but something more relevant, obviously)

=== How are these ID's generated anyway? ===

See [[Understanding IDs in Workflow Forms]].

=== What happens if the ID doesn't exist? ===

Nothing, the autocompleter does not raise an error. It just autocompletes all the things it can. This is handy if the workflow changes slightly, but makes debugging a bit trickier.

=== Some examples ===

Please note these examples have line breaks in which is illegal in the "file" script files (but not in SQL or in custom scripts).

<nowiki><li style='border-right: solid 50px #30FF30'>
"African Journal of Biotechnology" published by "Academic Publishers"<br />
<small>(a Green publisher)</small>ISSN: 1684-5315
<ul>
<li id="for:value:component:_publication">African Journal of Biotechnology</li>
<li id="for:value:component:_publisher">Academic Publishers</li>
<li id="for:value:component:_issn">1684-5315</li>
</ul>
</li></nowiki>

The above example autocompletes the issn, publication and publisher (text) fields in the current component.

<nowiki><li>
B. Draut
<small>(author of 3 items in this repository)</small>
<ul>
<li id="for:value:relative:_name_family">Draut</li>
<li id="for:value:relative:_name_given">B.</li>
<li id="for:value:relative:_name_honourific"/>
<li id="for:value:relative:_name_lineage"/>
<li id="for:value:relative:_id">434533X</li>
</ul>
</li></nowiki>

This completes relative to the current row of a compound field the compound is a name field (called name) and a text field (called id). This is the config. for the creators and editors fields by default. Note that it tries to autocomplete the honourific field even though it doesn't exist and it's got no value to autocomplete. This means that if it happens to exist, this autocompletion will remove any text from the field.

= Don't Forget to Share! =

If you write a really useful autocomplete script, or a useful data file for "file" or "simple_file", why not upload it to http://files.eprints.org/ so lots more people can benefit!

Frequently Asked Questions

2007-02-13T23:43:08Z

Sp: even more style...

This all needs sorting out, it's just being grabbed from the old wiki for now.

* [[Copyright and License FAQ]]
* [[Metadata FAQ]]
* [[Searching FAQ]]
* [[OAI FAQ]]
* [[BOAI Self-Archiving FAQ]]
* [[How much will it cost?]]

== What operating systems can we use? ==

EPrints should work on any UNIX operating system. We use Redhat Enterprise Linux. It will work on OSX but that takes a bit more effort. Please refer to the [http://www.eprints.org/documentation/handbook/osx.php Mac OS X Installation Guide] for more information

It will not run under Microsoft Windows and we have no plan to change this.

== What computer do we need? ==

Any new PC is easily powerful enough. Suggested minimum spec. for a live service: 1gig RAM, 20gig Harddrive, 1GHz+ processor.

== How much will it cost to set up? ==

Most of the costs are staff time. Equipment costs are a PC, an internet connection and a BACKUP STRATEGY. Please remember to budget for backups.

EPrints, and all the other software required to make it work, are available for no cost. At some point in the future EPrints may offer some pay-services, but the core software will remain zero cost and freely available to all.

See [[How much will it cost?]]

== How much diskspace will we need? ==

Proabably about 2 megabytes per eprint. At the time of writing a 120GB drive costs 50 pounds. That drive would hold approximately 60000 eprints.

See also: [[Detailed disk usage statistics]].

== Is it possible when depositing a document, to just point to an "alternative location" rather than have the full text copied and held in the eprint archive? ==

Yes, just don't assign any value to required_formats in ArchiveConfigure.pm, like so

$c->{required_formats} = [];

If you are doing this it would also be clever to change the ArchiveRender routines so that on the abstract page "Full text available as" is replaced by "Full text available via <link to alternative location>".

This keeps the key link to follow (to the full text) at the top of the screen.

== I need to run apache as a user other than "eprints", what do I do to make EPrints work in this situation? ==

Example, apache is running as user "apache".
* Make all the eprints files owned by "apache" instead of "eprints"
* Edit SystemSettings?.pm to tell eprints to run as user "apache"
* You'll need to run all command line scripts as user "apache"
* All eprints cron jobs should be owned by user "apache"

If you are installing a new copy of eprints, you can specify the user and group to use when you run 'configure'. Do

./configure --help

for details.

== How do I get the body HTML of a page without the template around it? ==

This is handy for dymnamically linking eprints content into other sites.

For "view" pages you need to add the option include=>1 to the view configuration. This will cause generate_views to make a .include page in addition to the .html page. The .include page will have no template around it.

For dynamic pages, those under /perl/, you can add the cgi parameter mainonly=yes

eg. http://eprints.ecs.soton.ac.uk/perl/latest?mainonly=yes

== How do I get statistics on number of deposits per month? ==

This rather grim bit of SQL should work, although datestamp is the last modified date, not the submission OR creation date, it should still give a good indication.

select count(*), year(datestamp), month(datestamp)
from archive
group by year(datestamp),month(datestamp)
order by year(datestamp),month(datestamp);

== I've edited the template (or other config file) but nothing seems to have changed - why? ==

See [[HowEPrintsGeneratesWebPages]]

----

= Installation Related Questions =

== What platforms will GNU EPrints run on? ==

In theory any UNIX like platform: Linux, Solaris, BSD etc. even OSX! If you don't care then we recommend the RedHat Linux distribution.

== When running a script I get the error; "Insecure dependency in mkdir while running with -T switch" ==

This usually indicates you are running an eprints script as root. Don't do that; become user 'eprints' instead.

== Errors with import_subjects when installing Eprints 2.3.3 with MySQL 4 ==

MySQL 4 does not grant permission to create temporary tables with <tt>GRANT ALL</tt>. Do (at the mysql prompt):
GRANT CREATE TEMPORARY TABLES ON archive_name.* TO eprints@localhost IDENTIFIED BY "*******";
replacing "archive_name" and "******" with your eprints mysql database name and user password. Then do:
mysqladmin [-u root -p] reload
to reload the mysql security tables.

== title and fulltext search returns no results, but date search does (EPrints 2.3) ==

The indexer daemon is probably not running or is not working correctly.

Syntax error on line 39 of /opt/eprints2/archives/eprintsOfGoat/cfg/auto-apache.conf:
order takes one argument, 'allow,deny', 'deny,allow', or 'mutual-failure' on restart of Apache after initial installation

There is a small error in the auto-apache.conf file, there is a space between 'deny, allow' on line 39, remove this space to stop this error.

== I don't want to give configure_archive my mysql root password. What is the alternative? ==

(instructions acurate as of EP 2.3.12)

Run configure_archive but say "no" to "create the database?"

Log into the mysql client as root:

% mysql -u root -p
Enter password:

(and enter your password)

This example creates a database for archive "foo" with user "foouser" and password "foopass".

These values should match the values you gave to configure_archive. You can check them in /opt/eprints2/archives/foo.xml

mysql> CREATE DATABASE foo;
Query OK, 1 row affected (0.06 sec)

mysql> GRANT ALL ON foo.* TO foouser@localhost;
Query OK, 0 rows affected (0.52 sec)

The last bit depends if you are running on a MySQL?
;version >= 4.1
mysql> SET PASSWORD FOR foouser@localhost = OLD_PASSWORD("foopass");

;version < 4.1
mysql> SET PASSWORD FOR foouser@localhost = PASSWORD("foopass");

That's all <tt>configure_archive</tt> would have done.

----

== How do I get a value for a field of an eprint (without using any SQL)? ==

(assuming the eprint is in the main archive, and has eprintid number 23)

my $ds = $session->get_archive()->get_dataset( "archive" );
my $eprint = EPrints::EPrint?->new( $session, 23, $ds );
my $value = $eprint->get_value( 'editors' );

== How can I get a utf8 string of the name of a subject, given its subjectid? ==

<pre>
sub get_subject_name_string
{
my( $session, $subjectid ) = @_;
my $subj = EPrints::Subject->new( $session, $subjectid );
if( !defined $subj )
{
return "errer, unknown subject: $subjectid";
}
return EPrints::Utils::tree_to_utf8( $subj->render_description() );
}
</pre>

...

== Using mod_perl2, pages with redirects (e.g. /perl/search) are blank. How do I fix this? ==

In perl_lib/EPrints/Session.pm change

$self->{"request"}->status_line( "302 Moved" );

to
$self->{"request"}->status(302);

Frequently Asked Questions

2007-02-13T23:33:29Z

Sp: /* When running a script I get the error; "Insecure dependency in mkdir while running with -T switch" */ style

This all needs sorting out, it's just being grabbed from the old wiki for now.

* [[Copyright and License FAQ]]
* [[Metadata FAQ]]
* [[Searching FAQ]]
* [[OAI FAQ]]
* [[BOAI Self-Archiving FAQ]]
* [[How much will it cost?]]

== What operating systems can we use? ==

EPrints should work on any UNIX operating system. We use Redhat Enterprise Linux. It will work on OSX but that takes a bit more effort. Please refer to the [http://www.eprints.org/documentation/handbook/osx.php Mac OS X Installation Guide] for more information

It will not run under Microsoft Windows and we have no plan to change this.

== What computer do we need? ==

Any new PC is easily powerful enough. Suggested minimum spec. for a live service: 1gig RAM, 20gig Harddrive, 1GHz+ processor.

== How much will it cost to set up? ==

Most of the costs are staff time. Equipment costs are a PC, an internet connection and a BACKUP STRATEGY. Please remember to budget for backups.

EPrints, and all the other software required to make it work, are available for no cost. At some point in the future EPrints may offer some pay-services, but the core software will remain zero cost and freely available to all.

See [[How much will it cost?]]

== How much diskspace will we need? ==

Proabably about 2 megabytes per eprint. At the time of writing a 120GB drive costs 50 pounds. That drive would hold approximately 60000 eprints.

See also: [[Detailed disk usage statistics]].

== Is it possible when depositing a document, to just point to an "alternative location" rather than have the full text copied and held in the eprint archive? ==

Yes, just don't assign any value to required_formats in ArchiveConfigure.pm, like so

$c->{required_formats} = [];

If you are doing this it would also be clever to change the ArchiveRender routines so that on the abstract page "Full text available as" is replaced by "Full text available via <link to alternative location>".

This keeps the key link to follow (to the full text) at the top of the screen.

== I need to run apache as a user other than "eprints", what do I do to make EPrints work in this situation? ==

Example, apache is running as user "apache".
* Make all the eprints files owned by "apache" instead of "eprints"
* Edit SystemSettings?.pm to tell eprints to run as user "apache"
* You'll need to run all command line scripts as user "apache"
* All eprints cron jobs should be owned by user "apache"

If you are installing a new copy of eprints, you can specify the user and group to use when you run 'configure'. Do

./configure --help

for details.

== How do I get the body HTML of a page without the template around it? ==

This is handy for dymnamically linking eprints content into other sites.

For "view" pages you need to add the option include=>1 to the view configuration. This will cause generate_views to make a .include page in addition to the .html page. The .include page will have no template around it.

For dynamic pages, those under /perl/, you can add the cgi parameter mainonly=yes

eg.

http://eprints.ecs.soton.ac.uk/perl/latest?mainonly=yes

== How do I get statistics on number of deposits per month? ==

This rather grim bit of SQL should work, although datestamp is the last modified date, not the submission OR creation date, it should still give a good indication.

select count(*), year(datestamp), month(datestamp)
from archive
group by year(datestamp),month(datestamp)
order by year(datestamp),month(datestamp);

== I've edited the template (or other config file) but nothing seems to have changed - why? ==

See [[HowEPrintsGeneratesWebPages]]

----

=Installation Related Questions =

== What platforms will GNU EPrints run on? ==

In theory any UNIX like platform: Linux, Solaris, BSD etc. even OSX! If you don't care then we recommend the RedHat Linux distribution.

== When running a script I get the error; "Insecure dependency in mkdir while running with -T switch" ==

This usually indicates you are running an eprints script as root. Don't do that; become user 'eprints' instead.

== Errors with import_subjects when installing Eprints 2.3.3 with MySQL 4 ==

MySQL 4 does not grant permission to create temporary tables with <tt>GRANT ALL</tt>. Do (at the mysql prompt):
GRANT CREATE TEMPORARY TABLES ON archive_name.* TO eprints@localhost IDENTIFIED BY "*******";
replacing "archive_name" and "******" with your eprints mysql database name and user password. Then do:
mysqladmin [-u root -p] reload
to reload the mysql security tables.

== title and fulltext search returns no results, but date search does (EPrints 2.3) ==

The indexer daemon is probably not running or is not working correctly.

Syntax error on line 39 of /opt/eprints2/archives/eprintsOfGoat/cfg/auto-apache.conf:
order takes one argument, 'allow,deny', 'deny,allow', or 'mutual-failure' on restart of Apache after initial installation

There is a small error in the auto-apache.conf file, there is a space between 'deny, allow' on line 39, remove this space to stop this error.

== I don\'t want to give configure_archive my mysql root password. What is the alternative? ==

(instructions acurate as of EP 2.3.12)

Run configure_archive but say "no" to "create the database?"

Log into the mysql client as root:

% mysql -u root -p
Enter password:

(and enter your password)

This example creates a database for archive "foo" with user "foouser" and password "foopass".

These values should match the values you gave to configure_archive. You can check them in /opt/eprints2/archives/foo.xml

mysql> CREATE DATABASE foo;
Query OK, 1 row affected (0.06 sec)

mysql> GRANT ALL ON foo.* TO foouser@localhost;
Query OK, 0 rows affected (0.52 sec)

The last bit depends if you are running on a MySQL? version equal of greater than 4.1

4.1+:

mysql> SET PASSWORD FOR foouser@localhost = OLD_PASSWORD("foopass");

pre 4.1:

mysql> SET PASSWORD FOR foouser@localhost = PASSWORD("foopass");

That's all configure_archive would have done.

----

== How do I get a value for a field of an eprint (without using any SQL)? ==

(assuming the eprint is in the main archive, and has eprintid number 23)

my $ds = $session->get_archive()->get_dataset( "archive" );
my $eprint = EPrints::EPrint?->new( $session, 23, $ds );
my $value = $eprint->get_value( 'editors' );

== How can I get a utf8 string of the name of a subject, given its subjectid? ==

<pre>
sub get_subject_name_string
{
my( $session, $subjectid ) = @_;
my $subj = EPrints::Subject->new( $session, $subjectid );
if( !defined $subj )
{
return "errer, unknown subject: $subjectid";
}
return EPrints::Utils::tree_to_utf8( $subj->render_description() );
}
</pre>

...

== Using mod_perl2, pages with redirects (e.g. /perl/search) are blank. How do I fix this? ==

In perl_lib/EPrints/Session.pm change

$self->{"request"}->status_line( "302 Moved" );

to
$self->{"request"}->status(302);

Frequently Asked Questions

2007-02-13T23:28:18Z

Sp: /* I\'ve edited the template (or other config file) but nothing seems to have changed - why? */ style

This all needs sorting out, it's just being grabbed from the old wiki for now.

* [[Copyright and License FAQ]]
* [[Metadata FAQ]]
* [[Searching FAQ]]
* [[OAI FAQ]]
* [[BOAI Self-Archiving FAQ]]
* [[How much will it cost?]]

== What operating systems can we use? ==

EPrints should work on any UNIX operating system. We use Redhat Enterprise Linux. It will work on OSX but that takes a bit more effort. Please refer to the [http://www.eprints.org/documentation/handbook/osx.php Mac OS X Installation Guide] for more information

It will not run under Microsoft Windows and we have no plan to change this.

== What computer do we need? ==

Any new PC is easily powerful enough. Suggested minimum spec. for a live service: 1gig RAM, 20gig Harddrive, 1GHz+ processor.

== How much will it cost to set up? ==

Most of the costs are staff time. Equipment costs are a PC, an internet connection and a BACKUP STRATEGY. Please remember to budget for backups.

EPrints, and all the other software required to make it work, are available for no cost. At some point in the future EPrints may offer some pay-services, but the core software will remain zero cost and freely available to all.

See [[How much will it cost?]]

== How much diskspace will we need? ==

Proabably about 2 megabytes per eprint. At the time of writing a 120GB drive costs 50 pounds. That drive would hold approximately 60000 eprints.

See also: [[Detailed disk usage statistics]].

== Is it possible when depositing a document, to just point to an "alternative location" rather than have the full text copied and held in the eprint archive? ==

Yes, just don't assign any value to required_formats in ArchiveConfigure.pm, like so

$c->{required_formats} = [];

If you are doing this it would also be clever to change the ArchiveRender routines so that on the abstract page "Full text available as" is replaced by "Full text available via <link to alternative location>".

This keeps the key link to follow (to the full text) at the top of the screen.

== I need to run apache as a user other than "eprints", what do I do to make EPrints work in this situation? ==

Example, apache is running as user "apache".
* Make all the eprints files owned by "apache" instead of "eprints"
* Edit SystemSettings?.pm to tell eprints to run as user "apache"
* You'll need to run all command line scripts as user "apache"
* All eprints cron jobs should be owned by user "apache"

If you are installing a new copy of eprints, you can specify the user and group to use when you run 'configure'. Do

./configure --help

for details.

== How do I get the body HTML of a page without the template around it? ==

This is handy for dymnamically linking eprints content into other sites.

For "view" pages you need to add the option include=>1 to the view configuration. This will cause generate_views to make a .include page in addition to the .html page. The .include page will have no template around it.

For dynamic pages, those under /perl/, you can add the cgi parameter mainonly=yes

eg.

http://eprints.ecs.soton.ac.uk/perl/latest?mainonly=yes

== How do I get statistics on number of deposits per month? ==

This rather grim bit of SQL should work, although datestamp is the last modified date, not the submission OR creation date, it should still give a good indication.

select count(*), year(datestamp), month(datestamp)
from archive
group by year(datestamp),month(datestamp)
order by year(datestamp),month(datestamp);

== I've edited the template (or other config file) but nothing seems to have changed - why? ==

See [[HowEPrintsGeneratesWebPages]]

----

=Installation Related Questions =

== What platforms will GNU EPrints run on? ==

In theory any UNIX like platform: Linux, Solaris, BSD etc. even OSX! If you don't care then we recommend the RedHat Linux distribution.

== When running a script I get the error; "Insecure dependency in mkdir while running with -T switch" ==

This usually indicates you are running an eprints script as root. Don't do that; become user 'eprints' instead.

== Errors with import_subjects when installing Eprints 2.3.3 with MySQL? 4
MySQL? ==

4 does not grant permission to create temporary tables with GRANT ALL. Do (at the mysql prompt): GRANT CREATE TEMPORARY TABLES ON archive_name.* TO eprints@localhost IDENTIFIED BY "*******"; Then do: mysqladmin -u root -p reload to reload the mysql security tables.

== title and fulltext search returns no results, but date search does (EPrints 2.3) ==

The indexer daemon is probably not running or is not working correctly.

Syntax error on line 39 of /opt/eprints2/archives/eprintsOfGoat/cfg/auto-apache.conf:
order takes one argument, 'allow,deny', 'deny,allow', or 'mutual-failure' on restart of Apache after initial installation

There is a small error in the auto-apache.conf file, there is a space between 'deny, allow' on line 39, remove this space to stop this error.

== I don\'t want to give configure_archive my mysql root password. What is the alternative? ==

(instructions acurate as of EP 2.3.12)

Run configure_archive but say "no" to "create the database?"

Log into the mysql client as root:

% mysql -u root -p
Enter password:

(and enter your password)

This example creates a database for archive "foo" with user "foouser" and password "foopass".

These values should match the values you gave to configure_archive. You can check them in /opt/eprints2/archives/foo.xml

mysql> CREATE DATABASE foo;
Query OK, 1 row affected (0.06 sec)

mysql> GRANT ALL ON foo.* TO foouser@localhost;
Query OK, 0 rows affected (0.52 sec)

The last bit depends if you are running on a MySQL? version equal of greater than 4.1

4.1+:

mysql> SET PASSWORD FOR foouser@localhost = OLD_PASSWORD("foopass");

pre 4.1:

mysql> SET PASSWORD FOR foouser@localhost = PASSWORD("foopass");

That's all configure_archive would have done.

----

== How do I get a value for a field of an eprint (without using any SQL)? ==

(assuming the eprint is in the main archive, and has eprintid number 23)

my $ds = $session->get_archive()->get_dataset( "archive" );
my $eprint = EPrints::EPrint?->new( $session, 23, $ds );
my $value = $eprint->get_value( 'editors' );

== How can I get a utf8 string of the name of a subject, given its subjectid? ==

<pre>
sub get_subject_name_string
{
my( $session, $subjectid ) = @_;
my $subj = EPrints::Subject->new( $session, $subjectid );
if( !defined $subj )
{
return "errer, unknown subject: $subjectid";
}
return EPrints::Utils::tree_to_utf8( $subj->render_description() );
}
</pre>

...

== Using mod_perl2, pages with redirects (e.g. /perl/search) are blank. How do I fix this? ==

In perl_lib/EPrints/Session.pm change

$self->{"request"}->status_line( "302 Moved" );

to
$self->{"request"}->status(302);

Frequently Asked Questions

2007-02-13T23:27:38Z

Sp: /* How do I get statistics on number of deposits per month? */ style

This all needs sorting out, it's just being grabbed from the old wiki for now.

* [[Copyright and License FAQ]]
* [[Metadata FAQ]]
* [[Searching FAQ]]
* [[OAI FAQ]]
* [[BOAI Self-Archiving FAQ]]
* [[How much will it cost?]]

== What operating systems can we use? ==

EPrints should work on any UNIX operating system. We use Redhat Enterprise Linux. It will work on OSX but that takes a bit more effort. Please refer to the [http://www.eprints.org/documentation/handbook/osx.php Mac OS X Installation Guide] for more information

It will not run under Microsoft Windows and we have no plan to change this.

== What computer do we need? ==

Any new PC is easily powerful enough. Suggested minimum spec. for a live service: 1gig RAM, 20gig Harddrive, 1GHz+ processor.

== How much will it cost to set up? ==

Most of the costs are staff time. Equipment costs are a PC, an internet connection and a BACKUP STRATEGY. Please remember to budget for backups.

EPrints, and all the other software required to make it work, are available for no cost. At some point in the future EPrints may offer some pay-services, but the core software will remain zero cost and freely available to all.

See [[How much will it cost?]]

== How much diskspace will we need? ==

Proabably about 2 megabytes per eprint. At the time of writing a 120GB drive costs 50 pounds. That drive would hold approximately 60000 eprints.

See also: [[Detailed disk usage statistics]].

== Is it possible when depositing a document, to just point to an "alternative location" rather than have the full text copied and held in the eprint archive? ==

Yes, just don't assign any value to required_formats in ArchiveConfigure.pm, like so

$c->{required_formats} = [];

If you are doing this it would also be clever to change the ArchiveRender routines so that on the abstract page "Full text available as" is replaced by "Full text available via <link to alternative location>".

This keeps the key link to follow (to the full text) at the top of the screen.

== I need to run apache as a user other than "eprints", what do I do to make EPrints work in this situation? ==

Example, apache is running as user "apache".
* Make all the eprints files owned by "apache" instead of "eprints"
* Edit SystemSettings?.pm to tell eprints to run as user "apache"
* You'll need to run all command line scripts as user "apache"
* All eprints cron jobs should be owned by user "apache"

If you are installing a new copy of eprints, you can specify the user and group to use when you run 'configure'. Do

./configure --help

for details.

== How do I get the body HTML of a page without the template around it? ==

This is handy for dymnamically linking eprints content into other sites.

For "view" pages you need to add the option include=>1 to the view configuration. This will cause generate_views to make a .include page in addition to the .html page. The .include page will have no template around it.

For dynamic pages, those under /perl/, you can add the cgi parameter mainonly=yes

eg.

http://eprints.ecs.soton.ac.uk/perl/latest?mainonly=yes

== How do I get statistics on number of deposits per month? ==

This rather grim bit of SQL should work, although datestamp is the last modified date, not the submission OR creation date, it should still give a good indication.

select count(*), year(datestamp), month(datestamp)
from archive
group by year(datestamp),month(datestamp)
order by year(datestamp),month(datestamp);

== I\'ve edited the template (or other config file) but nothing seems to have changed - why? ==

See HowEPrintsGeneratesWebPages

----

=Installation Related Questions =

== What platforms will GNU EPrints run on? ==

In theory any UNIX like platform: Linux, Solaris, BSD etc. even OSX! If you don't care then we recommend the RedHat Linux distribution.

== When running a script I get the error; "Insecure dependency in mkdir while running with -T switch" ==

This usually indicates you are running an eprints script as root. Don't do that; become user 'eprints' instead.

== Errors with import_subjects when installing Eprints 2.3.3 with MySQL? 4
MySQL? ==

4 does not grant permission to create temporary tables with GRANT ALL. Do (at the mysql prompt): GRANT CREATE TEMPORARY TABLES ON archive_name.* TO eprints@localhost IDENTIFIED BY "*******"; Then do: mysqladmin -u root -p reload to reload the mysql security tables.

== title and fulltext search returns no results, but date search does (EPrints 2.3) ==

The indexer daemon is probably not running or is not working correctly.

Syntax error on line 39 of /opt/eprints2/archives/eprintsOfGoat/cfg/auto-apache.conf:
order takes one argument, 'allow,deny', 'deny,allow', or 'mutual-failure' on restart of Apache after initial installation

There is a small error in the auto-apache.conf file, there is a space between 'deny, allow' on line 39, remove this space to stop this error.

== I don\'t want to give configure_archive my mysql root password. What is the alternative? ==

(instructions acurate as of EP 2.3.12)

Run configure_archive but say "no" to "create the database?"

Log into the mysql client as root:

% mysql -u root -p
Enter password:

(and enter your password)

This example creates a database for archive "foo" with user "foouser" and password "foopass".

These values should match the values you gave to configure_archive. You can check them in /opt/eprints2/archives/foo.xml

mysql> CREATE DATABASE foo;
Query OK, 1 row affected (0.06 sec)

mysql> GRANT ALL ON foo.* TO foouser@localhost;
Query OK, 0 rows affected (0.52 sec)

The last bit depends if you are running on a MySQL? version equal of greater than 4.1

4.1+:

mysql> SET PASSWORD FOR foouser@localhost = OLD_PASSWORD("foopass");

pre 4.1:

mysql> SET PASSWORD FOR foouser@localhost = PASSWORD("foopass");

That's all configure_archive would have done.

----

== How do I get a value for a field of an eprint (without using any SQL)? ==

(assuming the eprint is in the main archive, and has eprintid number 23)

my $ds = $session->get_archive()->get_dataset( "archive" );
my $eprint = EPrints::EPrint?->new( $session, 23, $ds );
my $value = $eprint->get_value( 'editors' );

== How can I get a utf8 string of the name of a subject, given its subjectid? ==

<pre>
sub get_subject_name_string
{
my( $session, $subjectid ) = @_;
my $subj = EPrints::Subject->new( $session, $subjectid );
if( !defined $subj )
{
return "errer, unknown subject: $subjectid";
}
return EPrints::Utils::tree_to_utf8( $subj->render_description() );
}
</pre>

...

== Using mod_perl2, pages with redirects (e.g. /perl/search) are blank. How do I fix this? ==

In perl_lib/EPrints/Session.pm change

$self->{"request"}->status_line( "302 Moved" );

to
$self->{"request"}->status(302);

Frequently Asked Questions

2007-02-13T23:25:47Z

Sp: /* I need to run apache as a user other than "eprints", what do I do to make EPrints work in this situation? */ style

This all needs sorting out, it's just being grabbed from the old wiki for now.

* [[Copyright and License FAQ]]
* [[Metadata FAQ]]
* [[Searching FAQ]]
* [[OAI FAQ]]
* [[BOAI Self-Archiving FAQ]]
* [[How much will it cost?]]

== What operating systems can we use? ==

EPrints should work on any UNIX operating system. We use Redhat Enterprise Linux. It will work on OSX but that takes a bit more effort. Please refer to the [http://www.eprints.org/documentation/handbook/osx.php Mac OS X Installation Guide] for more information

It will not run under Microsoft Windows and we have no plan to change this.

== What computer do we need? ==

Any new PC is easily powerful enough. Suggested minimum spec. for a live service: 1gig RAM, 20gig Harddrive, 1GHz+ processor.

== How much will it cost to set up? ==

Most of the costs are staff time. Equipment costs are a PC, an internet connection and a BACKUP STRATEGY. Please remember to budget for backups.

EPrints, and all the other software required to make it work, are available for no cost. At some point in the future EPrints may offer some pay-services, but the core software will remain zero cost and freely available to all.

See [[How much will it cost?]]

== How much diskspace will we need? ==

Proabably about 2 megabytes per eprint. At the time of writing a 120GB drive costs 50 pounds. That drive would hold approximately 60000 eprints.

See also: [[Detailed disk usage statistics]].

== Is it possible when depositing a document, to just point to an "alternative location" rather than have the full text copied and held in the eprint archive? ==

Yes, just don't assign any value to required_formats in ArchiveConfigure.pm, like so

$c->{required_formats} = [];

If you are doing this it would also be clever to change the ArchiveRender routines so that on the abstract page "Full text available as" is replaced by "Full text available via <link to alternative location>".

This keeps the key link to follow (to the full text) at the top of the screen.

== I need to run apache as a user other than "eprints", what do I do to make EPrints work in this situation? ==

Example, apache is running as user "apache".
* Make all the eprints files owned by "apache" instead of "eprints"
* Edit SystemSettings?.pm to tell eprints to run as user "apache"
* You'll need to run all command line scripts as user "apache"
* All eprints cron jobs should be owned by user "apache"

If you are installing a new copy of eprints, you can specify the user and group to use when you run 'configure'. Do

./configure --help

for details.

== How do I get the body HTML of a page without the template around it? ==

This is handy for dymnamically linking eprints content into other sites.

For "view" pages you need to add the option include=>1 to the view configuration. This will cause generate_views to make a .include page in addition to the .html page. The .include page will have no template around it.

For dynamic pages, those under /perl/, you can add the cgi parameter mainonly=yes

eg.

http://eprints.ecs.soton.ac.uk/perl/latest?mainonly=yes

== How do I get statistics on number of deposits per month? ==

This rather grim bit of SQL should work, although datestamp is the last modified date, not the submission OR creation date, it should still give a good indication.

select count(*),year(datestamp), month(datestamp) from archive group by year(datestamp),month(datestamp) order by year(datestamp),month(datestamp);

== I\'ve edited the template (or other config file) but nothing seems to have changed - why? ==

See HowEPrintsGeneratesWebPages

----

=Installation Related Questions =

== What platforms will GNU EPrints run on? ==

In theory any UNIX like platform: Linux, Solaris, BSD etc. even OSX! If you don't care then we recommend the RedHat Linux distribution.

== When running a script I get the error; "Insecure dependency in mkdir while running with -T switch" ==

This usually indicates you are running an eprints script as root. Don't do that; become user 'eprints' instead.

== Errors with import_subjects when installing Eprints 2.3.3 with MySQL? 4
MySQL? ==

4 does not grant permission to create temporary tables with GRANT ALL. Do (at the mysql prompt): GRANT CREATE TEMPORARY TABLES ON archive_name.* TO eprints@localhost IDENTIFIED BY "*******"; Then do: mysqladmin -u root -p reload to reload the mysql security tables.

== title and fulltext search returns no results, but date search does (EPrints 2.3) ==

The indexer daemon is probably not running or is not working correctly.

Syntax error on line 39 of /opt/eprints2/archives/eprintsOfGoat/cfg/auto-apache.conf:
order takes one argument, 'allow,deny', 'deny,allow', or 'mutual-failure' on restart of Apache after initial installation

There is a small error in the auto-apache.conf file, there is a space between 'deny, allow' on line 39, remove this space to stop this error.

== I don\'t want to give configure_archive my mysql root password. What is the alternative? ==

(instructions acurate as of EP 2.3.12)

Run configure_archive but say "no" to "create the database?"

Log into the mysql client as root:

% mysql -u root -p
Enter password:

(and enter your password)

This example creates a database for archive "foo" with user "foouser" and password "foopass".

These values should match the values you gave to configure_archive. You can check them in /opt/eprints2/archives/foo.xml

mysql> CREATE DATABASE foo;
Query OK, 1 row affected (0.06 sec)

mysql> GRANT ALL ON foo.* TO foouser@localhost;
Query OK, 0 rows affected (0.52 sec)

The last bit depends if you are running on a MySQL? version equal of greater than 4.1

4.1+:

mysql> SET PASSWORD FOR foouser@localhost = OLD_PASSWORD("foopass");

pre 4.1:

mysql> SET PASSWORD FOR foouser@localhost = PASSWORD("foopass");

That's all configure_archive would have done.

----

== How do I get a value for a field of an eprint (without using any SQL)? ==

(assuming the eprint is in the main archive, and has eprintid number 23)

my $ds = $session->get_archive()->get_dataset( "archive" );
my $eprint = EPrints::EPrint?->new( $session, 23, $ds );
my $value = $eprint->get_value( 'editors' );

== How can I get a utf8 string of the name of a subject, given its subjectid? ==

<pre>
sub get_subject_name_string
{
my( $session, $subjectid ) = @_;
my $subj = EPrints::Subject->new( $session, $subjectid );
if( !defined $subj )
{
return "errer, unknown subject: $subjectid";
}
return EPrints::Utils::tree_to_utf8( $subj->render_description() );
}
</pre>

...

== Using mod_perl2, pages with redirects (e.g. /perl/search) are blank. How do I fix this? ==

In perl_lib/EPrints/Session.pm change

$self->{"request"}->status_line( "302 Moved" );

to
$self->{"request"}->status(302);

Frequently Asked Questions

2007-02-13T23:25:17Z

Sp: /* Is it possible when depositing a document, to just point to an "alternative location" rather than have the full text copied and held in the eprint archive? */

This all needs sorting out, it's just being grabbed from the old wiki for now.

* [[Copyright and License FAQ]]
* [[Metadata FAQ]]
* [[Searching FAQ]]
* [[OAI FAQ]]
* [[BOAI Self-Archiving FAQ]]
* [[How much will it cost?]]

== What operating systems can we use? ==

EPrints should work on any UNIX operating system. We use Redhat Enterprise Linux. It will work on OSX but that takes a bit more effort. Please refer to the [http://www.eprints.org/documentation/handbook/osx.php Mac OS X Installation Guide] for more information

It will not run under Microsoft Windows and we have no plan to change this.

== What computer do we need? ==

Any new PC is easily powerful enough. Suggested minimum spec. for a live service: 1gig RAM, 20gig Harddrive, 1GHz+ processor.

== How much will it cost to set up? ==

Most of the costs are staff time. Equipment costs are a PC, an internet connection and a BACKUP STRATEGY. Please remember to budget for backups.

EPrints, and all the other software required to make it work, are available for no cost. At some point in the future EPrints may offer some pay-services, but the core software will remain zero cost and freely available to all.

See [[How much will it cost?]]

== How much diskspace will we need? ==

Proabably about 2 megabytes per eprint. At the time of writing a 120GB drive costs 50 pounds. That drive would hold approximately 60000 eprints.

See also: [[Detailed disk usage statistics]].

== Is it possible when depositing a document, to just point to an "alternative location" rather than have the full text copied and held in the eprint archive? ==

Yes, just don't assign any value to required_formats in ArchiveConfigure.pm, like so

$c->{required_formats} = [];

If you are doing this it would also be clever to change the ArchiveRender routines so that on the abstract page "Full text available as" is replaced by "Full text available via <link to alternative location>".

This keeps the key link to follow (to the full text) at the top of the screen.

== I need to run apache as a user other than "eprints", what do I do to make EPrints work in this situation? ==

Example, apache is running as user "apache".

* Make all the eprints files owned by "apache" instead of "eprints"
* Edit SystemSettings?.pm to tell eprints to run as user "apache"
* You'll need to run all command line scripts as user "apache"
* All eprints cron jobs should be owned by user "apache"

If you are installing a new copy of eprints, you can specify the user and group to use when you run 'configure'. Do

./configure --help

for details.

== How do I get the body HTML of a page without the template around it? ==

This is handy for dymnamically linking eprints content into other sites.

For "view" pages you need to add the option include=>1 to the view configuration. This will cause generate_views to make a .include page in addition to the .html page. The .include page will have no template around it.

For dynamic pages, those under /perl/, you can add the cgi parameter mainonly=yes

eg.

http://eprints.ecs.soton.ac.uk/perl/latest?mainonly=yes

== How do I get statistics on number of deposits per month? ==

This rather grim bit of SQL should work, although datestamp is the last modified date, not the submission OR creation date, it should still give a good indication.

select count(*),year(datestamp), month(datestamp) from archive group by year(datestamp),month(datestamp) order by year(datestamp),month(datestamp);

== I\'ve edited the template (or other config file) but nothing seems to have changed - why? ==

See HowEPrintsGeneratesWebPages

----

=Installation Related Questions =

== What platforms will GNU EPrints run on? ==

In theory any UNIX like platform: Linux, Solaris, BSD etc. even OSX! If you don't care then we recommend the RedHat Linux distribution.

== When running a script I get the error; "Insecure dependency in mkdir while running with -T switch" ==

This usually indicates you are running an eprints script as root. Don't do that; become user 'eprints' instead.

== Errors with import_subjects when installing Eprints 2.3.3 with MySQL? 4
MySQL? ==

4 does not grant permission to create temporary tables with GRANT ALL. Do (at the mysql prompt): GRANT CREATE TEMPORARY TABLES ON archive_name.* TO eprints@localhost IDENTIFIED BY "*******"; Then do: mysqladmin -u root -p reload to reload the mysql security tables.

== title and fulltext search returns no results, but date search does (EPrints 2.3) ==

The indexer daemon is probably not running or is not working correctly.

Syntax error on line 39 of /opt/eprints2/archives/eprintsOfGoat/cfg/auto-apache.conf:
order takes one argument, 'allow,deny', 'deny,allow', or 'mutual-failure' on restart of Apache after initial installation

There is a small error in the auto-apache.conf file, there is a space between 'deny, allow' on line 39, remove this space to stop this error.

== I don\'t want to give configure_archive my mysql root password. What is the alternative? ==

(instructions acurate as of EP 2.3.12)

Run configure_archive but say "no" to "create the database?"

Log into the mysql client as root:

% mysql -u root -p
Enter password:

(and enter your password)

This example creates a database for archive "foo" with user "foouser" and password "foopass".

These values should match the values you gave to configure_archive. You can check them in /opt/eprints2/archives/foo.xml

mysql> CREATE DATABASE foo;
Query OK, 1 row affected (0.06 sec)

mysql> GRANT ALL ON foo.* TO foouser@localhost;
Query OK, 0 rows affected (0.52 sec)

The last bit depends if you are running on a MySQL? version equal of greater than 4.1

4.1+:

mysql> SET PASSWORD FOR foouser@localhost = OLD_PASSWORD("foopass");

pre 4.1:

mysql> SET PASSWORD FOR foouser@localhost = PASSWORD("foopass");

That's all configure_archive would have done.

----

== How do I get a value for a field of an eprint (without using any SQL)? ==

(assuming the eprint is in the main archive, and has eprintid number 23)

my $ds = $session->get_archive()->get_dataset( "archive" );
my $eprint = EPrints::EPrint?->new( $session, 23, $ds );
my $value = $eprint->get_value( 'editors' );

== How can I get a utf8 string of the name of a subject, given its subjectid? ==

<pre>
sub get_subject_name_string
{
my( $session, $subjectid ) = @_;
my $subj = EPrints::Subject->new( $session, $subjectid );
if( !defined $subj )
{
return "errer, unknown subject: $subjectid";
}
return EPrints::Utils::tree_to_utf8( $subj->render_description() );
}
</pre>

...

== Using mod_perl2, pages with redirects (e.g. /perl/search) are blank. How do I fix this? ==

In perl_lib/EPrints/Session.pm change

$self->{"request"}->status_line( "302 Moved" );

to
$self->{"request"}->status(302);

Frequently Asked Questions

2007-02-13T23:25:02Z

Sp: /* Is it possible when depositing a document, to just point to an "alternative location" rather than have the full text copied and held in the eprint archive? */

This all needs sorting out, it's just being grabbed from the old wiki for now.

* [[Copyright and License FAQ]]
* [[Metadata FAQ]]
* [[Searching FAQ]]
* [[OAI FAQ]]
* [[BOAI Self-Archiving FAQ]]
* [[How much will it cost?]]

== What operating systems can we use? ==

EPrints should work on any UNIX operating system. We use Redhat Enterprise Linux. It will work on OSX but that takes a bit more effort. Please refer to the [http://www.eprints.org/documentation/handbook/osx.php Mac OS X Installation Guide] for more information

It will not run under Microsoft Windows and we have no plan to change this.

== What computer do we need? ==

Any new PC is easily powerful enough. Suggested minimum spec. for a live service: 1gig RAM, 20gig Harddrive, 1GHz+ processor.

== How much will it cost to set up? ==

Most of the costs are staff time. Equipment costs are a PC, an internet connection and a BACKUP STRATEGY. Please remember to budget for backups.

EPrints, and all the other software required to make it work, are available for no cost. At some point in the future EPrints may offer some pay-services, but the core software will remain zero cost and freely available to all.

See [[How much will it cost?]]

== How much diskspace will we need? ==

Proabably about 2 megabytes per eprint. At the time of writing a 120GB drive costs 50 pounds. That drive would hold approximately 60000 eprints.

See also: [[Detailed disk usage statistics]].

== Is it possible when depositing a document, to just point to an "alternative location" rather than have the full text copied and held in the eprint archive? ==

Yes, just don't assign any value to required_formats in ArchiveConfigure?.pm, like so

$c->{required_formats} = [];

If you are doing this it would also be clever to change the ArchiveRender routines so that on the abstract page "Full text available as" is replaced by "Full text available via <link to alternative location>".

This keeps the key link to follow (to the full text) at the top of the screen.

== I need to run apache as a user other than "eprints", what do I do to make EPrints work in this situation? ==

Example, apache is running as user "apache".

* Make all the eprints files owned by "apache" instead of "eprints"
* Edit SystemSettings?.pm to tell eprints to run as user "apache"
* You'll need to run all command line scripts as user "apache"
* All eprints cron jobs should be owned by user "apache"

If you are installing a new copy of eprints, you can specify the user and group to use when you run 'configure'. Do

./configure --help

for details.

== How do I get the body HTML of a page without the template around it? ==

This is handy for dymnamically linking eprints content into other sites.

For "view" pages you need to add the option include=>1 to the view configuration. This will cause generate_views to make a .include page in addition to the .html page. The .include page will have no template around it.

For dynamic pages, those under /perl/, you can add the cgi parameter mainonly=yes

eg.

http://eprints.ecs.soton.ac.uk/perl/latest?mainonly=yes

== How do I get statistics on number of deposits per month? ==

This rather grim bit of SQL should work, although datestamp is the last modified date, not the submission OR creation date, it should still give a good indication.

select count(*),year(datestamp), month(datestamp) from archive group by year(datestamp),month(datestamp) order by year(datestamp),month(datestamp);

== I\'ve edited the template (or other config file) but nothing seems to have changed - why? ==

See HowEPrintsGeneratesWebPages

----

=Installation Related Questions =

== What platforms will GNU EPrints run on? ==

In theory any UNIX like platform: Linux, Solaris, BSD etc. even OSX! If you don't care then we recommend the RedHat Linux distribution.

== When running a script I get the error; "Insecure dependency in mkdir while running with -T switch" ==

This usually indicates you are running an eprints script as root. Don't do that; become user 'eprints' instead.

== Errors with import_subjects when installing Eprints 2.3.3 with MySQL? 4
MySQL? ==

4 does not grant permission to create temporary tables with GRANT ALL. Do (at the mysql prompt): GRANT CREATE TEMPORARY TABLES ON archive_name.* TO eprints@localhost IDENTIFIED BY "*******"; Then do: mysqladmin -u root -p reload to reload the mysql security tables.

== title and fulltext search returns no results, but date search does (EPrints 2.3) ==

The indexer daemon is probably not running or is not working correctly.

Syntax error on line 39 of /opt/eprints2/archives/eprintsOfGoat/cfg/auto-apache.conf:
order takes one argument, 'allow,deny', 'deny,allow', or 'mutual-failure' on restart of Apache after initial installation

There is a small error in the auto-apache.conf file, there is a space between 'deny, allow' on line 39, remove this space to stop this error.

== I don\'t want to give configure_archive my mysql root password. What is the alternative? ==

(instructions acurate as of EP 2.3.12)

Run configure_archive but say "no" to "create the database?"

Log into the mysql client as root:

% mysql -u root -p
Enter password:

(and enter your password)

This example creates a database for archive "foo" with user "foouser" and password "foopass".

These values should match the values you gave to configure_archive. You can check them in /opt/eprints2/archives/foo.xml

mysql> CREATE DATABASE foo;
Query OK, 1 row affected (0.06 sec)

mysql> GRANT ALL ON foo.* TO foouser@localhost;
Query OK, 0 rows affected (0.52 sec)

The last bit depends if you are running on a MySQL? version equal of greater than 4.1

4.1+:

mysql> SET PASSWORD FOR foouser@localhost = OLD_PASSWORD("foopass");

pre 4.1:

mysql> SET PASSWORD FOR foouser@localhost = PASSWORD("foopass");

That's all configure_archive would have done.

----

== How do I get a value for a field of an eprint (without using any SQL)? ==

(assuming the eprint is in the main archive, and has eprintid number 23)

my $ds = $session->get_archive()->get_dataset( "archive" );
my $eprint = EPrints::EPrint?->new( $session, 23, $ds );
my $value = $eprint->get_value( 'editors' );

== How can I get a utf8 string of the name of a subject, given its subjectid? ==

<pre>
sub get_subject_name_string
{
my( $session, $subjectid ) = @_;
my $subj = EPrints::Subject->new( $session, $subjectid );
if( !defined $subj )
{
return "errer, unknown subject: $subjectid";
}
return EPrints::Utils::tree_to_utf8( $subj->render_description() );
}
</pre>

...

== Using mod_perl2, pages with redirects (e.g. /perl/search) are blank. How do I fix this? ==

In perl_lib/EPrints/Session.pm change

$self->{"request"}->status_line( "302 Moved" );

to
$self->{"request"}->status(302);

User:Sp

2007-02-13T22:56:22Z

Sp: whoami

UNIX Sysadmin<br>
University of Vienna, Austria

Installation

2007-02-13T22:53:48Z

Sp: formatting, apache.conf needs to be generated first

{{development}}
{{manual}}
==Installation==
(If you are upgrading an existing installation of eprints please see the section on upgrading elsewhere in this manual.)

EPrints needs to be installed as the same user as the apache webserver runs as. We suggest you install it as user "eprints" and group "eprints". Under some UNIX platforms, creating a user and group can be done using the "adduser" command. Otherwise refer to your operating system documentation.

Unpack the eprints tar.gz file:

% gunzip eprints-3.something.tar.gz
% tar xf eprints-3.something.tar

Now run the "configure" script. This is a /bin/sh script which will attempt to locate various parts of your system such as the perl binary. It will also check your system for required components.

% cd eprints-3.something
% ./configure

By default the system installs as user and group "eprints". You will need to change this if you are not installing as either "root" or "eprints".

The configure script accepts a number of options. All are optional. The most important are:

; --help : List all the options (many are intended for compiled software and are ignored).
; --prefix=PREFIX : Where to install EPrints (or look for a version to upgrade). By default /opt/eprints3/
; --with-perl=[PATH] : Path of perl interpreter (in case configure can't find it, or you have more than one and want to use a specific one).
; --with-user=[USER] : Install eprints to run as USER. By default "eprints".
; --with-group=[GROUP] : Install eprints to run as GROUP. By default "eprints".
; --with-virtualhost=[VIRTUALHOST] : Use VIRTUALHOST rather than * for apache VirtualHost directives.
; --disable-diskfree : Disable disk free space calls. This will be automatically set if configure fails its tests for the df call.
; --with-toolpath=[PATH] : An alternate path to search for the required binaries.

Once you are happy with your configuration you may install eprints by running install.pl:

% ./install.pl

Now you should edit the configuration file for your copy of apache. This is often <tt>/usr/local/apache/conf/http.conf</tt> or <tt>/etc/httpd/conf/httpd.conf</tt>

Add this line: (If you didn't install eprints in <tt>/opt/eprints3/</tt> replace that with the location on your system).
Include /opt/eprints3/cfg/apache.conf
Note that this file is only available after you created your archive via <tt>epadmin create</tt>.

You may also wish to change the user and group apache runs as. The user ''must'' be the same as the user you installed eprints as. We recommend:

User eprints
Group eprints