|
|
|
SSL Configuration
Minimum version
The following information is valid for EZproxy 2.2a or later.
Overview
Secure Socket Layer (SSL) is the technology used to provide secure network access for protocols
such as https. SSL encryption technology falls under export restrictions, so the SSL features
in EZproxy are disabled by default. These feature are automatically enabled by any EZproxy license
key, including a demo license key.
The key use of SSL by EZproxy is to support secure web access with https. EZproxy can use https to secure the login page accessed by your users, and to
proxy access to licensed content that uses https.
To configure EZproxy for SSL, you need to create an SSL certificate. This page will guide
you through the steps required to create a certificate and activate it for use by EZproxy.
OpenSSL
The SSL features of EZproxy use the OpenSSL Toolkit.
The EZproxy program file contain the OpenSSL routines required by EZproxy, so no separate library files
need to be downloaded to provide this functionality.
If you are currently evaluating EZproxy and have not yet purchased a license, you need
to send a request to ezproxy@oclc.org for a demo key.
Certificate renewal
If you are already using SSL with EZproxy and need to renew your existing certificate, refer to SSL Certificate Renewal for more information.
Certificates
EZproxy allows you to generate self-signed certificates or to request certificates from a certificate
authority such as ipsCA, VeriSign, Thawte, etc.
For initial testing, you should just generate a self-signed certificate.
If you want to test interacting with a certificate authority, it is safest to
request only free test certificates. If you actual pay money for a certificate,
make certain that you are backing up your EZproxy installation, and particularly
the new ssl subdirectory, since if you lose these files, you may have to pay
to replace the certificate.
Before you proceed, you should review this entire document to understand the configuration steps involved and you should also review SSL Certificate Options for information on how remote browsers will
respond based on the type of certificate you choose.
Configuration
The following instructions explain how to configure the EZproxy to enable SSL support. In all of these examples, in any location where http://ezproxy.yourlib.org:2048 appears, you should substitute your own EZproxy server name
and port.
If your EZproxy server was installed in August 2003 or later, you can skip this step.
There is directory named docs in the directory where EZproxy is installed. Within
that directory are the files login.htm and loginbu.htm. Edit these file with a text editor and
look for a line like:
<form action="^L" method="post">
If you find such a line, change it to:
<form action="/login" method="post">
If you are using proxy by hostname, or if you are using proxy by port and want to use https to encrypt user login processing, edit
config.txt/ezproxy.cfg
and add a line like:
LoginPortSSL 443
443 is the preferred number as this is the standard port for use with https. However,
if you already have a secure web server running on the same system as EZproxy, it will already be using
port 443. In this case, you will need to either setup two separate
IP addresses on your server, or
you will need to pick an alternate number such as:
LoginPortSSL 2443
If you use a firewall, you may need to configure it to allow access to the port you select. -
Check config.txt/ezproxy.cfg to see if it contains the directive:
Option IgnoreWildcardCertificate
If you find this directive, it indicates that your EZproxy server may be using a wildcard certificate that was created
outside of EZproxy and imported manually. This option can interfere with certificates created within EZproxy. If you find this
directive and you are planning to create a certificate from within EZproxy, you should delete this directive.
- If you have not already done so, edit
user.txt/ezproxy.usr
and add a line similar to this:
someuser:somepass:admin
You can pick any username for someuser and any password for somepass. You will use
this account to login to EZproxy with administrative access.
Login to your EZproxy server using a URL like:
http://ezproxy.yourlib.org:2048/admin
using the username and password that were created in the previous step.
If you use CAS, CGI, or Shibboleth for user authentication, please
consult EZproxy Administration for
additional steps that are required to access the administration page.
- From the EZproxy administration page, click on Manage SSL (https) certificates. This page is referred to as
the SSL management page throughout the rest of this document.
- On the SSL management page, click on the option to create a new certificate.
When creating a new certificate, you must
fill in your two-letter country code, your unabbreviated state or province
(e.g. Ohio not OH), your organization, and your e-mail address. You may fill in
the other fields as well. If you are purchasing a certificate, your certificate authority
may have specific requirements regarding which fields must be completed or omitted.
-
You must now decide whether you want to use a self-signed certificate or purchase
a certificate from a certificate authority. A self-signed certificate is free, but will
cause a browser warning when people access your EZproxy server.
For more information on differences in browser
behavior, consult SSL Certificate Options.
If you want to purchase a certificate, skip to step 10.
To create a self-signed certificate, click on the Self-Signed Certificate option. If necessary,
correct errors, then select this option again. Once you see the Certificate Details page,
skip to Step 14: Self-signed certificate from step 9...
-
To purchase a certificate from a certificate authority, click on Certificate Signing Request (CSR). If necessary, correct errors
and click Certificate Signing Request again. Once this is complete, EZproxy
will display a Certificate Signing Request (CSR), which is a block of lines that looks like this:
-----BEGIN CERTIFICATE REQUEST-----
MIIBxTCCAS4CAQAwgYQxHjAcBgNVBAMUFSouZXpwcm94eS55b3VybGliLm9yZzEL
MAkGA1UEBhMCVVMxEDAOBgNVBAgTB0FyaXpvbmExGTAXBgNVBAoTEFVzZWZ1bCBV
-----END CERTIFICATE REQUEST-----
You will need to submit this text to your certificate authority.
While your certificate request is being processed, do not delete the certificate signing request. When you receive your certificate,
it must be applied against the original request.
-
Visit the web site of your certificate authority and follow their procedure for purchasing a certificate.
When purchasing, if you are asked for your web server type, select Apache+ModSSL
or just Apache as either is directly compatible with EZproxy.
When
you are asked for your certificate signing request, you will need to paste
in everything from the certificate signing request created earlier, starting with the BEGIN CERTIFICATE REQUEST line through the and END CERTIFICATE REQUEST line,
including all the hyphens. If you have closed out of EZproxy, you can repeat the previous steps to access
SSL management, and from there click on your certificate signing request to access this information again.
-
Depending on the policies of your certificate authority, it may take a few minutes or a few days to receive your certificate. The certificate will look similar to:
-----BEGIN CERTIFICATE-----
MIIF5jCCBU+gAwIBAgIDAJAYMA0GCSqGSIb3DQEBBQUAMIGjMQswCQYDVQQGEwJF
UzESMBAGA1UECBMJQkFSQ0VMT05BMRIwEAYDVQQHEwlCQVJDRUxPTkExGTAXBgNV
-----END CERTIFICATE-----
In addition to the certificate for your server, the certificate authority may also provide intermediate or chained certificates. At this point, you should only be working with the certificate that has been issued for your server. See step 13 for instructions on working with intermediate certificates.
Once you have your certificate, return to the SSL management page and click on your certificate signing request, paste in all of the lines from BEGIN CERTIFICATE through
END CERTIFICATE into the certificate box, and click Save. EZproxy should accept the certificate. If it does not accept the certificate, insure that you are copying the
certificate for your server and not an intermediate certificate, then try pasting again and saving again.
Two common causes that prevent being able to save a certificate are:
-
Creating a certificate signing request, submitting this original to your certificate authority, deleting the original request, receiving the certificate from your
authority, recreating the request, and then trying to apply the certificate to the recreated request. A certificates is bound to a key that is created as part
of the original certificate signing request, and cannot be applied to any other certificate signing request. If you make this mistake, you will need to resubmit
the new certificate signing request to your certificate authority and ask them to use it to replace your certificate.
-
Creating a certificate signing request and then trying to apply an existing certificate that was created outside of EZproxy against the certificate signing request. Once again, certificates are bound to their original requests, so this process will fail. In EZproxy 5.1, the SSL management page has an option to import existing certificates. You can
use this option to bring existing certificates into EZproxy if necessary.
-
If your certificate authority provides a intermediate certificate file or chained certificate authority file, you can enter this on the
Certificate Details page. First, you will need to obtain this file from your certificate authority. Once you have it, open the
file with a text editor and use select all and copy. Next, open up the Certificate Details page in EZproxy and paste the
intermediate certificate into the box toward the end of the page, and use the option to save the intermediate certificate. Changes to
intermediate certificates take effect immediately, with no need to restart EZproxy.
-
Self-signed certificate from step 9 and certificate authority issued both continue here.
On the Certificate Details page, follow the instructions to make the certificate
active.
- Once the certificate is active, use the option in the upper left to return to the main administration page, and on that page, use the
option to restart EZproxy.
-
Steps 17 and 18 provide information on how to test https and how to configure EZproxy to force the use of https during login.
For ease of maintenance and maximum flexibility, it is best to create EZproxy URLs using http. There is no need to change
existing URLs from http to https when configuring SSL.
More information on how to force the use of https during login appears at the end of these instructions.
If you established a LoginPortSSL statement, then you should now be able to access EZproxy
securely.
If you used LoginPortSSL 443, then you can try a URL like:
https://ezproxy.yourlib.org/
If you are using proxy by hostname with a wildcard certificate such as *.ezproxy.yourlib.org, you will need to add login. to your server name to avoid browser warnings with a URL like:
https://login.ezproxy.yourlib.org/
If you used a different port such as LoginPortSSL 9433, you will need to incorporate the port in the URL such as:
https://ezproxy.yourlib.org:9433/
If you use a wildcard certificate with a port other than 443, your test URL will combine both of these details to look like:
https://login.ezproxy.yourlib.org:9433/
Note the use of https:// at the start of all of these sample URLs. - Once you are satisfied that your new certificate works, you can choose to require the use of
https during login.
If you would like to force the use of https when the login page is presented,
you can edit
config.txt/ezproxy.cfg and add this directive:
Option ForceHTTPSLogin
anywhere in the file.
In extremely old installations of EZproxy, it may also be necessary to remove the following line:
Option AllowHTTPLogin
Once you put this directive in place, you need to restart EZproxy to make this option take effect.
With Option ForceHTTPSLogin in place, whenever EZproxy needs to present the login page, it will insure that an https connection is being used. If the
request is made with http, EZproxy will automatically redirect to the appropriate URL for https, including adding "login." in the front of the
hostname if required for proxy by hostname with a wildcard certificate.
|
|
Librarians' Toolbox:
