Automatic certificate management with ACME

The Automatic Certificate Management Environment (ACME) protocol automates the process of transport layer security (TLS) certificate issuance and verification. You can use the Open Liberty Automatic Certificate Management Environment (ACME) Support feature to automatically get a browser-trusted TLS certificate for domains on your server from an ACME certificate authority (CA).

Clients use TLS certificates to authenticate domain names on a server. These TLS certificates verify that the server legitimately controls a domain and protect clients from man-in-the-middle attacks. The TLS certificate is a record that server control over a domain is tested and verified by a CA. To get a TLS certificate, the server must generate a certificate signing request (CSR) and respond to several challenges from the CA. These challenges prove the server controls the domain that is being verified.

In the past, TLS certificate issuance required significant human involvement. The ACME protocol standardizes the process so that it can be carried out between an automatic certificate management agent on the server and an ACME CA, such as Let’s Encrypt ™.

ACME and Open Liberty

To use an ACME CA with your Open Liberty server, you must enable and configure the ACME Support feature (acmeCA-2.0). At a minimum, you must provide the URL of an ACME CA and the name of one or more domains that your server controls. To receive a callback from a public ACME provider, port 80 must be open to comply with the standards for the HTTP-01 challenge type. For many internal or test ACME providers, you can use any open port to complete the ACME challenge. For more information about using an ACME test server, see Use an ACME test server.

When an Open Liberty server starts with TLS enabled, a self-signed TLS certificate is created for the server. This certificate can be used for testing and development purposes. However, since the certificate isn’t signed by a CA, clients that connect to the server over TLS don’t trust it. Browsers then require clients to confirm whether they trust the server, which can cause problems for containerized environments and microservices, even during testing and development.

To avoid problems with self-signed certificates, services such as Let’s Encrypt use the ACME protocol to provide free CA-signed TLS certificates over the public internet. When the ACME Support feature is enabled, the Open Liberty server automatically requests a certificate from your configured CA provider at startup if a new certificate is needed. The feature can also respond to challenges from the CA and manage certificate renewals and revocations.

You can view, renew, or revoke TLS certificates and get details about the active ACME CA account by making HTTPS calls to the REST API. Depending on the action you want to take, you must be in either the administrator or reader role to use the REST API. For more information about configuring Open Liberty administrator and reader roles, see the Application security feature.

ACME CA account management

The ACME Support feature requires a valid account with an ACME CA. Account details are stored in an account key file. Before a CSR is sent, the feature first checks for an existing account key file. If no account key file exists, the feature generates a new one. This file is then used to either register a new account or log in to an existing account. Like any security credential, the account key file must be backed up and protected.

You can request a new account key at any time by using the REST API. Renewing an account key might be necessary if your existing key is compromised, or as a periodic security precaution. To renew the account key, a user that is in the administrator role can send the following HTTPS request:

curl -kv https://mydomain.com:443/ibm/api/acmeca/account -X post -H "content-type: application/json" -d '{"operation":"renewAccountKeyPair"}'

Some certificate authorities provide terms of service. If an ACME CA modifies its terms of service, you might be required to agree to the new terms manually. If you fail to agree to the modified terms of service, the ACME CA server might refuse any future requests from your account until you confirm your agreement. To avoid service interruption, provide an account contact in your ACME configuration that specifies a monitored email address. For more information, see the ACME Support feature.

Certificate renewal and revocation

The ACME Support feature automatically renews any expiring or revoked TLS certificates by default. The renewBeforeExpiration property specifies the amount of time before a certificate expires that the server requests a new certificate. The default value for this property is seven days.

When the server starts, it checks the expiration date on the CA-signed TLS certificate. If the expiration date is within the specified range of time, or if the certificate is already expired or revoked, the server automatically requests a new TLS certificate. While the server is running, it checks the TLS certificate daily and automatically renews any expiring or revoked certificate. If a renew request fails, the background process continues to request a new TLS certificate hourly until the request is successful. For more information, see the ACME Support feature.

Runtime changes to the acmeCA configuration can trigger an automatic certificate renewal request. For example, if the directory URI is changed to a different endpoint, the server requests a new TLS certificate.

You can also choose to manually renew the active TLS certificate. To renew the active certificate, a user that is in the administrator role can send the following HTTPS request:

curl -kv https://mydomain.com:443/ibm/api/acmeca/certificate -X POST -u admin:password -H "content-type: application/json" -d '{"operation":"renewCertificate"}'

The TLS certificate that is replaced is revoked automatically after the new TLS certificate is installed. When a TLS certificate is renewed, new connections use the new TLS certificate. Existing connections are not interrupted.

To revoke a TLS certificate before you retire a server, during testing, or before you move from one ACME CA to another, a user that is in the administrator role can send the following HTTPS request:

curl -kv https://mydomain.com:443/ibm/api/acmeca/certificate -X POST -u admin:password -H "content-type: application/json" -d '{"operation":"revokeCertificate","reason":"key_compromise"}'

You can specify a revocation reason by using the reason key-value pair. The following reason values are valid:

  • unspecified

  • key_compromise

  • ca_compromise

  • affiliation_changed

  • superseded

  • cessation_of_operations

  • certificate_hold

  • remove_from_crl

  • privilege_withdrawn

  • aa_compromise

If you don’t specify a reason value, the default value is unspecified.

ACME CA account and certificate monitoring with the REST API

You can monitor the active ACME CA account and any active TLS certificates by sending HTTPS requests to the REST API. You can check your account details and contact information or view the current CA-signed TLS certificate details, such as the validity dates for the certificate and the issuer. If you request a certificate renewal, you can see the updated TLS certificate information. However, the content that is returned from these HTTPS endpoints is for informational purposes only and cannot be used or depended on programmatically.

To view both the active ACME CA account and TLS certificate, a user that is in either the administrator or reader role can send the following HTTPS request:

curl -kv https://mydomain.com:443/ibm/api/acmeca -X GET -u admin:password

To view only the active account, a user that is in either the administrator or reader role can send the following HTTPS request:

curl -kv https://mydomain.com:443/ibm/api/acmeca/account -X GET -u admin:password

To view only the active TLS certificate, a user that is in either the administrator or reader role can send the following HTTPS request:

curl -kv https://mydomain.com:443/ibm/api/acmeca/certificate -X GET -u admin:password

You can also access the REST endpoint by using a browser and providing administrator or reader role credentials, as shown in the following examples:

https://mydomain.com:443/ibm/api/acmeca
https://mydomain.com:443/ibm/api/acmeca/account
https://mydomain.com:443/ibm/api/acmeca/certificate

See Also

Troubleshooting ACME certificates