Securing your site with SSL has many advantages. It provides data encryption, gives users peace of mind, and is a tried and tested solution. However, it can often be tricky to get everything set up and working together. In this guide we will go over how to get SSL attached to your Modulus projects. Keep in mind you will have to set up a custom domain before you go through this guide.
Alternatively, the ExpeditedSSL Add-On will walk you through the setup process and provide a preconfigured custom SSL Certificate specifically for your Modulus Project.
Since there are many choices involved with picking the right certificate for your needs, we will only document the process after purchase. In this example, we are using a wildcard certificate, purchased from Namecheap, with Comodo as our Certificate Authority (CA).
Generating a Certificate Signing Request
Once you have your certificate purchased, you will have to create a Certificate Signing Request, or CSR. This will allow the CA verify that you are who you say you are, and that the certificate (and domain) belongs to you.
In order to generate a CSR, you will need a command-line tool called OpenSSL. It is available for every major platform, and allows us to easily generate the files the CA is looking for. Once you have OpenSSL installed, open up a terminal window. We first need to generate a private key.
$ sudo openssl genrsa -out moxles.com.key 2048 Generating RSA private key, 2048 bit long modulus ........................................... ................................................+++ ......................................+++ e is 65537 (0x10001)
Keep this private key around. You will have to provide it to Modulus later. For now we have to use it to generate the CSR itself. Again, we are going to use OpenSSL to do this.
> sudo openssl req -new -key moxles.com.key -out moxles.com.csr You are about to be asked to enter information that will be incorporated into your certificate request. What you are about to enter is what is called a Distinguished Name or a DN. There are quite a few fields but you can leave some blank For some fields there will be a default value, If you enter '.', the field will be left blank. ----- Country Name (2 letter code) [AU]:US State or Province Name (full name) [Some-State]:Ohio Locality Name (eg, city) :Springfield Organization Name (eg, company) [Internet Widgits Pty Ltd]:Software, Inc. Organizational Unit Name (eg, section) :Domain Department Common Name (e.g. server FQDN or YOUR name) :*.moxles.com Email Address :firstname.lastname@example.org Please enter the following 'extra' attributes to be sent with your certificate request A challenge password : An optional company name :
Notice that I have not passed in a challenge password. This is important because Modulus does not support password-protected certificates. You should always leave this empty when generating a CSR.
Using the CSR
Now we have to pass this CSR off to Namecheap/Comodo. All you have to do is copy the text of the CSR file you generated into the CSR field during the first part of the submission process. Its important to copy all of the contents of the file, including the "BEGIN" and "END" statements.
During this process, you may be asked what type of server you have. For this, you can just select anything with "apache" or "openssl" in the name. In this example I choose "Apache + OpenSSL". However, what you select has no impact on the certificates generated by NameCheap.
Then you just finish up the process by answering various questions about your domain and who you are. Once this is done, you will be sent an email. The verification process will be different for everyone, so follow the instructions given in the various emails.
Creating a Certificate Bundle
Once you have completed the verification process, you will be emailed your certificate files. Make you sure download the attached zip and not just "plain text" certificate some providers give you in the email itself. If they do provide you a "plain text" certificate, you can ignore it. Here are the files for the Moxles SSL. Your files may be named different, but they should be similar.
Comodo has changed the way they distribute their certificates. They now
only provide a example_com.crt and example_com.ca-bundle
"bundle" may be misleading as it doesn't include the domain
certificate, only the CA's.
Now we have to create a "bundle" of all our certificate files. We do this by concatenating all the files together into one, big bundle file. However, the order of these files matters greatly, so make sure you follow the order given below.
- Domain specific cert or server cert. Usually has the domain somewhere in the filename.
- Domain specific cert / or server cert
- Domain bundle
You can create the bundle via your favorite text editor, or you can use the command line. The *inx command to concatenate all the files is below.
cat STAR_moxles_com.crt COMODORSADomainValidationSecureServerCA.crt \ COMODORSAAddTrustCA.crt \ AddTrustExternalCARoot.crt > star.moxles.com.chained.crtThis is the command if you just have the crt and bundle:
cat STAR_domain_com.crt STAR_YourDomain_com.ca-bundle > \ star.YourDomain.com.chained.crt
And the windows equivalent.
type STAR_moxles_com.crt COMODORSADomainValidationSecureServerCA.crt ^ COMODORSAAddTrustCA.crt ^ AddTrustExternalCARoot.crt > star.moxles.com.chained.crt
Adding the Bundle to Your Project
Once you have created your bundle, all you have to do is add this bundle, along with your private key, to your Modulus project. You can find the SSL section in the Administration tab of your project dashboard.
Simply click the "+" symbol to add a your information. Keep in mind you will have to already have added a domain to your project. When copying the certificate information, make sure to copy the BEGIN and END statements for both your bundle and your private key. The bundle goes into the "Certificate" field.
All that is left is to open up your project's URL and make sure you get a "green" lock for your domain. If you want to check out the Moxles example, you can visit ssl.moxles.com to check it out.
The onmodulus.net Certificate is Being Served Instead of Mine
The most common issue with setting up SSL is a nasty error saying that onmodulus.net certificate was provided instead of your domain's. This happens when termination of your certificate has failed, and can have any number of many causes.
If you are still having trouble figuring what might be the cause, below are a few general rules of thumb to follow while you debug.
- Make sure your certificate is not password protected. If you suspect your certificate is, you can use OpenSSL to stripe the password. This link has more information on how to do that. http://wiki.apache.org/httpd/RemoveSSLCertPassPhrase
- Make sure your bundle is ordered correctly. If just one file is left out or in the wrong order, it will fail.
- Make sure the private key you provide is the one you used to generate the original CSR. You cannot generate a new one without reassigning the entire certificate, IE going through the whole verification and generation process again.
I Get a Certificate Chain Error in Some Browsers
Sometimes you may also get a certificate chain error. This happens when your certificate may be validating in some browsers but give a warning in others. Most commonly Google Chrome or Safari will load the certificate fine, but Firefox will throw a "certificate chain" error.
To troubleshoot this, visit http://www.sslshopper.com/ssl-checker.html and check enter your site's URL. This should give you a general idea about where in the chain your SSL is failing. For an example of what it should look like, you can run ssl.moxles.com through it.
For most sites, the problem occurs because only the domain-specific certificate was provided, or one of the files required for the bundle is missing. Most browsers will accept and use a domain certificate, while others require an entire "chain" of certificates bundled together.
Some Mobile Devices Won't Accept My Certificate
If desktop browsers and most mobile browsers accept your certificate chain without issue, but a few are having problems, you may be having compatibility issues with how Modulus terminates your SSL connections.
In order to terminate SSL connections on your behalf, Modulus is required to use what a technology called Server Name Identification or SNI for short. Unfortunately not all mobile browsers support this type of authentication/handshake. The only way around this issue is to set up a dedicated proxy that will do the termination directly, without the use of SNI. You can use the contact link below to request pricing and information.
If you are confident you have taking all the correct steps and you are still running into problems, you are always welcome to contact support.
Go to top