Table of contents of the article:
The NGINX development team has announced the availability of a preview release of ACME support in NGINX. This release introduces the new ngx_http_acme_module module , designed to provide built-in directives that allow you to request, install, and renew certificates directly within the NGINX configuration, without the need for external procedures. ACME support is based on the NGINX-Rust SDK and is distributed as a dynamic module written in Rust, made available to both NGINX Open Source users and NGINX Plus enterprise customers through the NGINX One platform.
The native integration of the ACME protocol into NGINX represents a significant step in simplifying SSL/TLS certificate management. The ability to directly configure the issuance and renewal process using NGINX directives significantly reduces the risk of manual errors while also improving operational efficiency. This approach eliminates much of the complexity and overhead typically associated with digital certificate management and reduces reliance on external tools like Certbot. The result is a more secure, streamlined, and centralized workflow with a smaller attack surface and more transparent management.
Another advantage over external tools is the lack of platform constraints. The native implementation in NGINX ensures superior portability and independence, making it suitable for a wide range of contexts, from established corporate web infrastructures to rapidly evolving cloud environments. This makes the new module a versatile and reliable solution, capable of meeting the scalability, security, and automation needs that characterize modern application architectures.
What is ACME?
The ACME (Automated Certificate Management Environment) protocol is a communication system designed to automate operations related to digital security certificates, particularly SSL/TLS. ACME allows for the management of a certificate's entire lifecycle: from initial issuance to validation, renewal, and eventual revocation. This allows clients to interact with a Certification Authority (CA) without the need for manual intervention, reducing time, costs, and complexity. The availability of a standardized protocol has made it much easier to adopt HTTPS as a basic requirement for websites, applications, and online services that require encrypted and secure communications.
The development of the ACME protocol was initiated by the Internet Security Research Group (ISRG) as part of the Let's Encrypt project , launched in late 2015. The initiative had a revolutionary impact: for the first time, free and easily obtainable SSL/TLS certificates were offered, at a time when certificate acquisition was often a manual, costly, and error-prone process. The automation introduced by ACME radically changed the paradigm, transforming the adoption of the HTTPS protocol from an advanced option to the de facto standard for the modern web.
Over time, the protocol was further improved with the ACMEv2 specification , which introduced new features and expanded its use cases. Major updates include support for new challenge types for identity verification, more flexible authentication methods, the introduction of wildcard certificates (useful for protecting entire domains and subdomains with a single certificate), and increased overall security robustness. Thanks to these developments, ACME is now considered a cornerstone of automated digital certificate management and an essential tool for ensuring the widespread availability of encrypted and secure connections globally.
How does the ACME protocol work?
There are actually two explanations for this question. A high-level one that covers just the basics, and a more in-depth one that covers the technical side. We'll try to keep things high-level.
Once the ACME agent is installed and properly configured, the process is actually quite simple. We'll discuss configuration shortly, but for now, keep in mind that during the verification process that occurs when the agent is installed, a key pair will be generated for use by the agent and the CA. These keys are sometimes called "authorization keys."
Issue/Renewal
To obtain a digital certificate, the agent must generate a Certificate Signing Request (CSR) for the desired domain and submit it to the Certification Authority (CA). The entire process is conducted securely via HTTPS , ensuring the integrity and confidentiality of the information.
-
The agent generates a CSR for the domain
The first phase consists in the creation of the Certificate Signing Request, which includes domain identification data (e.g.example.com) and the public key that will be associated with the certificate. This document is the starting point of the validation process. -
The agent signs the public key generated along with the CSR with the corresponding private key
To ensure that the public key is truly bound to the domain and has not been tampered with, the agent uses its private key to sign the CSR. This establishes a secure cryptographic link between the public/private key pair. -
The agent signs the entire CSR with its private authorization key
In addition to the signature associated with the domain key pair, the agent also applies the authorization private key, generated during the initial configuration of the ACME protocol. This second signature serves to prove to the CA that the request comes from a legitimate client authorized to request certificates. -
The CA verifies both signatures and issues the certificate
The Certification Authority checks the validity of the signatures, the accuracy of the CSR, and the association with the domain. Once these checks are successfully completed, it issues the SSL/TLS digital certificate. -
The agent receives the certificate and installs it on the relevant domain
Once issued, the certificate is sent to the agent, who installs it in the server's configuration. From then on, the domain is accessible via secure HTTPS connections, with the certificate valid and recognized by browsers and clients.
You'll notice that the agent we're talking about isn't a little guy residing on your server, as the icons I've chosen might suggest. So, there's no need to point that out. It's just more fun to imagine him that way.
In any case, this process works more or less the same way with renewals. The agent can be configured to ping the CA at regular intervals to rotate keys or replace entire certificates. And all of this happens behind the scenes, without any human intervention.
withdrawal
As with issuing, revoking an SSL/TLS certificate requires the agent's intervention, which must generate and sign an official request. In this case, however, the request is not for obtaining a new certificate, but for invalidating an existing one. The Certification Authority (CA) then revokes the certificate and updates the public registers that allow browsers and clients to check the certificate's status.
-
The agent generates a revocation request for the SSL/TLS certificate
The agent creates a document that identifies the certificate to be revoked, including the serial number and the information needed to uniquely link it to the original issuance. -
The agent signs the request with its private key
To ensure that the request actually comes from the certificate holder, the agent uses its private key to digitally sign it. This proves to the CA that the revocation was not requested by an unauthorized third party. -
The CA verifies the signature to ensure that the request is authorized.
The Certification Authority checks the validity of the signature and its correspondence with the public key associated with the certificate. If the verification is successful, the CA recognizes the request as legitimate. -
The CA revokes the certificate
Once the authenticity of the request is confirmed, the certificate is officially revoked, making it no longer valid for establishing secure connections. -
Certificate revocation status is published to CRLs and OCSP responders
Finally, the CA updates the Certificate Revocation List (CRL) and the responders Online Certificate Status Protocol (OCSP)These systems allow browsers and clients to check the validity status of the certificate in real time, ensuring that any compromised certificates can no longer be used for reliable HTTPS connections.
ACME Workflow in NGINX
The ACME workflow within NGINX can be described as a sequence of four main phases, which allow for the automated management of the entire digital certificate lifecycle:
-
Setting up the ACME server
At this stage, NGINX is configured to communicate with a Certificate Authority that supports the ACME protocol. This establishes the point of contact from which to request, validate, and obtain SSL/TLS certificates. -
Shared memory allocation
To ensure efficiency and stability, the NGINX ACME module uses shared memory areas to manage request information and validation status. This architecture allows for reliable coordination between the various server processes. -
Setting up challenges
NGINX is instructed to handle validation challenges required by the CA, such as HTTP-01 or DNS-01. This step is essential for proving domain ownership and authorizing certificate issuance. -
Issuance and renewal of certificates
Once validation is complete, the certificate is automatically issued and installed. The ACME module also handles periodic renewal, eliminating the need for manual intervention and reducing the risk of service interruptions due to expired certificates.
Setting up the ACME server
To enable ACME features in NGINX, the first step—and the only required one—is to specify the ACME server directory URL. This parameter tells the module which Certificate Authority to contact for issuing, validating, and renewing SSL/TLS certificates.
Beyond this minimum requirement, you can define additional information useful for the module's proper functioning. For example, you can specify contact information to be used in the event the Certification Authority needs to report issues related to issued certificates. You can also configure the path to store module data, such as status information or the keys required for the validation process. These additional options, while not mandatory, help make management more reliable and ensure better operational control.
acme_issuer letsencrypt { uri https://acme-v02.api.letsencrypt.org/directory; # contact admin@example.test; state_path /var/cache/nginx/acme-letsencrypt; accept_terms_of_service; }
Shared memory allocation
The implementation of ACME support in NGINX also introduces the optional acme_shared_zone directive , designed to manage certificates, private keys, and challenge data from all configured issuers in a common area. This shared memory zone allows different server processes to access the same information consistently, avoiding redundancies and simplifying internal coordination.
By default, the zone size is 256 KB , which is sufficient for simple scenarios. However, for more complex environments or with a large number of certificates to manage, this size can be increased as needed. The ability to adjust the dedicated memory makes the approach more flexible, ensuring that NGINX can adapt to both lightweight installations and more demanding enterprise environments.
acme_shared_zone zone=acme_shared:1M;
Setting up challenges
In the preview release, the ACME implementation in NGINX currently supports HTTP-01 challenges , used to verify the client's ownership of the domain. To properly handle this mechanism, you must define a listener on port 80 in the NGINX configuration that can receive and respond to validation requests sent by the Certificate Authority. This configuration ensures that the server can automatically and transparently demonstrate domain ownership, a prerequisite for issuing an SSL/TLS certificate.
server { # Listener on port 80 is required to process ACME HTTP-01 challenges listen 80; location / { # Serves as a basic 404 response while listening for challenges return 404; } }
The development team also plans to extend support for other challenge types, including TLS-ALPN-01 and DNS-01 , which will be introduced in upcoming releases. These additional methods will expand validation capabilities, offering greater flexibility in complex scenarios such as load balancers, multi-server environments, or where direct access to port 80 is not practical.
Issuance and renewal of certificates
To automate the issuance and renewal of TLS certificates in NGINX, you can use the acme_certificate directive within the relevant server block . This directive requires a list of identifiers (domains) for which certificates should be dynamically generated. This list is typically defined using the server_name directive , which specifies the domain names associated with the server block.
A typical example is the configuration of a server block for the domain example.domain, using the previously defined ACME issuer (for example, Let's Encrypt's). In this scenario, the module automatically takes care of requesting and installing the SSL/TLS certificate, as well as managing its periodic renewals, without the need for manual intervention.
server { listen 443 ssl; server_name .example.com; acme_certificate letsencrypt; ssl_certificate $acme_certificate; ssl_certificate_key $acme_certificate_key; ssl_certificate_cache max=2; }
It is important to underline that not all values accepted by the directive server_name are considered valid identifiers. The preview version does not support wildcard (Eg *.example.domain) nor the use of regular expressionsThese limits will be progressively revised in future implementations to broaden compatibility with more complex scenarios.
Once the certificate is obtained, its information can be managed using the $acme_certificate and $acme_certificate_key variables , which provide the module with the data needed to enable SSL/TLS encryption on the associated domain. This integration simplifies the operational flow and ensures consistent certificate management directly within the NGINX configuration.
Why all this is important
The global adoption of HTTPS was significantly accelerated by the introduction of the ACME protocol , which made web security a basic requirement, not an option. By automating the entire SSL/TLS certificate lifecycle—from issuance to renewal to day-to-day management—ACME eliminated much of the operational complexity and costs associated with manual processes, making securing online communications simpler and more accessible.
ACME's role is not limited to the traditional web. With the exponential growth of IoT devices, API services, and edge computing infrastructure , the protocol is also emerging as a fundamental element in automating security in distributed and highly scalable environments. In such scenarios, the ability to provide reliable and always up-to-date certificates is a crucial requirement to ensure system integrity, privacy, and resilience.
NGINX's native support for ACME confirms the protocol's strategic importance for the future of security, automation, and scalability. ACME will likely remain the cornerstone of certificate automation for a long time to come, extending its impact far beyond the web. Since security is now an integral part of network standards, it's natural to expect continued evolution in both application deployment models and security requirements, driving further improvements and enhancements to the protocol itself.
Looking to the future, the NGINX development team has expressed its commitment to progressively growing its implementation to align not only with current user and customer needs, but also with emerging ones. The goal is to provide features that are ready to address new scenarios, with an approach that balances reliability, security, and innovation.
How to get started
You can already experience native ACME support in NGINX.
-
For open source users , downloadable pre-compiled packages are available.
-
For NGINX Plus enterprise customers , through the NGINX One platform , the module is provided as a dynamic component supported by F5.
More information about configuring and using the module can be found in the official NGINX documentation.
