Project

General

Profile

Certificate Management API

This API provides a way to update the HTTPS/TLS web certificate used by the FWD admin web server through REST, without regenerating directory.xml and without restarting the server.
It is implemented by CertRestHandler and performs a hot-reload of Jetty SSL context after storing the new certificate material.

The work on this feature was implemented in #11067.

Configuration

Certificate Management API is a sub-module of Administration_REST_API. To use it, the global REST API must be enabled. Please see Administration_REST_API. There are no additional setup requirements for this sub-module.

Add Permissions for the Certificate Management API

To access this API, grant ACL permission for the endpoint:

<node class="container" name="security">
  <node class="container" name="acl">
    <node class="container" name="webservice">
      <node class="container" name="000100">
        <node class="resource" name="resource-instance">
          <node-attribute name="reference" value="ADMIN:PUT:/admin/config/ssl-certificate"/>
          <node-attribute name="reftype" value="FALSE"/>
        </node>
        <node class="webServiceRights" name="rights">
          <node-attribute name="allow" value="true"/>
        </node>
        <node class="strings" name="subjects">
          <node-attribute name="values" value="restAdmin"/>
        </node>
      </node>
    </node>
  </node>
</node>

For the definition of admin-rest FWD user, see Administration_REST_API.

By setting this ACL, you allow:

Method Path Description Body Required
PUT /admin/config/ssl-certificate Update and hot-reload the web TLS certificate Yes

Request Object Reference

The request body is a JSON object with PEM-encoded values:

Field Type Required Description
certificate String Yes PEM-encoded leaf/server X.509 certificate.
privateKey String Yes PEM-encoded private key. Supports PKCS#8 and legacy PEM key-pair formats. The key must be unencrypted.
chain String No PEM-encoded certificate chain (intermediate/root certs). Can be empty or omitted.

API Routes

The Certificate Management API has the following capability:

  • Authentication: login/logout are provided by the main module. See Administration_REST_API.
  • Certificate update: update and hot-reload TLS assets using one PUT endpoint.

Update SSL Certificate (Hot Reload)

Update the active web certificate by performing a PUT request at /admin/config/ssl-certificate.
Header must include a valid FwdSessionId token.

  • certificate and privateKey are required.
  • chain is optional; if omitted, it is treated as empty.
  • On success, certificate data is stored and Jetty SSL is hot-reloaded.
  • The existing alias/password from directory configuration is reused when available.

Error Handling

The API uses standard HTTP status codes:

Status Code Description
200 OK The request was processed successfully and SSL context was hot-reloaded.
400 Bad Request The request was malformed, missing required fields, or contained invalid PEM material.
401 Unauthorized The FwdSessionId header is missing or the session token is invalid/expired.
500 Internal Server Error The server failed while writing the response payload.

Successful response:

{
  "success": true
}

Failed response:

{
  "success": false
}

Failed response with collected errors:

{
  "success": false,
  "errors": [
    "Error message 1",
    "Error message 2" 
  ]
}