Automatic Certificate Management Environment (ACME) Support 2.0
This feature automates interactions with a certificate authority (CA) by using the Automated Certificate Management Environment (ACME) protocol.
To enable the Automatic Certificate Management Environment (ACME) Support 2.0 feature, add the following element declaration into your
server.xml file, inside the
The minimum configuration for the ACME Support feature requires the URL of a certificate authority (CA) provider and the name of one or more domains, as shown in the following example:
<acmeCA directoryURI="https://acme-v02.api.letsencrypt.org/directory" > <domain>theDomainThatIOwn.com</domain> </acmeCA> <httpEndpoint host="*" httpPort="80" httpsPort="443" id="defaultHttpEndpoint"/> <keyStore password="password_for_keystore" id="defaultKeyStore"/>
In this example, Let’s Encrypt is the ACME CA provider. To receive a callback from a public ACME CA provider, port 80 must be open to comply with the standards for the HTTP-01 challenge type.
You can provide an account contact as part of your ACME Support feature configuration. If a CA modifies its terms of service, it might require you to agree to the new terms of service manually. If you specify a monitored email address in your feature configuration, the ACME CA server can warn you about new terms of service so that you can avoid service disruption. Whenever you update your contact information in the feature configuration, the ACME service updates your account on the ACME CA server.
To provide an account contact, specify a monitored email address in the
accountContact element, as shown in the following example:
<acmeCA> ... <accountContact>mailto:[email protected]</accountContact> </acmeCA >
You can configure the amount of time before a certificate expires that the ACME Support feature renews the certificate by specifying a value for the
renewBeforeExpiration property. When the certificate enters renew timeframe, a renew request can occur at server startup, after a configuration update, or during default daily certificate checks. In the following example, the feature requests a certificate renewal 24 hours before the expiration date:
<acmeCA> ... <renewBeforeExpiration>24h</renewBeforeExpiration> </acmeCA >
The default value for the
renewBeforeExpiration property is seven days. To disable automatic certificate renewals, set this property to
In development environments, you can test your ACME configuration with a containerized ACME test server like Pebble or Boulder. Some ACME CA providers require an initial public certificate if they are not included in the JRE’s cacerts and you want to use the HTTPS protocol to retrieve the certificate. To configure a custom truststore specifically for the ACME Support feature, use the
acmeTransportConfig configuration element, as shown in the following example:
<acmeCA> ... <acmeTransportConfig trustStore="myServer/resources/security/cacerts.p12" trustStorePassword="password"/> </acmeCA>
The ACME Support feature still trusts all certificates in the JRE cacerts file even if you specify a custom truststore.
When you run containerized or test versions of ACME CA servers, the OCSP responder URL that is defined in the certificate might not be reachable. You can override the OCSP responder URL in the certificate by specifying the 'ocspResponderUrl' attribute in the
acmeRevocationChecker element, as shown in the following example:
<acmeCA> ... <acmeRevocationChecker ocspResponderUrl="127.0.0.1:4567"/> </acmeCA>
If your ACME test server does not support revocation checking, you can disable revocation testing by setting the
enabled attribute on the
acmeRevocationChecker element to
false, as shown in the following example:
<acmeCA> ... <acmeRevocationChecker enabled="false"/> </acmeCA>
For more information, see Automated certificate management with ACME.