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.

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

Minimum configuration

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 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 >

Renew expiring certificates

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 0.

Use an ACME test server

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.

Supported Java versions

  • JavaSE-1.8

  • JavaSE-11.0

  • JavaSE-15.0

Developing a feature that depends on this feature

If you are developing a feature that depends on this feature, include the following item in the Subsystem-Content header in your feature manifest file.

com.ibm.websphere.appserver.acmeCA-2.0; type="osgi.subsystem.feature"