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

From EPrints Documentation
Jump to: navigation, search
(Fixed files wrong way round for SSLCertificateFile and SSLCertificateKeyFile and added SSL config options that will score A on Qualsys SSL checker.)
(23 intermediate revisions by 7 users not shown)
Line 1: Line 1:
{{development}}
 
 
{{manual}}
 
{{manual}}
==Add HTTPS Settings==
 
  
For each <tt>ARCHIVEID.xml</tt> file, fill in the <tt>securehost</tt> and <tt>securepath</tt> entries.
+
[[Category:Authentication]]
  
Example:
+
'''This guide is intended for EPrints 3.2 or later.'''
  
<archive id="demo">
+
'''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.'''
    ....
 
    <securehost>secure.mydomain.com</securehost>
 
    <securepath>/demo</securepath>
 
    ....
 
</archive>
 
  
The <tt>securehost</tt> is vhosted on the same server as your EPrints archive(s).
 
  
Secure requests will be of the form <tt>https://securehost/securepath</tt>.
+
== Configuration ==
 +
''' It is assumed that EPrints is installed in the directory <tt>/opt/eprints3/</tt>. If EPrints is installed elsewhere on your server please substitute as appropriate.'''
  
<tt>securepath</tt> therefore differentiates requests from individual archives.
+
To start setting up your existing archive to work under HTTPS, you must first edit <tt>/opt/eprints3/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>/opt/eprints3/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.
  
==Generate Secure Config==
+
$c->{host} = 'your.dnshostname.org';
 +
$c->{port} = 80;
 +
$c->{aliases} = [];
 +
$c->{securehost} = &#39;&#39;;
 +
$c->{secureport} = 443;
 +
$c->{http_root} = undef;
  
  $ bin/generate_apacheconf
+
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.
  
As well as the usual apache configuration files, and depending on the version of EPrints, this will generate:
+
$c->{host} = 'your.dnshostname.org';
 +
$c->{port} = 80;
 +
$c->{aliases} = [];
 +
$c->{securehost} = $c->{host};
 +
$c->{secureport} = 443;
 +
$c->{http_root} = undef;
  
* an <tt>auto-secure.conf</tt> file in each archive's <tt>cfg</tt> directory (2.3.13)
+
Now, you need to create the directory <tt>/opt/eprints3/archives/[repoid]/ssl/</tt> and then edit the file <tt>/opt/eprints3/archives/[repoid]/ssl/securevhost.conf</tt>.  This file should look something like:
* an <tt>auto-your.secure.host.conf</tt> file (for each secure host) in the main <tt>cfg</tt> directory (2.3.11)
 
  
==Set up Secure Host==
+
<VirtualHost *:443>
 
+
Under Fedora Core 4, run:
+
  ServerName your.dnshostname.org:443
 
+
   
  $ yum install mod_ssl
+
  ErrorLog logs/ssl_error_log
 
+
  TransferLog logs/ssl_access_log
This sets up a test SSL server.
+
  LogLevel warn
 
+
===Certificates===
+
  SSLEngine on
 
+
  SSLProtocol all -SSLv2 -SSLv3
For a production system, you would need to provide the relevant certificates and tweak the mod_ssl config accordingly - see:  
+
  SSLHonorCipherOrder on
 
+
  SSLCipherSuite HIGH:!aNULL:!eNULL:!kECDH:!aDH:!RC4:!3DES:!CAMELLIA:!MD5:!PSK:!SRP:!KRB5:@STRENGTH
* [http://httpd.apache.org/docs/2.2/mod/mod_ssl.html Apache Module mod_ssl]
+
* [http://www.modssl.org/docs/2.8/ssl_faq.html mod_ssl FAQ]
+
  SSLCertificateFile /opt/eprints3/archives/[repoid]/ssl/your.dnshostname.org.crt
 
+
  SSLCertificateKeyFile /opt/eprints3/archives/[repoid]/ssl/your.dnshostname.org.key
Create a <tt>server.key</tt> on the EPrints server (remembering the passphrase you enter):
+
  SSLCertificateChainFile /opt/eprints3/archives/[repoid]/ssl/your.dnshostname.org.ca-bundle
 
+
  $ openssl genrsa -des3 -out server.key 1024
+
  SetEnvIf User-Agent ".*MSIE.*" \
 
+
    nokeepalive ssl-unclean-shutdown \
Create a certificate request:
+
    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>
  
$ openssl req -new -key server.key -out server.csr
+
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.
  
The important thing when answering the questions is the CommonName: if ultimately the secure web address of your EPrints server is <tt>https://www.myeprints.com</tt>, then the CommonName value to enter is exactly <tt>www.myeprints.com</tt>.
+
== Generate the Apache Configuration File for HTTPS ==
 +
Run <tt>/opt/eprints3/bin/generate_apacheconf --system --replace</tt> to generate the secure Apache configuration files.  Depending upon the version of EPrints you are using, it may copy the default template <tt>/opt/eprints3/archives/[repoid]/cfg/lang/en/templates/default.xml</tt> to the template used for HTTPS <tt>/opt/eprints3/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. (N.B. EPrints 3.3 and later now uses default.xml template for both HTTP and HTTPS).
  
Send the <tt>server.csr</tt> file to your Certificate Authority administrator, who should send you back a <tt>.cer</tt> file.
 
  
Copy <tt>server.key</tt> and the <tt>.cer</tt> file to the following locations:
+
== 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>/opt/eprints3/bin/generate_apacheconf --man</tt> or view the source of <tt>/opt/eprints3/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.
  
  /etc/httpd/conf/ssl.key/server.key
+
  Include /opt/eprints3/archives/[repoid]/var/auto-secure.conf
/etc/httpd/conf/ssl.crt/eprints.cer
 
  
Modify <tt>/etc/httpd/conf.d/ssl.conf</tt> accordingly:
+
Or
  
  SSLCertificateFile /etc/httpd/conf/ssl.crt/eprints.cer
+
  Include /opt/eprints3/cfg/apache_ssl.conf
SSLCertificateKeyFile /etc/httpd/conf/ssl.key/server.key
 
  
===Include EPrints SSL config===
+
=== For Red Hat/Fedora/CentOS Linux ===
 
+
Add then add the appropriate Include line above, to the end of <tt>/etc/httpd/conf.d/ssl.conf</tt>
Include each <tt>auto-secure.conf</tt> file generated by EPrints inside the <tt>Virtualhost</tt> directive.
 
 
 
On FC4, edit <tt>/etc/httpd/conf.d/ssl.conf</tt>:
 
 
 
<VirtualHost _default_:443>
 
    ....
 
    Include /opt/eprints2/archives/ARCHIVEID/cfg/auto-secure.conf # 2.3.13
 
    Include /opt/eprints2/cfg/auto-your.secure.host.conf # 2.3.11
 
</VirtualHost>
 
  
If you have set up SSL certificates, you will be asked to enter your passphrase when you restart apache. To override this, see [http://www.modssl.org/docs/2.8/ssl_faq.html#remove-passphrase How can I get rid of the pass-phrase dialog at Apache startup time?].
+
=== For Debian/Ubuntu Linux ===
 +
Make sure the SSL Apache module is enabled, by running the following (as root):
 +
/usr/sbin/a2enmod ssl
 +
Add then add the appropriate <tt>Include</tt> line above, just before the <tt>&lt;/IfModule&gt;</tt> line in <tt>/etc/apache2/mods-enabled/ssl.conf</tt>
  
==Create Template for Secure Pages==
 
  
Make a copy of <tt>template-en.xml</tt>:
+
== 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>:
  
  $ cp template-en.xml template-secure-en.xml
+
=== For Red Hat/Fedora/CentOS Linux ===
 +
  /sbin/service httpd restart
  
In a multi-language archive, you would need to do this for each language-specific template.
+
=== For Debian/Ubuntu Linux ===
 +
/etc/init.d/apache2 restart
  
It's a good idea to have a visual differentiation between secure and non-secure pages, e.g. edit <tt>template-secure-en.xml</tt> and add "(SECURE)" to the title of the page.
+
== 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.
  
Some browsers will complain if images/CSS etc. embedded in a secure page are served by the non-secure host. To solve this, add a new entity to <tt>ArchiveConfig.pm/sub get_entities</tt>:
+
EPrints default HTTPS configuration is usually sufficient for most institutions needs, as there is no real 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.
  
  $entities{https_base_url} = "https://" . $archive->get_conf("securehost") . $archive->get_conf("securepath");
+
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>/opt/eprints3/archives/[repoid]/ssl/securevhost.conf</tt> after the <tt>ServerName<//tt> line and then restarting Apache again:
  
Now replace image/CSS <tt>base_url</tt>s with <tt>https_base_url</tt>.
+
Header set Strict-Transport-Security "max-age=15780000"

Revision as of 15:30, 20 November 2017

Manual Sections

This guide is intended for EPrints 3.2 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

It is assumed that EPrints is installed in the directory /opt/eprints3/. If EPrints is installed elsewhere on your server please substitute as appropriate.

To start setting up your existing archive to work under HTTPS, you must first edit /opt/eprints3/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 /opt/eprints3/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.dnshostname.org';
$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.dnshostname.org';
$c->{port} = 80;
$c->{aliases} = [];
$c->{securehost} = $c->{host};
$c->{secureport} = 443;
$c->{http_root} = undef;

Now, you need to create the directory /opt/eprints3/archives/[repoid]/ssl/ and then edit the file /opt/eprints3/archives/[repoid]/ssl/securevhost.conf. This file should look something like:

<VirtualHost *:443>

  ServerName your.dnshostname.org: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 /opt/eprints3/archives/[repoid]/ssl/your.dnshostname.org.crt
  SSLCertificateKeyFile /opt/eprints3/archives/[repoid]/ssl/your.dnshostname.org.key
  SSLCertificateChainFile /opt/eprints3/archives/[repoid]/ssl/your.dnshostname.org.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 /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

Run /opt/eprints3/bin/generate_apacheconf --system --replace to generate the secure Apache configuration files. Depending upon the version of EPrints you are using, it may copy the default template /opt/eprints3/archives/[repoid]/cfg/lang/en/templates/default.xml to the template used for HTTPS /opt/eprints3/archives/[repoid]/cfg/lang/en/templates/secure.xml. This will also setup the repository configuration file located in the /opt/eprints3/cfg/apache_ssl/ directory named [repoid].conf. (N.B. EPrints 3.3 and later now uses default.xml template for both HTTP and HTTPS).


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 /opt/eprints3/bin/generate_apacheconf --man or view the source of /opt/eprints3/bin/generate_apacheconf 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 /etc/httpd/conf.d/mod_ssl.conf or /etc/httpd/conf.d/ssl.conf). Make sure that these lines are placed inside the <VirtualHost> Apache directive.

Include /opt/eprints3/archives/[repoid]/var/auto-secure.conf

Or

Include /opt/eprints3/cfg/apache_ssl.conf

For Red Hat/Fedora/CentOS Linux

Add then add the appropriate Include line above, to the end of /etc/httpd/conf.d/ssl.conf

For Debian/Ubuntu Linux

Make sure the SSL Apache module is enabled, by running the following (as root):

/usr/sbin/a2enmod ssl

Add then add the appropriate Include line above, just before the </IfModule> line in /etc/apache2/mods-enabled/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 root or using sudo:

For Red Hat/Fedora/CentOS Linux

/sbin/service httpd restart

For Debian/Ubuntu Linux

/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.

EPrints default HTTPS configuration is usually sufficient for most institutions needs, as there is no real 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 /opt/eprints3/archives/[repoid]/ssl/securevhost.conf after the ServerName<//tt> line and then restarting Apache again:

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