[feature] Introduced standalone certificate templates and device bindings

docs/developer/extending.rst

@@ -342,6 +342,7 @@ Once you have created the models, add the following to your
     CONFIG_TEMPLATE_MODEL = "sample_config.Template"
     CONFIG_VPN_MODEL = "sample_config.Vpn"
     CONFIG_VPNCLIENT_MODEL = "sample_config.VpnClient"
+    CONFIG_DEVICECERTIFICATE_MODEL = "sample_config.DeviceCertificate"
     CONFIG_ORGANIZATIONCONFIGSETTINGS_MODEL = "sample_config.OrganizationConfigSettings"
     CONFIG_ORGANIZATIONLIMITS_MODEL = "sample_config.OrganizationLimits"
     CONFIG_WHOISINFO_MODEL = "sample_config.WHOISInfo"

docs/index.rst

@@ -37,6 +37,7 @@ the OpenWISP architecture.
     user/intro.rst
     user/device-config-status.rst
     user/templates.rst
+    user/certificate-templates.rst
     user/variables.rst
     user/device-groups.rst
     user/push-operations.rst

docs/user/certificate-templates.rst

@@ -0,0 +1,219 @@
+X.509 Certificate Generator Templates
+=====================================
+
+.. contents:: **Table of Contents**:
+    :depth: 3
+    :local:
+
+Introduction
+------------
+
+A Certificate Template is a specific type of :doc:`Configuration Template
+</controller/user/templates>` that allows OpenWISP to centrally manage and
+automatically provision X.509 client certificates for devices.
+
+Unlike VPN templates, which generate certificates as part of a larger
+tunnel configuration (like OpenVPN or WireGuard), Certificate Templates
+are standalone. They are ideal for use cases where devices need
+cryptographic identities for external services, such as:
+
+- Mutual TLS (mTLS) authentication against internal APIs.
+- Cryptographically signed device identities for 802.1x or captive
+  portals.
+- Secure payload signing.
+
+.. _certificate_templates_setup:
+
+Setting Up a Certificate Template
+---------------------------------
+
+To create a Certificate Template, navigate to the Templates section in the
+OpenWISP admin and set the **Type** to :guilabel:`Certificate` (``cert``).
+This will reveal the certificate-specific configuration fields.
+
+.. image:: https://raw.githubusercontent.com/openwisp/openwisp-controller/docs/docs/1.4/certificate-templates/certificate-template.png
+    :target: https://raw.githubusercontent.com/openwisp/openwisp-controller/docs/docs/1.4/certificate-templates/certificate-template.png
+    :alt: Certificate Template admin form
+
+:guilabel:`Certificate Authority` (required)
+    The Certificate Authority that will sign the X.509 certificates
+    generated for each device using the template. The CA must belong to
+    the same organization as the template (or be shared).
+
+:guilabel:`Blueprint Certificate` (optional)
+    An existing, unassigned, non-revoked X.509 certificate that will be
+    used as a *blueprint*. The extensions, key length, digest, and other
+    subject fields of the blueprint are copied to each newly generated
+    certificate. The blueprint must be signed by the selected
+    :guilabel:`Certificate Authority` and must not already be bound to a
+    device.
+
+:guilabel:`Automatic certificate provisioning` (``auto_cert``)
+    When enabled (which is the default behavior), an X.509 certificate is
+    automatically created and signed by the template's CA the moment the
+    template is assigned to a device configuration.
+
+.. _certificate_templates_validation:
+
+Validation Rules
+----------------
+
+To ensure cryptographic integrity and prevent misconfigurations,
+Certificate Templates enforce the following validation rules upon saving:
+
+- A :guilabel:`Certificate Authority` is strictly required.
+- The :guilabel:`Blueprint Certificate` **must** be signed by the selected
+  :guilabel:`Certificate Authority`. Saving with a mismatched pair will
+  fail.
+- The :guilabel:`Blueprint Certificate` must be *unassigned* (it cannot be
+  currently bound to any device). The blueprint dropdown in the admin
+  panel is pre-filtered to show only unassigned, non-revoked certificates.
+- Both the :guilabel:`Certificate Authority` and the :guilabel:`Blueprint
+  Certificate` must belong to the same organization as the template, or be
+  marked as shared.
+
+.. _certificate_templates_lifecycle:
+
+Provisioning and Revocation Lifecycle
+-------------------------------------
+
+Certificate Templates are tightly coupled with the device configuration
+lifecycle to ensure certificates are only valid while the device is
+actively authorized to use them.
+
+**When assigned to a device:** When a Certificate Template is added to a
+device configuration, a ``DeviceCertificate`` relationship is established.
+If ``auto_cert`` is enabled, an X.509 certificate is generated and signed
+in the same database transaction:
+
+- The certificate's subject and extensions are copied from the
+  :guilabel:`Blueprint Certificate` (or the CA defaults).
+- The certificate is augmented with two custom OpenWISP OIDs that
+  cryptographically identify the device (see
+  :ref:`certificate_templates_oid_extensions`).
+- The certificate's :guilabel:`Common Name` is generated using the
+  :ref:`OPENWISP_CONTROLLER_COMMON_NAME_FORMAT
+  <openwisp_controller_common_name_format>` setting, suffixed with a
+  unique slug to prevent collisions.
+
+**When removed from a device:** When the Certificate Template is
+unassigned from a device configuration, the ``DeviceCertificate``
+relationship is deleted. Crucially, the underlying X.509 certificate is
+**automatically revoked** (provided it was created via
+``auto_cert=True``). This ensures that compromised or decommissioned
+devices immediately lose their cryptographic access.
+
+.. _certificate_templates_active_lock:
+
+Active Template Mutation Lock
+-----------------------------
+
+To prevent breaking the cryptographic binding with devices that are
+already using a template, certain destructive changes are blocked while
+the template is assigned to *active* or *activating* device
+configurations.
+
+You **cannot** change the following on an actively used template:
+
+- :guilabel:`Type` (only changing a ``cert`` template to a different type
+  is blocked)
+- :guilabel:`Certificate Authority`
+- :guilabel:`Blueprint Certificate`
+
+If you need to update these core parameters, you must first unassign the
+Certificate Template from all affected device configurations (or
+deactivate the devices), apply your template changes, and then reassign
+them.
+
+.. _certificate_templates_oid_extensions:
+
+Custom Device Identification OIDs
+---------------------------------
+
+To allow external systems to uniquely and securely identify devices by
+parsing their X.509 certificates, every automatically generated
+certificate includes two custom ASN.1 Object Identifiers (OIDs):
+
+- ``1.3.6.1.4.1.65901.1``: Contains the MAC address of the device
+  (``ASN1:UTF8:string:<mac_address>``).
+- ``1.3.6.1.4.1.65901.2``: Contains the UUID of the device
+  (``ASN1:UTF8:string:<device_id>``).
+
+These OIDs are appended securely to the certificate in addition to any
+extensions inherited from the :guilabel:`Blueprint Certificate`.
+
+.. _certificate_templates_context:
+
+Using Certificates in Configuration (Context Injection)
+-------------------------------------------------------
+
+To deploy the certificate to the device, administrators must reference the
+automatically generated variables within the template's JSON configuration
+payload.
+
+To prevent variable collisions when multiple Certificate Templates are
+assigned to a single device, OpenWISP namespaces the Jinja2 variables
+using the template's 32-character hexadecimal UUID (the UUID with dashes
+removed).
+
+The following variables are dynamically injected into the configuration
+context:
+
+- ``{{ cert_<template_uuid_hex>_pem }}``: The public certificate.
+- ``{{ cert_<template_uuid_hex>_key }}``: The private key.
+- ``{{ cert_<template_uuid_hex>_uuid }}``: The UUID of the generated
+  certificate.
+
+**Workflow Example:**
+
+1. Create a Certificate Template and click **Save and continue editing**
+   to generate its UUID.
+2. Note the UUID from the URL (e.g.,
+   ``d7d20eb8-b3c8-420c-9103-401e7960cfb3``).
+3. Strip the dashes to get the hex string
+   (``d7d20eb8b3c8420c9103401e7960cfb3``).
+4. Add the following JSON payload to write the certificate to the device's
+   filesystem:
+
+.. code-block:: json
+
+    {
+        "files": [
+            {
+                "path": "/etc/ssl/certs/device-cert.pem",
+                "mode": "0600",
+                "contents": "{{ cert_d7d20eb8b3c8420c9103401e7960cfb3_pem }}"
+            },
+            {
+                "path": "/etc/ssl/private/device-key.pem",
+                "mode": "0600",
+                "contents": "{{ cert_d7d20eb8b3c8420c9103401e7960cfb3_key }}"
+            }
+        ]
+    }
+
+When this template is assigned to a device, OpenWISP will automatically
+replace the variables with the exact, unique X.509 certificate and private
+key generated for that specific device.
+
+.. _certificate_templates_api:
+
+Certificate Templates via the REST API
+--------------------------------------
+
+The Certificate Template architecture is fully supported by the
+:doc:`OpenWISP REST API </controller/user/rest-api>`:
+
+- The ``type`` field accepts the ``cert`` enumeration.
+- ``ca`` and ``blueprint_cert`` are writable fields on the
+  ``/api/v1/controller/template/`` endpoint.
+- The ``blueprint_cert`` field is strictly filtered. Attempting to pass
+  the UUID of an already-assigned or revoked certificate will return a
+  ``400 Bad Request``.
+- The Active Mutation Lock is enforced at the serializer level: attempting
+  to patch the ``type``, ``ca``, or ``blueprint_cert`` of an actively
+  deployed template will return a ``400 Bad Request``.
+
+Additionally, you can trigger the automated creation and revocation
+lifecycle by patching the ``config.templates`` array on the :ref:`Device
+endpoint <rest_device_patch>`.

docs/user/intro.rst

@@ -35,6 +35,8 @@ following features:
 - **VPN management**: automatically provision VPN tunnel configurations,
   including cryptographic keys and IP addresses, e.g.: :doc:`OpenVPN
   </user/vpn>`, :doc:`WireGuard <wireguard>`
+- :doc:`Certificate Templates <certificate-templates>`: automatically
+  generate and manage X.509 client certificates for devices
 - :doc:`whois`: display information about the public IP address used by
   devices to communicate with OpenWISP
 - :doc:`import-export`

docs/user/rest-api.rst

@@ -1112,7 +1112,7 @@ You can filter a list of templates based on their backend using the
     GET /api/v1/controller/template/?backend={backend}
 
 You can filter a list of templates based on their type using the ``type``
-(e.g. vpn or generic).
+(e.g. vpn, cert or generic).
 
 .. code-block:: text
 

docs/user/settings.rst

@@ -308,9 +308,9 @@ levels of OpenWISP, see `netjsonconfig context: configuration variables
 The default value of the ``auto_cert`` field for new ``Template`` objects.
 
 The ``auto_cert`` field is valid only for templates which have ``type``
-set to ``VPN`` and indicates whether configuration regarding the VPN
-tunnel is provisioned automatically to each device using the template,
-e.g.:
+set to ``VPN`` or ``cert`` and indicates whether configuration regarding
+the VPN tunnel (or the x509 certificate) is provisioned automatically to
+each device using the template, e.g.:
 
 - when using OpenVPN, new `x509 <https://tools.ietf.org/html/rfc5280>`_
   certificates will be generated automatically using the same CA assigned

docs/user/templates.rst

@@ -209,3 +209,21 @@ engine: netjsonconfig.
 For more advanced technical information about templates, consult the
 netjsonconfig documentation: `Basic Concepts, Template
 <https://netjsonconfig.openwisp.org/en/latest/general/basics.html#template>`_.
+
+.. _certificate_templates:
+
+Certificate Templates
+---------------------
+
+A Certificate Template is a :doc:`Template </controller/user/templates>`
+whose **Type** is set to :guilabel:`Certificate` (``cert``). See
+:doc:`/controller/user/certificate-templates` for detailed documentation.
+
+It allows declaring the *Certificate Authority* and an optional *Blueprint
+Certificate* that will be used to issue an X.509 certificate for each
+device the template is assigned to, without needing a VPN backend.
+
+Certificate Templates are useful for any use case in which a fleet of
+devices needs an X.509 client certificate managed centrally by OpenWISP,
+for example: mutual TLS authentication against an internal service, signed
+device identities for captive portals, etc.

openwisp_controller/config/admin.py

@@ -117,7 +117,12 @@ class Media:
         css = {"all": (f"{prefix}css/admin.css",)}
         js = list(CopyableFieldsAdmin.Media.js) + [
             f"{prefix}js/{file_}"
-            for file_ in ("preview.js", "unsaved_changes.js", "switcher.js")
+            for file_ in (
+                "preview.js",
+                "unsaved_changes.js",
+                "switcher.js",
+                "template_ui.js",
+            )
         ]
 
     def get_extra_context(self, pk=None):
@@ -1060,6 +1065,8 @@ class TemplateAdmin(MultitenantAdminMixin, BaseConfigAdmin, SystemDefinedVariabl
         "organization",
         "type",
         "backend",
+        "ca",
+        "blueprint_cert",
         "default",
         "required",
         "created",
@@ -1074,13 +1081,15 @@ class TemplateAdmin(MultitenantAdminMixin, BaseConfigAdmin, SystemDefinedVariabl
         "created",
     ]
     search_fields = ["name"]
-    multitenant_shared_relations = ("vpn",)
+    multitenant_shared_relations = ("vpn", "ca", "blueprint_cert")
     fields = [
         "name",
         "organization",
         "type",
         "backend",
         "vpn",
+        "ca",
+        "blueprint_cert",
         "auto_cert",
         "tags",
         "default",
@@ -1092,7 +1101,7 @@ class TemplateAdmin(MultitenantAdminMixin, BaseConfigAdmin, SystemDefinedVariabl
         "modified",
     ]
     readonly_fields = ["system_context"]
-    autocomplete_fields = ["vpn"]
+    autocomplete_fields = ["vpn", "ca", "blueprint_cert"]
 
     @admin.action(permissions=["add"])
     def clone_selected_templates(self, request, queryset):