Difference between revisions of "How to use EPrints with HTTPS"

From EPrints Documentation
Jump to: navigation, search
(Added securevhost,conf)
m
(19 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
{{manual}}
 
{{manual}}
 +
 
[[Category:Authentication]]
 
[[Category:Authentication]]
  
'''This guide is intended for EPrints 3.2 or later.'''
+
'''This guide is intended for EPrints 3.3 or later.'''
  
 
+
'''N.B.''' Setting up your Apache Web server is beyond the scope of this document.  Please see your operating system documentation and the Apache documentation for assistance in setting up Apache in your environment.'''
'''N.B. Setting up your Apache Web server is beyond the scope of this document.  Please see your operating system documentation and the Apache documentation for assistance in setting up Apache in your environment.'''
+
  
  
 
== Configuration ==
 
== Configuration ==
To start setting up your existing archive to work under HTTPS, you must first edit <tt>archives/[repoid]/cfg/cfg.d/10_core.pl</tt>. Initially it will probably look something like the following which is the basic 10_core.pl configuration file after you have run <tt>bin/epadmin create</tt> to setup your archive.  Alternatively you could run <tt>bin/epadmin config_core [repoid]</tt> that will prompt you for the following information. It is suggested that you make a backup of the 10_core.pl file regardless before proceeding.
+
Below is a list of variable names described in these instructions and example values of what they might be in a real-world configuration.
 +
{| border="1" cellpadding="10" cellspacing="0"
 +
!Variable
 +
!Example
 +
|-
 +
|EPRINTS_PATH
 +
|/opt/eprints3
 +
|-
 +
|YOUR-REPOSITORY-DOMAIN
 +
|example.eprints.org
 +
|-
 +
|REPOID
 +
|example
 +
|-
 +
|}
 +
 
 +
To start setting up your existing archive to work under HTTPS, you must first edit <tt>EPRINTS_PATH/archives/REPOID/cfg/cfg.d/10_core.pl</tt>. Initially it will probably look something like the configuration directly below,  which is the basic 10_core.pl configuration file after you have run <tt>EPRINTS_PATH/bin/epadmin create</tt> to setup your archive.  Alternatively you could run <tt>/opt/eprints3/bin/epadmin config_core REPOID</tt> that will prompt you for the following information. It is suggested that you make a backup of the 10_core.pl file regardless before proceeding.
  
  $c->{host} = 'your.dnshostname.org';
+
  $c->{host} = 'YOUR-REPOSITORY-DOMAIN';
 
  $c->{port} = 80;
 
  $c->{port} = 80;
 
  $c->{aliases} = [];
 
  $c->{aliases} = [];
  $c->{securehost} = '';
+
  $c->{securehost} = &#39;&#39;;
 
  $c->{secureport} = 443;
 
  $c->{secureport} = 443;
 
  $c->{http_root} = undef;
 
  $c->{http_root} = undef;
  
Update the file to define the secure host and modify ports as needed.  If your Apache web server is not using the standard ports (80,443) you can adjust the 'port' and 'secureport' parameters in the config file accordingly.
+
Update the file to define the secure host and modify ports as needed.  If your Apache web server is not using the standard ports (80,443) you can adjust the <tt>port</tt> and <tt>secureport</tt> parameters in the config file accordingly.
  
  $c->{host} = 'your.dnshostname.org';
+
  $c->{host} = 'YOUR-REPOSITORY-DOMAIN';
 
  $c->{port} = 80;
 
  $c->{port} = 80;
 
  $c->{aliases} = [];
 
  $c->{aliases} = [];
  $c->{securehost} = 'your.dnshostname.org';
+
  $c->{securehost} = $c->{host};
 
  $c->{secureport} = 443;
 
  $c->{secureport} = 443;
 
  $c->{http_root} = undef;
 
  $c->{http_root} = undef;
  
Now, you need to create the directory <tt>archives/[repoid]/ssl/</tt> and then edit the file <tt>archives/[repoid]/ssl/securevhost.conf</tt>.  This file should look something like:
+
Now, you need to create the directory <tt>EPRINTS_PATH/archives/REPOID/ssl/</tt> and then edit the file <tt>REPOID/ssl/securevhost.conf</tt>.  This file should look something like below. If you are installing EPrints on Debian/Ubuntu based systens you will need to create a symlink <tt>logs</tt> in <tt>/etc/apache2/</tt> to point at <tt>/var/log/apache2/</tt>.
 
+
{{Securevhost.conf}}
  <VirtualHost *:443>
+
+
  ServerName your.dnshostname.org:443
+
+
  Header always set Strict-Transport-Security "max-age=63072000;"
+
+
  ErrorLog logs/ssl_error_log
+
  TransferLog logs/ssl_access_log
+
  LogLevel warn
+
+
  SSLEngine on
+
  SSLProtocol all -SSLv2
+
  SSLCipherSuite ALL:!ADH:!EXPORT:!SSLv2:RC4+RSA:+HIGH:+MEDIUM:+LOW
+
+
  SSLCertificateFile cert.pem
+
  SSLCertificateKeyFile privkey.pem
+
  SSLCertificateChainFile chain.pem
+
+
  SetEnvIf User-Agent ".*MSIE.*" \
+
    nokeepalive ssl-unclean-shutdown \
+
    downgrade-1.0 force-response-1.0
+
 
+
  CustomLog logs/ssl_request_log \
+
    "%t %h %{SSL_PROTOCOL}x %{SSL_CIPHER}x \"%r\" %b"
+
+
  Include /opt/eprints3/cfg/apache_ssl/[repoid].conf
+
+
  PerlTransHandler +EPrints::Apache::Rewrite
+
+
</VirtualHost>
+
  
 +
It is advised that you keep the SSL key, certificate and chain files in the same directory as securevhost.conf, as this will make it easy if you need to migrate you EPrints repository to a new server in the future.
  
 
== Generate the Apache Configuration File for HTTPS ==
 
== Generate the Apache Configuration File for HTTPS ==
Run <tt>bin/generate_apacheconf</tt> to generate the secure Apache configuration files and depending upon the version of EPrints you are using, it may copy the default template <tt>archives/[repoid]/cfg/lang/en/templates/default.xml</tt> to the template used for HTTPS <tt>archives/[repoid]/cfg/lang/en/templates/secure.xml</tt>.  This will also setup the repository configuration file located in the <tt>/opt/eprints3/cfg/apache_ssl/</tt> directory named [repoid].conf.
+
Run <tt>EPRINTS_PATH/bin/generate_apacheconf --system --replace</tt> to generate the secure Apache configuration files.  This will setup the repository configuration file located in the <tt>EPRINTS_PATH/cfg/apache_ssl/</tt> directory named <tt>REPOID.conf</tt>.  
  
  
 
== Add the Main Apache Config File to SSL Config ==
 
== Add the Main Apache Config File to SSL Config ==
Depending upon the version of EPrints you are running there are a couple files that may be involved.  It is recommended to run <tt>bin/generate_apacheconf --man</tt> or view the source of <tt>bin/generate_apacheconf</tt> file to understand what file(s) need to be setup.  In general you will need to place a line like either of the following inside your Apache SSL Virtual Host declaration (most likely found in <tt>/etc/httpd/conf.d/mod_ssl.conf</tt> or <tt>/etc/httpd/conf.d/ssl.conf</tt>)Make sure that these lines are placed inside the <VirtualHost> Apache directive.
+
Depending upon the version of EPrints you are running there are a couple files that may be involved.  It is recommended to run <tt>EPRINTS_PATH/bin/generate_apacheconf --man</tt> or view the source of <tt>EPRINTS_PATH/bin/generate_apacheconf</tt> file to understand what file(s) need to be setup.  Apache will not yet have been setup to include <tt>EPRINTS_PATH/archives/REPOID/ssl/securevhost.conf</tt>.   
  
  Include /opt/eprints3/archives/[repoid]/var/auto-secure.conf
+
To include this, you will need to find the file that already includes <tt>cfg/apache.conf</tt>. (For Red Hat/Fedora/CentOS Linux you will need to look in <tt>/etc/httpd/</tt>. For Debian/Ubuntu Linux you will need to look in <tt>/etc/apache2/</tt>).  Then add the following line after
  
Or
+
Include EPRINTS_PATH/archives/*/ssl/securevhost.conf
  
Include /opt/eprints3/cfg/apache_ssl.conf
+
== Restart Apache to pick up the changes to the Apache configuration ==
 +
Consult your operating system documentation on how to restart service processes but in general you need to run one of the following commands either as <tt>root</tt> or using <tt>sudo</tt>:
  
 
=== For Red Hat/Fedora/CentOS Linux ===
 
=== For Red Hat/Fedora/CentOS Linux ===
 +
/sbin/service httpd restart
  
 
=== For Debian/Ubuntu Linux ===
 
=== For Debian/Ubuntu Linux ===
 +
Before restarting Apache make sure <tt>mod_ssl</tt> is enabled:
 +
a2enmod ssl
 +
Then restart Apache:
 +
/etc/init.d/apache2 restart
  
 +
== Confirmation ==
 +
Open your web browser and access your repository via its URL, this should be done over HTTP.  When you click to login you should notice that you will be redirected to an HTTPS connection.  N.B. Any tasks that require you to be logged in will be redirected to an HTTPS connection otherwise an HTTP request will be used by default.
  
== Restart Apache to pick up the changes to the Apache configuration ==
+
== HTTPS Only ==
Consult your operating system documentation on how to restart service processes but in general you need to run one of the following commands either as <tt>root</tt> or using <tt>sudo</tt>:
+
EPrints default HTTPS configuration is usually sufficient for most institutions needs, as there is no absolute need to encrypt the requesting and sending of Open Access research.  However, if you wish to only ever use HTTPS, then follow the instructions for [[HTTPS-only and HSTS]].  HSTS (HTTP Strict Transport Security) ensures that even if the link you click on is for HTTP, your web browser will convert this to HTTPS before making the request.  Meaning you will never send any un-encrypted traffic to EPrints.  It also helps reduce the load on your repository's server, as it save it having to do the HTTP to HTTPS redirection.  
  # /sbin/service httpd restart
+
  
  # /etc/init.d/apache2 restart
+
It is generally a good idea to enable HSTS even on repositories with default HTTPS configuration, in case there are any errant bespoke links that could send private information using HTTP. This can be done by adding the following line to <tt>EPRINTS_PATH/archives/REPOID/ssl/securevhost.conf</tt> after the <tt>ServerName</tt> line and then restarting Apache again:
  
 
+
Header set Strict-Transport-Security "max-age=15780000"
== Confirmation ==
+
Open your web browser and access your repository via its URL, this should be done over HTTP.  When you click to login you should notice that you will be redirected to an HTTPS connection.  Note that in general most tasks that require you to login are now redirected to an HTTPS connection otherwise an HTTP request will be used.
+

Revision as of 01:08, 21 February 2018

Manual Sections

This guide is intended for EPrints 3.3 or later.

N.B. Setting up your Apache Web server is beyond the scope of this document. Please see your operating system documentation and the Apache documentation for assistance in setting up Apache in your environment.


Configuration

Below is a list of variable names described in these instructions and example values of what they might be in a real-world configuration.

Variable Example
EPRINTS_PATH /opt/eprints3
YOUR-REPOSITORY-DOMAIN example.eprints.org
REPOID example

To start setting up your existing archive to work under HTTPS, you must first edit EPRINTS_PATH/archives/REPOID/cfg/cfg.d/10_core.pl. Initially it will probably look something like the configuration directly below, which is the basic 10_core.pl configuration file after you have run EPRINTS_PATH/bin/epadmin create to setup your archive. Alternatively you could run /opt/eprints3/bin/epadmin config_core REPOID that will prompt you for the following information. It is suggested that you make a backup of the 10_core.pl file regardless before proceeding.

$c->{host} = 'YOUR-REPOSITORY-DOMAIN';
$c->{port} = 80;
$c->{aliases} = [];
$c->{securehost} = '';
$c->{secureport} = 443;
$c->{http_root} = undef;

Update the file to define the secure host and modify ports as needed. If your Apache web server is not using the standard ports (80,443) you can adjust the port and secureport parameters in the config file accordingly.

$c->{host} = 'YOUR-REPOSITORY-DOMAIN';
$c->{port} = 80;
$c->{aliases} = [];
$c->{securehost} = $c->{host};
$c->{secureport} = 443;
$c->{http_root} = undef;

Now, you need to create the directory EPRINTS_PATH/archives/REPOID/ssl/ and then edit the file REPOID/ssl/securevhost.conf. This file should look something like below. If you are installing EPrints on Debian/Ubuntu based systens you will need to create a symlink logs in /etc/apache2/ to point at /var/log/apache2/.

<VirtualHost *:443>

  ServerName YOUR-REPOSITORY-DOMAIN:443

  ErrorLog logs/ssl_error_log
  TransferLog logs/ssl_access_log
  LogLevel warn

  SSLEngine on
  SSLProtocol all -SSLv2 -SSLv3
  SSLHonorCipherOrder on
  SSLCipherSuite HIGH:!aNULL:!eNULL:!kECDH:!aDH:!RC4:!3DES:!CAMELLIA:!MD5:!PSK:!SRP:!KRB5:@STRENGTH

  SSLCertificateFile EPRINTS_PATH/archives/REPOID/ssl/YOUR-REPOSITORY-DOMAIN.crt
  SSLCertificateKeyFile EPRINTS_PATH/archives/REPOID/ssl/YOUR-REPOSITORY-DOMAIN.key
  SSLCertificateChainFile EPRINTS_PATH/archives/REPOID/ssl/YOUR-REPOSITORY-DOMAIN.ca-bundle

  SetEnvIf User-Agent ".*MSIE.*" \
    nokeepalive ssl-unclean-shutdown \
    downgrade-1.0 force-response-1.0

  CustomLog logs/ssl_request_log \
    "%t %h %{SSL_PROTOCOL}x %{SSL_CIPHER}x \"%r\" %b"

  Include EPRINTS_PATH/cfg/apache_ssl/REPOID.conf

  PerlTransHandler +EPrints::Apache::Rewrite

</VirtualHost>

It is advised that you keep the SSL key, certificate and chain files in the same directory as securevhost.conf, as this will make it easy if you need to migrate you EPrints repository to a new server in the future.

Generate the Apache Configuration File for HTTPS

Run EPRINTS_PATH/bin/generate_apacheconf --system --replace to generate the secure Apache configuration files. This will setup the repository configuration file located in the EPRINTS_PATH/cfg/apache_ssl/ directory named REPOID.conf.


Add the Main Apache Config File to SSL Config

Depending upon the version of EPrints you are running there are a couple files that may be involved. It is recommended to run EPRINTS_PATH/bin/generate_apacheconf --man or view the source of EPRINTS_PATH/bin/generate_apacheconf file to understand what file(s) need to be setup. Apache will not yet have been setup to include EPRINTS_PATH/archives/REPOID/ssl/securevhost.conf.

To include this, you will need to find the file that already includes cfg/apache.conf. (For Red Hat/Fedora/CentOS Linux you will need to look in /etc/httpd/. For Debian/Ubuntu Linux you will need to look in /etc/apache2/). Then add the following line after

Include EPRINTS_PATH/archives/*/ssl/securevhost.conf

Restart Apache to pick up the changes to the Apache configuration

Consult your operating system documentation on how to restart service processes but in general you need to run one of the following commands either as root or using sudo:

For Red Hat/Fedora/CentOS Linux

/sbin/service httpd restart

For Debian/Ubuntu Linux

Before restarting Apache make sure mod_ssl is enabled:

a2enmod ssl

Then restart Apache:

/etc/init.d/apache2 restart

Confirmation

Open your web browser and access your repository via its URL, this should be done over HTTP. When you click to login you should notice that you will be redirected to an HTTPS connection. N.B. Any tasks that require you to be logged in will be redirected to an HTTPS connection otherwise an HTTP request will be used by default.

HTTPS Only

EPrints default HTTPS configuration is usually sufficient for most institutions needs, as there is no absolute need to encrypt the requesting and sending of Open Access research. However, if you wish to only ever use HTTPS, then follow the instructions for HTTPS-only and HSTS. HSTS (HTTP Strict Transport Security) ensures that even if the link you click on is for HTTP, your web browser will convert this to HTTPS before making the request. Meaning you will never send any un-encrypted traffic to EPrints. It also helps reduce the load on your repository's server, as it save it having to do the HTTP to HTTPS redirection.

It is generally a good idea to enable HSTS even on repositories with default HTTPS configuration, in case there are any errant bespoke links that could send private information using HTTP. This can be done by adding the following line to EPRINTS_PATH/archives/REPOID/ssl/securevhost.conf after the ServerName line and then restarting Apache again:

Header set Strict-Transport-Security "max-age=15780000"