How-To: Setup EZCA ACME Agent

In this page we go through how to download the EZCA ACME agent and set it up to accept internal ACME requests. This will allow you to issue ACME certificates in your private Certificate Authority.

Introduction - Setup Internal ACME Agent To Issue Certificates To Your Local Network

For EZCA to validate the local domain ownership, we have to install a local agent in your network. This web service will receive all ACME requests and validate the domain ownership on behalf of EZCA. In this step we will set up the agent.

Diagram showing how the EZCA ACME Agent interacts with the EZCA Certificate Authority and internal applications

In this step, we will set up the ACME agent in your local network, allowing it to communicate with EZCA and issue certificates from your CA. We will go through how to set up the server, how to create the authentication certificate, and how to configure the agent to communicate with EZCA.

Prerequisites - What You Need Before Setting Up Your ACME Agent

Before setting up your internal ACME agent, make sure you have completed the following prerequisites:

  1. You have registered your ACME agent in EZCA
  2. You have a Windows Server available to host the ACME agent within your local network (can be a VM in Azure or on-premises)

How To Set Up Your ACME Agent - Video Walkthrough

Follow along with this video walkthrough to set up your internal ACME agent:

How To Set Up a Local EZCA ACME Agent - Step-by-Step Guide

The EZCA ACME Agent is a web service that runs on Internet Information Services (IIS). To set up the agent, you first need to install IIS on your Windows Server, then you will install the ACME agent web application, and finally configure it to communicate with EZCA.

How to Install Internet Information Services (IIS) on Windows Server

The EZCA ACME Agent is a web service that runs on Internet Information Services (IIS). To set up the agent, you first need to install IIS on your Windows Server. You can do this through the Server Manager or by using PowerShell.

In your Windows Server open an Administrator PowerShell window and run the following command:

Install-WindowsFeature -name Web-Server -IncludeManagementTools

How to Install IIS Web Deploy

Once IIS is installed, you will install web-deploy from the official Microsoft site and open the installer. Web Deploy is a Microsoft tool that simplifies the deployment of web applications and services to IIS. It allows us to easily deploy the ACME agent web application to our IIS server.

  1. Download Web Deploy from the official Microsoft site and open the installer.

  2. Once the installer is open, click Next on the first page.

  3. Read and accept the Terms and Conditions.

  4. For Choose Setup Type, select Complete to install all features of Web Deploy, which are required for the ACME agent to function properly.

    Web Deploy Installation Setup Type page with Complete option highlighted

  5. Click Install to begin the installation process.

How to Install .NET Hosting Bundle

The EZCA ACME Agent is built on .NET, so you need to install the .NET Hosting Bundle on your server to run the agent. The hosting bundle includes the .NET runtime and the ASP.NET Core module for IIS, which allows IIS to host .NET applications.

  1. Download the latest .NET hosting bundle from Microsoft.
  2. Click Install.

How To Setup the ACME Agent Certificate

The EZCA ACME Agent requires a certificate to authenticate to EZCA and issue certificates on behalf of your CA.

If you previously enabled health checks when registering your agent in EZCA, this certificate will be automatically rotated by the health API, meaning once it is setup, you will not have to manually renew it. If you did not enable automatic health checks, you will have to manually call the health API (https://YOURACMEAgent/api/Health/Overall) periodically to check the health of your agent and renew the certificate before it expires. If you do not periodically check this endpoint your agent’s certificate may expire without your knowledge, causing all ACME requests to fail.

To create a new certificate for the ACME agent in EZCA, follow these steps:

  1. In the EZCA portal, navigate to Domains.

    EZCA Cloud PKI My Domains page showing list of registered domains with Request Certificate button for each domain

  2. When you registered your ACME agent, you had to provide a domain name for it. Find that domain in the list and click on the Request Certificate button for that domain.

    EZCA Cloud PKI My Domains page with Request Certificate button highlighted for a specific domain

  3. The Subject Name and DNS Names will be pre-populated with the domain name you provided when registering your agent in EZCA.

    EZCA Cloud PKI Request New Certificate form with Subject Name and DNS Names fields pre-populated with the domain name provided during ACME agent registration

  4. If this certificate requires more subject alternate names (for other domains that might use this certificate), add them in the DNS Names section.

  5. By default, EZCA will request the certificate to be the maximum Validity Period allowed by your CA and PKI Admins. If you want to decrease the lifetime of the certificate, optionally adjust the validity slider.

  6. Under Certificate Location, select Import CSR.

    EZCA Cloud PKI Request New Certificate form with Certificate Location set to Import CSR

  7. Click How to create a CSR Locally:

    EZCA Cloud PKI Request New Certificate form with How to create a CSR Locally button highlighted

  8. Select Windows.

    EZCA Cloud PKI Create CSR Request dialog with Windows option selected to show instructions for creating a CSR using certreq.exe

  9. Click Download to download the .inf file for the CSR request.

    EZCA Cloud PKI Create CSR Request dialog with Download button highlighted to download the .inf file for creating the CSR using certreq.exe

  10. Edit the following values in the .inf file you just downloaded:

    Exportable = FALSE
MachineKeySet = TRUE

  11. Open cmd.exe as an Administrator.

  12. Navigate to your downloads folder and run the following command where <INFFILENAME> is the file name you just downloaded:

    certreq.exe -new <INFFILENAME>.inf acme.csr

  13. Go back to the EZCA portal and close out the instructions dialog.

  14. Click on the Upload CSR button.

    EZCA Cloud PKI Request New Certificate form with Upload CSR button highlighted to upload the CSR created using certreq.exe

  15. Select your newly created CSR file, acme.csr:

    Windows file explorer showing acmeCertificateSigningRequest.csr file selected for upload in EZCA Cloud PKI Request New Certificate form

  16. Click the Request Certificate button at the top right of the form.

    EZCA Cloud PKI Request New Certificate form with Request Certificate button highlighted to submit the certificate request after uploading the CSR

  17. Your ACME Agent certificate has been created successfully. Click Download Certificate to download the certificate file.

    EZCA Cloud PKI Certificate Created Successfully page showing Download Certificate button highlighted to download the newly created ACME Agent certificate

  18. Open the downloaded certificate on your Windows Server where you’ll run your ACME agent.

  19. Click Install Certificate to start the Certificate Import Wizard.

    Windows Certificate dialog showing certificate details with Install Certificate button highlighted

  20. Select Local Machine.

    Certificate Import Wizard dialog with Local Machine option selected to specify the certificate store location for the ACME Agent certificate

  21. Click Next and complete the wizard to install the certificate in the Local Machine certificate store.

How To Create the ACME CA Agent Site and Deploy the Web Application

Now that the ACME Agent certificate is installed to your Windows Server local machine certificate store, you will create an IIS site for the ACME agent and bind it to this certificate. You will also deploy the ACME agent web application to this site and configure it to communicate with EZCA.

  1. Download the signed IIS setup script.

  2. Open a PowerShell terminal as an administrator on the Windows Server where you want to host your ACME agent.

  3. Run the following command to execute the script and set up your IIS site and deploy the ACME agent web application. Make sure to replace the parameters with the appropriate values for your environment.

    • certificateSubject: The subject name of the SSL Certificate for your IIS site. (acmeagent.yourdomain.com). This certificate must be different than the authentication certificate you created in the previous step. If your site is going to be public facing, this certificate needs to be issued by a public CA. If your site is internal, this certificate can be issued by your private CA.
    • acmeCertificateSubject: The subject name of the SSL Certificate we created in the previous step to authenticate with EZCA. (acmeboston). This is the certificate that will be used by the ACME agent to authenticate to EZCA and request certificates on behalf of your CA.
    • appInsights: The connection string for the Application Insights where you want this agent to report the telemetry. If you don’t want to use Application Insights, you can leave this parameter empty and the agent will run without telemetry.
    • agentURL: The URL where computers on your network can find this agent.
    $certificateSubject = "acmeagent.yourdomain.com"
$acmeCertificateSubject = "acmeboston"
$appInsights = "YourAppInsightsConnectionString"
$agentURL = "https://acmeagent.yourdomain.com"

.\InstallIISSite.ps1  -certificateSubject $certificateSubject -acmeCertificateSubject $acmeCertificateSubject -appInsights $appInsights -agentURL $agentURL

  4. Verify the site is up by going to https://YourSite/api/Health/Overall. You should see a JSON response with the overall health status of the agent.

    Browser showing ACME Agent Health API response with overall status healthy

  5. Done! Now that the agent is up and running you are ready to start requesting ACME certificates.

Next Steps - Request ACME Certificates from Your CA Using the Agent

Now that you have your ACME agent set up and running, the next step is to start requesting ACME certificates from your CA using the agent. You can do this from any computer in your network by using an ACME client such as Win-ACME. Learn how to do this in the next page.

🚀 Request ACME Certificates Using Your Agent

Troubleshooting ACME Agent Setup

Below you will find common exceptions or errors when setting up the EZCA ACME agent and how to fix them.

Domain Validation Failure

ACME validation is carried out through DNS, ensure that the ACME Server has http access into the server requesting the certificate.

Exception ‘Keyset does not exist’

If when creating a new ACME account the request fails with an internal server error and when looking at the Application Insights you see a Cryptographic Exception “Keyset does not exist” this means that the identity running the application pool in IIS does not have permission to read the certificate’s private key. Please ensure that the Application’s pool identity has the correct permissions.

Certificate Not Being Available When Calling The Test API

If when calling the test API you get an error that the certificate is not available, and you have verified that it is in the right store and that the application running the pool in IIS (by default IIS_IUSRS) has permission to the certificate, make sure that the certificate chain (including the root certificate) is in the trusted root store.