Automatic Certificate Renewal with ACME

This quick and easy tutorial guides you through the steps necessary to get automatic certificate renewal up and running in Membrane API Gateway.

Setup

Before we run Membrane, we first need to set up our environment.
Make sure you have downloaded the latest release .zip of the Membrane API Gateway.
To run Membrane you will require a JDK of at least version 17.
After the download has finished, extract the archive and locate the file conf/proxies.xml

Configuring Membrane

Setting up ACME is straight forward, for this tutorial we will configure an ACME HTTP-01 challenge.
Membrane currently supports HTTP-01 and DNS-01 challenges. (TLS-ALPN-01 will arrive in a future release.)

See the following resources for more information on this topic:

Setting Up SSL/ACME

Open the Membrane configuration file, proxies.xml, and set up an SSL/ACME component:

...>

<ssl id="demoSSL">
  <acme
    experimental="true" 
    directoryUrl="https://acme-v02.api.letsencrypt.org/directory"
    contacts="mailto:<email-of-webadmin>"
    termsOfServiceAgreed="true"
  >
    <!-- The ACME implementation is still in active development so the 'experimental' flag is necessary. The URL points to the ACME endpoint of the certificate authority. 'contacts' should be your email and you agree to Let's Encrypts terms and condition by starting this software. -->
    <fileStorage dir="<path-to-store-certificates>" /> <!-- Alternative ways of storing the certificates can be found in the Element Reference -->
  </acme>
</ssl>

<router>
...

Next, add a simple insecure endpoint responding to ACME challenge requests:

...
<router>

<api port="80">
  <acmeHttpChallenge />
  <javascript>
    exc.setResponse(Response.ok().build());
    RETURN
  </javascript<
</api>

</router>

Securing Endpoints

To secure an endpoint with your freshly set up SSL, simply add a reference to the SSL element using its ID:

...
</api>

<api host="example.com" port="443"> <!-- Important! Always specify a host so the CN field of the certificate can be properly determined. -->
  <spring:ref bean="demoSSL" />
  <target host="<server-address>" port="<server-port>">
</api>

</router>