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

From EPrints Documentation
Jump to: navigation, search
Line 2: Line 2:
 
{{ep2}}
 
{{ep2}}
 
{{manual}}
 
{{manual}}
==Add HTTPS Settings==
+
==Setting up HTTPS under EPrints 3.0.5+/3.1==
  
For each <tt>ARCHIVEID.xml</tt> file, fill in the <tt>securehost</tt> and <tt>securepath</tt> entries.
+
EPrints 3.0.5 (or EPrints 3.1) introduces a revised process for using EPrints under HTTPS. These instructions apply to users setting up a new repository - existing repositories will have old (incompatible) templates.
  
Example:
+
===Configuration===
  
<archive id="demo">
+
Edit <tt>archives/[repoid]/cfg/cfg.d/10_core.pl</tt>. It will probably look like this:
    ....
+
    <securehost>secure.mydomain.com</securehost>
+
    <securepath>/demo</securepath>
+
    ....
+
</archive>
+
  
The <tt>securehost</tt> is vhosted on the same server as your EPrints archive(s).
+
$c->{host} = 'yomiko.ecs.soton.ac.uk';
 +
$c->{port} = 8080;
 +
$c->{aliases} = [];
 +
#$c->{securehost} = 'yomiko.ecs.soton.ac.uk';
 +
#$c->{secureport} = 8083;
 +
#$c->{securepath} = '/secure';
  
Secure requests will be of the form <tt>https://securehost/securepath</tt>.
+
Add to the end of this file the following settings:
  
<tt>securepath</tt> therefore differentiates requests from individual archives.
+
$c->{securehost} = 'HOSTNAME';
 +
#$c->{secureport} = 'PORT';
  
==Generate Secure Config==
+
$c->{http_root} = "";
 +
$c->{https_root} = '/secure';
 +
$c->{http_cgiroot} = '/cgi';
 +
$c->{https_cgiroot} = '/secure/cgi';
  
$ bin/generate_apacheconf
+
Where HOSTNAME is the hostname of your HTTPS server. If your HTTPS server is not using the standard port 443 specify it here. The <tt>http(s)_(cgi)root</tt> variables specify the path to EPrints on your HTTP and HTTPS servers.
  
As well as the usual apache configuration files, and depending on the version of EPrints, this will generate:
+
Now run <tt>bin/generate_apacheconf</tt> to generate the secure Apache configuration and copy the default template to the template used for HTTPS.
  
* an <tt>auto-secure.conf</tt> file in each archive's <tt>cfg</tt> directory (2.3.13)
+
Add the following line inside your Apache SSL virtual host declaration (probably in <tt>/etc/httpd/conf.d/mod_ssl.conf</tt>):
* 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==
+
Include /opt/eprints3/archives/[repoid]/var/auto-secure.conf
  
Under Fedora Core 4, run:
+
Restart Apache.
 
+
$ yum install mod_ssl
+
 
+
This sets up a test SSL server.
+
 
+
===Certificates===
+
 
+
For a production system, you would need to provide the relevant certificates and tweak the mod_ssl config accordingly - see:
+
 
+
* [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]
+
 
+
Create a <tt>server.key</tt> on the EPrints server (remembering the passphrase you enter):
+
 
+
$ openssl genrsa -des3 -out server.key 1024
+
 
+
Create a certificate request:
+
 
+
$ openssl req -new -key server.key -out server.csr
+
 
+
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>.
+
 
+
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:
+
 
+
/etc/httpd/conf/ssl.key/server.key
+
/etc/httpd/conf/ssl.crt/eprints.cer
+
 
+
Modify <tt>/etc/httpd/conf.d/ssl.conf</tt> accordingly:
+
 
+
SSLCertificateFile /etc/httpd/conf/ssl.crt/eprints.cer
+
SSLCertificateKeyFile /etc/httpd/conf/ssl.key/server.key
+
 
+
===Include EPrints SSL config===
+
 
+
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
+
    Include /opt/eprints3/archives/soton/var/auto-secure.conf # 3.0.0
+
</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?].
+
 
+
==Create Template for Secure Pages==
+
 
+
Make a copy of the default template in <tt>archives/ARCHIVEID/cfg/lang/en/templates/</tt>:
+
 
+
$ cp default.xml secure.xml
+
 
+
In a multi-language archive, you would need to do this for each language-specific template (en = ENglish).
+
 
+
It's a good idea to have a visual differentiation between secure and non-secure pages, e.g. edit <tt>secure.xml</tt> and add "(SECURE)" to the title of the page.
+
 
+
Some browsers will complain if images/CSS etc. embedded in a secure page are served by the non-secure host. To solve this modify the <tt>secure_urlpath</tt> and <tt>secure_url</tt> entries in <tt>archives/ARCHIVEID/cfg/cfg.d/20_baseurls.pl</tt>:
+
 
+
$c->{secure_urlpath} = "";
+
$c->{secure_url} = "https://".$c->{securehost}.$c->{securepath};
+
 
+
In the <tt>secure.xml</tt> template replace image/CSS <tt>base_url</tt>s with <tt>secure_url</tt>.
+
 
+
BUG FIX: In bin/generate_static replace <tt>import url($base_url$1);</tt> with <tt>import url($1);</tt>.
+

Revision as of 16:38, 7 April 2008

Warning This page is under development as part of the EPrints 3.0 manual. It may still contain content specific to earlier versions. Manuals for previous versions of EPrints are also available.

Please note! This page was written for EPrints version 2 and may not apply to version 3.


Manual Sections

Setting up HTTPS under EPrints 3.0.5+/3.1

EPrints 3.0.5 (or EPrints 3.1) introduces a revised process for using EPrints under HTTPS. These instructions apply to users setting up a new repository - existing repositories will have old (incompatible) templates.

Configuration

Edit archives/[repoid]/cfg/cfg.d/10_core.pl. It will probably look like this:

$c->{host} = 'yomiko.ecs.soton.ac.uk';
$c->{port} = 8080;
$c->{aliases} = [];
#$c->{securehost} = 'yomiko.ecs.soton.ac.uk';
#$c->{secureport} = 8083;
#$c->{securepath} = '/secure';

Add to the end of this file the following settings:

$c->{securehost} = 'HOSTNAME';
#$c->{secureport} = 'PORT';
$c->{http_root} = "";
$c->{https_root} = '/secure';
$c->{http_cgiroot} = '/cgi';
$c->{https_cgiroot} = '/secure/cgi';

Where HOSTNAME is the hostname of your HTTPS server. If your HTTPS server is not using the standard port 443 specify it here. The http(s)_(cgi)root variables specify the path to EPrints on your HTTP and HTTPS servers.

Now run bin/generate_apacheconf to generate the secure Apache configuration and copy the default template to the template used for HTTPS.

Add the following line inside your Apache SSL virtual host declaration (probably in /etc/httpd/conf.d/mod_ssl.conf):

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

Restart Apache.