Automatic Certificate Management Environment (ACME) Support2.0
This feature automates interactions with a certificate authority (CA) by using the Automated Certificate Management Environment (ACME) protocol.
For more information, see Automated certificate management with ACME.
Enabling this feature
To enable the Automatic Certificate Management Environment (ACME) Support 2.0 feature, add the following element declaration into your server.xml
file, inside the featureManager
element:
<feature>acmeCA-2.0</feature>
Examples
Configure ACME support
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.
Provide an account contact
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 manually agree to the new terms of service. 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 >
Renew expiring certificates within a specified time period
You can specify the renewBeforeExpiration
property to configure the amount of time before a certificate expires that the ACME Support feature renews the certificate. When the certificate enters renew time frame, 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"/>
The default value for the renewBeforeExpiration
property is seven days. To disable automatic certificate renewals, set this property to 0
.
Configure access to an ACME test server
In development environments, you can test your ACME configuration with a containerized ACME test server like Pebble or Boulder. If the test server is not included in the Java runtime environment (JRE) cacerts file, some ACME CA providers require an initial public 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 Java runtime environment (JRE) cacerts file even if you specify a custom truststore for a test server.
When you run containerized or test versions of ACME CA servers, the Online Certificate Status Protocol (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>