Install a Custom SSL Certificate

HTTPS (SSL) for Your Domains

You can only have one SSL certificate per Cloud instance; it must be in the PEM format. It must also cover every domain you intend to have resolve to your instance.

You can installing a custom SSL Certificate without touching the command line straight from the Dashboard in MODX Cloud. The high-level process is as follows:

1. Generate a certificate signing request (CSR)
2. Purchase your Certificate in PEM/NGINX/Apache format
3. Upload your Certificate to your Cloud instance

Collect the Right Information for a CSR

A CSR provides information to a Certificate Authority that is used to verify who you say you are. In order to facilitate a smooth and rapid verification process, it’s important to provide accurate information. It starts with the domain that you want to cover, referred to as the “Common Name”.

Common Names

Most people want a certificate that covers both example.com and www.example.com. Support for this is up to where you purchase your certificate, but most support this common scenario. In this case, use the root domain for the CSR request (example.com).

A common name is technically a fully qualified domain name (FQDN). Keep in mind that www.example.com, example.com and blog.example.com are each unique FQDNs. A single SSL Cert can cover multiple FQDNs, however.

If you need to cover multiple subdomains of one base URL with a single certificate, use a wildcard Common Name: *.example.com

If you need to cover multiple unique domains with a single certificate, you will need to purchase a multi-domain SSL cert that supports Subject Alternative Names (SANs). This would also cover example.org and example.co.uk (or more). Enter the common names separated by a comma.

Other Important Information for CSRs

When supplying the following information for a CSR, the following characters are prohibited: <>~ ! @ # $ % ^ * / \ ( ) ?

• Country—a 2-digit ISO code: https://www.iso.org/obp/ui/#search
• State or Province Name— the full name where your organization is located
• Locality—e.g., the city … for some City-States, like Stockholm or Vatican City, duplicate the entry here and for the State/Province
• Organization Name—The full legal name of your organization or company.
• Organization Unit Name (optional)—an example might be "MODX Cloud" is a organization unit within MODX Systems, LLC, or "Marketing". Skip this if you wish.
• Email Address—Make sure you can access this email address. SSL vendors frequently handle email address policies differently. Check their requirements before supplying this information, e.g., some require this to match the administrative, technical or billing contact listed on the domain registration.

Generate the CSR

CSR generation in MODX Cloud is almost instantaneous once you fill out the form:

1. In the MODX Cloud Dashboard, locate the Cloud you wish to add SSL to from the list of Clouds
2. Click on the Cloud name to view the Cloud Edit screen
3. Click on the Add-ons tab
   
   
4. Click the toggle at the right to start the process
5. Click the link to switch to custom SSL.
6. Click to Create a CSR
7. A form will pop up into which you will enter the common name of the domain (see Common Names, above) you are creating the CSR for, then click Next to proceed.
8. Complete the Organization Information and click Generate CSR.
9. Your CSR will be displayed for you to copy and use for the purchase of your certificate.

Upload the Certificate

If you just generated your CSR and had an SSL Certificate issued to you, the window to paste in the certificate may still be open in your browser. In this case, skip to step 6, below:

1. In the MODX Cloud Dashboard, locate the Cloud you need upload the newly purchased SSL certificate to, from the list of Clouds
2. Click on the Cloud name to view the Cloud Edit screen
3. Click on the Add-ons tab
4. Click to Upload Your Certificate
5. A form will pop up in your web browser
6. Paste your certificate into the Certificate text area
7. Click the Save button to complete the process

Once the above steps are complete, your SSL Certificate should be active within a few minutes.