Skip to page content

SSL Configuration

The following information is valid for EZproxy 2.0e or later.

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.

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 want to test SSL features but do not have a license key, 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 VeriSign, Thawte, FreeSSL, 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 SSL Certificate Options for information on how remote browsers will respond based on the type of certificate you setup.

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.

  1. 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.
  2. 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 this line is in this form, then you should change it to:
    <form action="/login" method="post">
    This change will prevent EZproxy from forcing the use of https during login. Later on, this can be enabled, but it is left disabled during initial configuration.
  3. If you want to use https to encrypt user login processing or if you are using proxy by hostname, 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.

    If you are using a version of EZproxy prior to version 2.2a, you should also add:

    Option AllowHTTPLogin
    At this point, it will be possible to use https with EZproxy, but it will not be mandatory. This allows you to configure and test the SSL certificate without the need to worry about it impacting remote users who are using EZproxy.
  4. Login to your EZproxy server using a URL like:
    http://ezproxy.yourlib.org:2048/login
    using the username and password that were created in the first step.

    If you use CGI processing, you will need to login to your EZproxy server using a URL like:

    http://ezproxy.yourlib.org:2048/login?user=someuser&pass=somepass
  5. Go to:
    http://ezproxy.yourlib.org:2048/ssl
    and select the option to create a new certificate. On this page, you must fill in your two-letter country code, your unabbreviated state or province (e.g. Arizona not AZ), your organization, your e-mail address, and you may fill in the optional fields as well.

    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. To select this option, click on the Self-Signed Certificate option. If necessary, correct errors, then select this option again. Once this is complete, proceed to the next step.

    If you choose to purchase a certificate from a certificate authority, you should click on Certificate Signing Request. If necessary, correct errors and click Certificate Signing Request again. Once this is complete, you will need to go to your certificate authority and start the process to purchase 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, copy everything between the BEGIN CERTIFICATE REQUEST and END CERTIFICATE REQUEST lines, including all the hyphens, and paste this into the box provided by your certificate authority.

    Once you get your certificate back from the certificate authority (this may be a few minutes to a few days later), go to:

    http://ezproxy.yourlib.org:2048/ssl
    and click on your certificate signing request, then paste the certificate into box provided and click Save. EZproxy should accept the certificate. If it does, the Certificate Details page will display. If your certificate authority provides a chained certificate authority file, you can enter this on the Certificate Details page. With the Certificate Details page open still open, proceed to the next step.

  6. On the Certificate Details page, follow the instructions to make the certificate active.
  7. Once the certificate is active, restart EZproxy with the URL:
    http://ezproxy.yourlib.org:2048/restart
  8. 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 had to use a different port such as LoginPortSSL 9433, you will need to incorporate the port in the URL like:
    https://ezproxy.yourlib.org:9433/
    Note the use of https:// at the start of both of these sample URLs.
  9. 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 remove any line that states:
    Option AllowHTTPLogin
    If you are using EZproxy 2.2 or later, you must also add this line to config.txt/ezproxy.cfg:
    Option ForceHTTPSLogin

Encrypting user authentication with IMAP, LDAP and POP

For user login validation, if you want to use SSL with IMAP or POP authentication, you will need to add "ssl," after the second colon, such as:

::ssl,imap=imapserv.mylib.org
::ssl,pop=popserv.mylib.org

With LDAP authentication, you can use "URL ldaps://..." to specify the use of LDAP over SSL.