Using SSL with Web Interface
To configure CommitCRM with SSL you need to be using Microsoft IIS as the back end Web server for the Web interface.
Then - install and configure your SSL certificates in Microsoft IIS.
CommitCRM version 9, and above, are required in order to use Microsoft IIS with CommitCRM Web interface.
>>> Continue here: Using Microsoft IIS as the Web Server for the Web Interface
THE FOLLOWING ARE THE OLD INSTRUCTIONS ON HOW TO USE SSL WITH CommitCRM version 8 (or below). THIS OLD METHOD MIGHT BE EXPOSED TO VULNERABILITIES DISCOVERED IN THE SSL3 PROTOCOL AND SHOULD NOT BE USED ANYMORE. Instead - Use CommitCRM version 9, or above, together with Microsoft IIS as its back end Web server.
CommitCRM Web Interface supports the ability to accept SSL connections (https rather than http).
Using SSL with CommitCRM Web Interface is OPTIONAL. You can use CommitCRM Web Interface without setting up SSL.
The first step you should take if you want to use SSL with CommitCRM Web Interface is to obtain SSL certificates from an authorized SSL authority such as Verisign or Thawte.
Saving the Certificates Files
CommitCRM requires that your certificates files be in the .pem file format. You should have three certificates files with the following names:
Key.pem
Cert.pem
Root.pem
Place your certificates files in the following folder:
<Installation_DIR>\CommitCRM\WebInterface
If your certificates are in another file format, convert them to the .pem file format.
Read the SSL Troubleshooting to see how to convert certain types of SSL certificate file formats.
If you'd like to read a SSL Certificate creation tutorial, please click here.
Activating SSL with CommitCRM
You need to instruct CommitCRM Web Interface to use SSL. To do so, you must edit the following file:
<Installation_DIR>\CommitCRM\WebInterface\CommitWebInterface.ini
Change the token settings in the above file to Yes as follows:
UseSSLEncryption=Y
Setting the SSL Port
The SSL communication between users/browsers and CommitCRM Web Interface uses a dedicated port.
Set a port number for CommitCRM Web Interface. This port should not be in use by any other application or service.
We recommend using the CommitCRM default port for SSL: 4962.
If you decide to use another port, make sure that:
- You select a DIFFERENT port than the one used for standard connections (ServerPort).
- You select a port value other than the standard SSL port (443) which is probably already in use on your server (by IIS for example).
To configure the SSL port, set the SSLPort token value in the following settings file:
<Installation_DIR>\CommitCRM\WebInterface\CommitWebInterface.ini
Important Note:
If you use a firewall, proxy, etc., it is recommended that you open Port 4962 in order to allow a connection to be established with CommitCRM Web Interface.
If this port is blocked by a firewall, a connection cannot be established.
Setting SSL Certificate Password
If you have a password for your SSL Certificate (SSL Certificate passwords are optional), enter the password for the SSlPassword token in:
<Installation_DIR>\CommitCRM\WebInterface\CommitWebInterface.ini
Modifying the Login Page to Use SSL
To use an SSL secure connection, modify your login page as follows:
You should change:
- Http to Https
- Standard Port (default 4961) to the SSL Port (default 4962)
For example:
If you've used the predefined login page (as described in section C.(1) above)the link, from your web site, to the secure login page should appear as follows:
<A HREF="https://127.0.0.1:4962">Click to login</A>
If you have embedded the login fields on one of your web pages (as described in section C.(2) above), modify the JavaScript used to post the login request as follows:
Original: Method="post" action="http://127.0.0.1:4961"
Modified: Method="post" action="https://127.0.0.1:4962"
SSL Troubleshooting
Note:
The Web Interface Installation Troubleshooting section of this document is valid for SSL settings as well. Make sure you read it as well.
This section only deals with SSL specific issues:
Preparing SSL Certificate files (including converting them to the .pem file format if needed)
- General Information
This issue is relevant only when you configure CommitCRM Web Interface to use SSL. CommitCRM requires that your certificate files all have the .pem format.
If your certificates are in another format, convert them to the .pem format by following these instructions:
Note: This procedure assumes that you have already received your key and certificate pair from a Certificate Authority (like Verisign or Thawte) and that you have installed them in Microsoft Internet Explorer under the Personal Certificates tab.
Note 2: To install the certificates in Internet Explorer, follow these instructions:
Open Internet Options window: Internet Explorer > Tools > Internet Options
Navigate to the: Content tab
Click on the "Certificates" button
The Certificates Window dialog box will open.
Navigate to the Personal tab, select the Import option and follow the wizard to install your certificate.
- Export Certificate
The first step is to export your certificate to a .pfx file format.
Open Internet Options window: Internet Explorer > Tools > Internet Options
Navigate to the Content tab.
Click on the Certificates.
The Certificates Window dialog box will open.
Navigate to the Personal tab, select your installed certificate and select Export.
Follow the wizard and select to export it as a .pfx file (Personal Exchange Format).
You may optionally protect it with a password.
- Convert the exported .pfx file to a .pem format
To convert the .pfx file to a .pem file, you need to use a utility called openssl.exe.
The utility can be downloaded from CommitCRM's web site at the following URL:
http://www.rangermsp.comdownloads/openssl.exe
After downloading this file and saving it to your disk, open a command window and navigate to the folder where the utility is stored. Run the following command:
openssl.exe pkcs12 –in <your file>.pfx –out <your file>.pem
Where <your file> is the name of the file created during the export phase.
Openssl.exe will prompt you for a password. Enter it if you used one during the export phase, or leave it blank if you did not specify one.
It will also prompt you for a new password for the .pem file. This is optional, but if you protect it with a password be sure to enter the SSLPassword token in the CommitWebInterface.ini file as explained above.
- Splitting the .pem file
Now it is time to split the newly created .pem file into the different files required by Commit Web Interface.
If you examine the new .pem file with Notepad, you will notice that it consists of two parts:
- The private key
- the certificate (public key) part
Using Notepad, create a file called Key.pem
Into this file, paste everything between AND including these two statements:
-----BEGIN RSA PRIVATE KEY-----
-----END RSA PRIVATE KEY-----
Using Notepad create a file named: Cert.pem Into this file, paste everything between AND including these two statements:
-----BEGIN CERTIFICATE-----
-----END CERTIFICATE-----
The final stage is to obtain the Root.pem file.
This is the Certificate Authority certificate file. You can obtain this from Internet Explorer > Tools > Internet Options.
Navigate to the Content tab and click on Certificates.
In Trusted Root Certificate Authority tab, select the Authority that issued your certificate and the Export it in Base64 (cer) format.
The exported file format is the SAME as the .pem format, so after exporting it simply rename the file Root.pem and save it with the other certificate file in folder
<Installation_DIR>\CommitCRM\WebInterface