Acme Certificate

Version 2.0.0

Last Updated May 13, 2018

Table Of Contents


Configuration

There are two pieces that need to be configured before you can encrypt your website with your free SSL certificate. Both of them are configured in the same place. To get there, go to your Admin Tools > Installed Plugins. You will find a new button that looks suspiciously like the one below. In this new page you will find the two sections that need your attention.

Plugin Button

Account Settings

All Acme Certificate Authorities require you to register with them. Primarily this is to alert you of any certificates that are about to expire so you get a final warning just in case something doesn't work with automatic renewals. But they may also use this account to alert you to any other changes that may affect your account, such as new terms of use. When you first get to the Acme Certificates page you will need to use the Register button to register your account.

Be sure to use a real e-mail address that somebody will watch. They do not send you unsolicited e-mail and you will want any alerts that they do send you so you don't suddenly find yourself without a valid certificate.

Registering your account is as simple as putting in your e-mail address and agreeing to the terms of service. There is a checkbox called Test Mode that you will most likely want to leave off. This causes the plugin to use their test servers and will issue you test certificates that are not valid to the rest of the Internet. Leave this box turned off unless you know what you are doing.

Once you are done click the Save button and your account will be created. Don't worry, there are no passwords or anything to setup. A single e-mail address can even be used for multiple accounts. The key that identifies your account is now safely stored inside Rock.

Certificates

Most people will only have a single certificate configured. This plugin can put multiple domain names on a single certificate and even install that certificate on multiple IIS sites configured on your server. So the only reason you need multiple certificates is if you have a specific need to keep your site certificates separate.

Once your account is registered you can add your first certificate. Click the + button to create a new certificate request. You will need to provide a friendly name (this is what you will see in IIS if you look at the bindings) as well as the domain names to be certified. Any domain name that is entered in the URL to reach your Rock server should be listed here. For example, if your Rock domain is rocksolidchurch.com, you would probably have the following domains pointing to your server:

  • rocksolidchurch.com
  • www.rocksolidchurch.com
  • rock.rocksolidchurch.com

Even if you have rocksolidchurch.com setup to redirect to www.rocksolidchurch.com you will want to list it since they might use that domain to reach your server initially before being redirected. I cannot give you a full list of the domains you will need to list, the above is just an example that will be common to most people. If you are going to be using the same certificate to secure other IIS sites besides your Rock installation, list all of their domain names as well.

You may have noticed the Recommend Configuration button. This will attempt to detect your domain names and bindings that need to be configured and fill them in for you. While this may be perfectly accurate for most systems, it does depend on your Rock install having been setup correctly. For example, when detecting the domain names it uses the domains entered in the Rock Sites configuration. If you have not entered all the domain names you are using then it obviously can't magically determine those. The information that is filled in for you should be used as a starting point. Take a look and make any changes you need, but most likely the things added will be a minimum set of required settings.

Next, and finally, is configuring the bindings. This is what tells IIS which certificate to use for which sites. Many people have a straight forward installation. There is a single IIS site and a single IP Address on their server and it runs nothing but Rock. In this case you will have a single "catch all" entry. More complex configuration is allowed, but you will want to get whomever configured your IIS server involved to help you setup the bindings. In fact, if that wasn't you it's a good idea to get them involved anyway just to make sure you are configuring things correctly.

A sample, common, binding would be one for the Default Web Site on port 443. If you leave the IP Address blank then it will bind to all IP Addresses on the server. Similarly, if you leave the domain blank then it will be the "catch all" binding. This is your most common configuration. If you have multiple IIS sites and a single IP address, you will probably have more bindings to configure, one for each Rock domain.

Please consult your IT department about what bindings to configure. In fact, it's probably best to have them sit with you while you set this up. They can answer questions about what IP addresses, sites and domains need to be included.

If you are sharing this same certificate with other non-Rock IIS sites, you can setup their bindings here as well and they will be updated to use the new certificate.

For your first few runs, you may want to leave the Remove Old Certificate checkbox turned off. This way if something goes wrong you have some old certificates to go back to. This will only remove the previous Acme Certificate, it will not remove any SSL certificate you may have been using before this plugin.

Once you click Save you will get an overview of your certificate configuration.

Certificate Sample

After the certificate is configured, you may see a few warning messages about your IIS configuration. The plug-in will use the information you have provided to determine if there are likely to be problems when trying to renew your certificate. If you are trying to provide a certificate to a non-Rock website then it will check if you have the Http Redirect module installed. If you do not it will warn you and offer to try to install the module for you. If Rock does not have enough permissions to install the module or if you simply wish to do it yourself, you may need to install it before renewing a certificate.

Redirect Warning

The next warning you might see after enabling the Http Redirect module is a notice that the other site(s) need to be configured to redirect the certificate authorization requests to the Rock site. Again, if any site is not properly configured it will offer to fix it for you. This automatic configuration creates a small web.config at the .well-known/acme-challenge in the other sites which redirects requests to your Rock site. Because this other-site configuration is so simple, it can easily be undone by you later by simply deleting the .well-known folder from those sites.

Site Warning

Now that your certificate is configured and any possible warnings have been resolved you can click the Renew button to request the certificate be validated and installed. This may take a while so be patient. For each domain name you have listed it can take anywhere between 3-10 seconds to validate the domain name. Once it is finished it will, hopefully, give you a success message. At this point your SSL certificate has been installed and IIS has been configured to use it.

You will notice a box to enter something called a CSR when renewing / requesting your certificate. Normally you will want to leave this blank. If you are operating in a partial-trust environment, you will usually initiate the certificate request with your hosting provider. They will then give you a CSR (Certificate Signing Request) to be signed by a CA. This CSR would be pasted in here before clicking the Request Certificate button. The final certificate would then be copied and pasted back to your hosting provider.

In the event you get an error, there are usually two types. The first is a domain validation error. It will tell you that it had trouble validating a domain name. Verify that the domain name is correct and actually points to your server then try again. The second error that you may run into is a permission error. This will happen if you are not running on a Full-Trust system. In that case you will either have to fix the permissions or use Offline Mode (more on that later).

Offline Mode

This is a work in progress but seems to work in testing. Sometimes your Rock install does not have enough permissions to automatically install certificates or configure IIS. Sometimes you just don't trust full automation and want to do it yourself. Offline Mode performs all the domain verification steps and renews the certificate but does not install it. Instead the certificate is presented to you for download and manually install. The hope is that this method will also allow the plug-in to function in partial-trust hosting situations where you can download the certificate and upload it to your hosting provider.

Automatic Renewals

A new job is installed with this plugin that handles automatic renewals of certificates when they come close to expiring. By default the job is configured to begin renewing certificates 30 days before they expire. This gives a good margin of error for the job to retry the renewal process and for you to intervene if needed.

Because of the high priority nature of a working certificate on your Rock installation it is highly recommended that you enable the notification e-mails.