README.md

HM ACM WordPress plugin for user-land AWS ACM and CloudFront HTTPS
A Human Made project. Maintained by @joehoyle.

When to use HM ACM

If you have a WordPress multisite that allows users to add their own domain names, and you want to support HTTPS on all custom domains.

Because CloudFront only supports a single HTTPS certificate, it's inpractical (and mostly impossible) to update to a new SSL certification that includes a new custom domain every time a user on the network configures their site's domain.

How HM ACM works

The basic idea is to generate a new ACM certificate for every domain configured on the multisite, and then use that SSL certificate on a new CloudFront distribituion, specific to each site with a custom domain.

This plugin handles the API calls and steps to AWS to generate the ACM SSL certificate and create the CloudFront Distribution. The plugin has admin UI to step the user through this process.

The CloudFront Distribution Config is hard coded in this plugin, and reflects the CloudFront Distribution in use under Human Made's typical config. This should ideally be updated to be synchonrised with any updates made to the "base" network CloudFront Distribution Config.

Configuration

HM ACM needs access to the AWS APIs for CloudFront and ACM. To pass the API credentials, you must define the HM_ACM_AWS_KEY and HM_ACM_AWS_SECRET constants. You also have to define HM_ACM_UPSTREAM_DOMAIN (upstream CloudFront domain name) to set correct origin for new domain.

Also the constants need to be defined for HM_ACM_UPSTREAM_CLOUDFRONT_FUNCTION_ARN which must be a CloudFront function ARN. This is used to forward the Host header to the upstream CloudFront distribution.

HM_ACM_CLOUDFRONT_CACHE_POLICY_ID must be defined as the ID of the CloudFront cache policy to use for the distribution.

HM_ACM_CLOUDFRONT_ORIGIN_REQUEST_POLICY_ID must be defined as the ID of the CloudFront origin request policy to use for the distribution.

The AWS Access Key should have the following policy:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "VisualEditor0",
            "Effect": "Allow",
            "Action": [
                "cloudfront:GetDistribution",
                "acm:DescribeCertificate",
                "acm:RequestCertificate",
                "cloudfront:CreateDistribution",
                "cloudfront:UpdateDistribution"
            ],
            "Resource": "*"
        }
    ]
}

Limitations

Because this plugin doesn't provide DNS / Nameserver services (via Route 53) it is not possible to use a root domain with the CloudFront distribution. This is because AWS does not provide IP addresses for the CDN, so we don't have anything to provide users with to add an A record to their DNS.

The path forward here is probably to incorperate Route 53 in to this plugin, so instead of providing users with DNS records, we give them nameservers to switch to. This adds the complication of needing to add UI for general DNS management, as users will likely need to now manage things like MX records.

User guide

To do the following you current have to activate the "HM ACM HTTP" plugin on the site.

Step 1: Request HTTPS Certificate

Step 2: Once certificate is requested, I must verify the domain by adding DNS records:

After 5 minutes, I click "Refresh" in the plugin admin page, the certificate is now ISSUED, on to the next step:

Step 3: Click Create CDN Configuration

Step 4: Update DNS records for the domain

Now the CDN is configured, I have new DNS settings for the www.exmaple.com domain. I update the www.example.com (leaving example.no unchanged, as the domain provider is already doing a redirect to www in this case).

Now the site is configured with a valid HTTPS certificate. In the case of this site, I had to then do a search-replace as there was lots of http:// urls stored in the content:

wp --url=https://www.example.com/ search-replace http://examplenetwork.com/uploads/ https://unitedbloggers.noexamplenetwork.com/uploads/

You should now see https://www.example.com/ functional with HTTPS.

CLI

The plugin includes a CLI command hm-acm which allows for executing some actions via CLI for a specific site, list of sites or network wide. The currently supported actions are:

• create-cert which will create an ACM certificate given a comma separated list of domains. If no domains are supplied via the command then they'll be attempted to be retrieved via the suggested domains function allows for filtering the domains via other plugins.
• verify-cert which will refresh the details of an ACM certificate in WordPress. Helps check if the records to validate the cert have been added.
• delete-cert which will unlink an ACM certificate in WordPress from a site.
• create-cloudfront which will create a CloudFront distribution provided the site has a verified certificate.

Example usage:

wp hm-acm {action} {associative args}