ACME - Plugin - v2.8.x

You are browsing documentation for an outdated plugin version.

Looking for the plugin's configuration parameters? You can find them in the ACME configuration reference doc.

The ACME plugin allows Kong Gateway to apply certificates from Let’s Encrypt or any other ACMEv2 service and serve them dynamically. Renewal is handled with a configurable threshold time.

Notes:

The plugin only supports the http-01 challenge, meaning a user needs a public IP and a resolvable DNS. Kong also needs to accept proxy traffic from port 80.

A wildcard or star (*) certificate is not supported. Each domain must have its own certificate.

Workflow

A http-01 challenge workflow between the Kong Gateway and the ACME server is described below:

The client sends a proxy or Admin API request that triggers certificate generation for mydomain.com.
The Kong Gateway sends a request to the ACME server to start the validation process.
The ACME server returns a challenge response detail to the Kong Gateway.
mydomain.com is publicly resolvable to the Kong Gateway that serves the challenge response.
The ACME server checks if the previous challenge has a response at mydomain.com.
The Kong Gateway checks the challenge status and if passed, downloads the certificate from the ACME server.
The Kong Gateway uses the new certificate to serve TLS requests.

Hybrid mode workflow

"shm" storage type is not available in Hybrid Mode.

Due to current the limitations of Hybrid Mode, "kong" storage only supports certificate generation from the Admin API but not the proxy side.

"kong" storage in Hybrid Mode works in following flow:

The client sends an Admin API request that triggers certificate generation for mydomain.com.
The Kong Control Plane requests the ACME server to start the validation process.
The ACME server returns a challenge response detail to the Kong Control Plane.
The Kong Control Plane propagates the challenge response detail to the Kong Data Plane.
mydomain.com is publicly resolvable to the Kong Data Plane that serves the challenge response.
The ACME server checks if the previous challenge has a response at mydomain.com.
The Kong Control Plane checks the challenge status and if passed, downloads the certificate from the ACME server.
The Kong Control Plane propagates the new certificates to the Kong Data Plane.
The Kong Data Plane uses the new certificate to serve TLS requests.

All external storage types work as usual in Hybrid Mode. Note both the Control Plane and Data Planes need to connect to the same external storage cluster. It’s also a good idea to setup replicas to avoid connecting to same node directly for external storage.

External storage in Hybrid Mode works in following flow:

The client send a proxy or Admin API request that triggers certificate generation for mydomain.com.
The Kong Control Plane or Data Plane requests the ACME server to start the validation process.
The ACME server returns a challenge response detail to the Kong Gateway.
The Kong Control Plane or Data Plane stores the challenge response detail in external storage.
mydomain.com is publicly resolvable to the Kong Data Plane that reads and serves the challenge response from external storage.
The ACME server checks if the previous challenge has a response at mydomain.com.
The Kong Control Plane or Data Plane checks the challenge status and if passed, downloads the certificate from the ACME server.
The Kong Control Plane or Data Plane stores the new certificates in external storage.
The Kong Data Plane reads from external storage and uses the new certificate to serve TLS requests.

Running with or without a database

In database mode, the plugin creates an SNI and Certificate entity in Kong to serve the certificate. If SNI or Certificate for the current request is already set in the database, they will be overwritten.

In DB-less mode, the plugin takes over certificate handling. If the SNI or Certificate entity is already defined in Kong, they will be overridden by the response.

EAB support

External account binding (EAB) is supported as long as eab_kid and eab_hmac_key are provided.

The following CA provider’s external account can be registered automatically, without specifying the eab_kid or eab_hmac_key:

ZeroSSL

Storage configuration considerations

config.storage_config is a table for all possible storage types. By default, it is:

    "storage_config": {
      "kong": {},
      "shm": {
        "shm_name": "kong"
      },
      "redis": {
        "auth": null,
        "port": 6379,
        "database": 0,
        "host": "127.0.0.1",
        "ssl": false,
        "ssl_verify": false,
        "ssl_server_name": null,
        "namespace": ""
      },
       "consul": {
          "host": "127.0.0.1",
          "port": 8500,
          "token": null,
          "kv_path": "acme",
          "timeout": 2000,
          "https": false
      },
      "vault": {
          "host": "127.0.0.1",
          "port": 8200,
          "token": null,
          "kv_path": "acme",
          "timeout": 2000,
          "https": false,
          "tls_verify": true,
          "tls_server_name": null,
          "auth_method": "token",
          "auth_path": null,
          "auth_role": null,
          "jwt_path": null,
      },
    }

To configure a storage type other than kong, refer to lua-resty-acme.

Get started with the ACME plugin

Next ACME Configuration