feat(web-modeler): ssl setup

docs/self-managed/modeler/web-modeler/configuration/configuration.md

@@ -62,7 +62,7 @@ Web Modeler integrates with Identity and Keycloak for authentication and authori
 | `SPRING_SECURITY_OAUTH2_RESOURCESERVER_JWT_ISSUER_URI` | URL of the token issuer (used for JWT validation).                                                                                                                                                                                                                                      | `https://keycloak.example.com/auth/realms/camunda-platform` |
 | `RESTAPI_OAUTH2_TOKEN_ISSUER_BACKEND_URL`              | [optional]<br/>[Internal](#notes-on-host-names-and-port-numbers) URL used to request Keycloak's [OpenID Provider Configuration](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfig); if not set, `SPRING_SECURITY_OAUTH2_RESOURCESERVER_JWT_ISSUER_URI` is used. | `http://keycloak:8080/auth/realms/camunda-platform`         |
 
-Refer to the [advanced Identity configuration guide](./identity.md) for additional details on how to set up secure connections to an external Identity instance or connect a custom OpenID Connect (OIDC) authentication provider.
+Refer to the [advanced Identity configuration guide](./identity.md) for additional details on how to connect a custom OpenID Connect (OIDC) authentication provider.
 
 ### Zeebe Client
 
@@ -87,6 +87,20 @@ For more details, [see the Zeebe connection troubleshooting section](/self-manag
 
 Refer to the [advanced logging configuration guide](./logging.md#logging-configuration-for-the-restapi-component) for additional details on how to customize the `restapi` logging output.
 
+### SSL
+
+| Environment variable                            | Description                                                                          | Example value                        | Default value |
+| ----------------------------------------------- | ------------------------------------------------------------------------------------ | ------------------------------------ | ------------- |
+| `SERVER_SSL_ENABLED`                            | [optional]<br/>Whether to enable SSL support.                                        | `true`                               | `false`       |
+| `SERVER_SSL_CERTIFICATE`                        | [optional]<br/>Path to a PEM-encoded SSL certificate file.                           | `file:/full/path/to/certificate.pem` | -             |
+| `SERVER_SSL_CERTIFICATE_PRIVATE_KEY`            | [optional]<br/>Path to a PEM-encoded private key file for the SSL certificate.       | `file:/full/path/to/key.pem`         | -             |
+| `MANAGEMENT_SERVER_SSL_ENABLED`                 | [optional]<br/>Whether to enable SSL support for the management server routes.       | `true`                               | `false`       |
+| `MANAGEMENT_SERVER_SSL_CERTIFICATE`             | [optional]<br/>Path to a PEM-encoded SSL certificate file.                           | `file:/full/path/to/certificate.pem` | -             |
+| `MANAGEMENT_SERVER_SSL_CERTIFICATE_PRIVATE_KEY` | [optional]<br/>Path to a PEM-encoded private key file for the SSL certificate.       | `file:/full/path/to/key.pem`         | -             |
+| `RESTAPI_PUSHER_SSL_ENABLED`                    | [optional]<br/>Whether to enable communication via SSL to the `websocket` component. | `true`                               | `false`       |
+
+Refer to the [advanced SSL configuration guide](./ssl.md) for additional details on how to set up secure connections (incoming & outgoing) to the Web Modeler components.
+
 ## Configuration of the `webapp` component
 
 ### General
@@ -119,7 +133,7 @@ Refer to the [advanced logging configuration guide](./logging.md#logging-configu
 | `OAUTH2_TOKEN_ISSUER`                     | URL of the token issuer (used for JWT validation).                                                                                                                                                                                                                  | `https://keycloak.example.com/auth/realms/camunda-platform`                       | -             |
 | `IDENTITY_BASE_URL`                       | [Internal](#notes-on-host-names-and-port-numbers) base URL of the Identity API (used to fetch user data).                                                                                                                                                           | `http://identity:8080`                                                            | -             |
 
-Refer to the [advanced Identity configuration guide](./identity.md) for additional details on how to set up secure connections to an external Identity instance or connect a custom OpenID Connect (OIDC) authentication provider.
+Refer to the [advanced Identity configuration guide](./identity.md) for additional details on how to connect a custom OpenID Connect (OIDC) authentication provider.
 
 ### WebSocket
 
@@ -146,6 +160,23 @@ The `webapp` component sends certain events (e.g. "user opened diagram", "user l
 
 Refer to the [Advanced Logging Configuration Guide](./logging.md#logging-configuration-for-the-webapp-component) for additional details on how to customize the `webapp` logging output.
 
+### SSL
+
+| Environment variable             | Description                                                                                            | Example value                   | Default value |
+| -------------------------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------- | ------------- |
+| `SSL_ENABLED`                    | [optional]<br/>Whether to enable SSL support.                                                          | `true`                          | `false`       |
+| `SSL_CERT`                       | [optional]<br/>Path to a PEM-encoded SSL certificate file.                                             | `/full/path/to/certificate.pem` | -             |
+| `SSL_KEY`                        | [optional]<br/>Path to a PEM-encoded private key file for the SSL certificate.                         | `/full/path/to/key.pem`         | -             |
+| `SSL_PASSPHRASE`                 | [optional]<br/>Passphrase for the private key file.                                                    | `change-me`                     | -             |
+| `MANAGEMENT_SSL_ENABLED`         | [optional]<br/>Whether to enable SSL support for management server routes.                             | `true`                          | `false`       |
+| `MANAGEMENT_SSL_CERT`            | [optional]<br/>Path to a PEM-encoded SSL certificate file.                                             | `/full/path/to/certificate.pem` | -             |
+| `MANAGEMENT_SSL_KEY`             | [optional]<br/>Path to a PEM-encoded private key file for the SSL certificate.                         | `/full/path/to/key.pem`         | -             |
+| `MANAGEMENT_SSL_PASSPHRASE`      | [optional]<br/>Passphrase for the private key file.                                                    | `change-me`                     | -             |
+| `RESTAPI_SSL_ENABLED`            | [optional]<br/>Whether to enable communication via SSL to the `restapi` component.                     | `true`                          | `false`       |
+| `RESTAPI_MANAGEMENT_SSL_ENABLED` | [optional]<br/>Whether to enable communication via SSL to the `restapi` component's management routes. | `true`                          | `false`       |
+
+Refer to the [advanced SSL configuration guide](./ssl.md) for additional details on how to set up secure connections (incoming & outgoing) to the Web Modeler components.
+
 ## Configuration of the `websocket` component
 
 The [WebSocket](https://en.wikipedia.org/wiki/WebSocket) server shipped with Web Modeler Self-Managed is based on the [laravel-websockets](https://laravel.com/docs/10.x/broadcasting#open-source-alternatives-php) open source package and implements the [Pusher Channels Protocol](https://pusher.com/docs/channels/library_auth_reference/pusher-websockets-protocol/).
@@ -165,6 +196,16 @@ The [WebSocket](https://en.wikipedia.org/wiki/WebSocket) server shipped with Web
 
 Refer to the [Advanced Logging Configuration Guide](./logging.md#logging-configuration-for-the-websocket-component) for additional details on how to customize the `websocket` logging output.
 
+### SSL
+
+| Environment variable    | Description                                                                    | Example value                   | Default Value |
+| ----------------------- | ------------------------------------------------------------------------------ | ------------------------------- | ------------- |
+| `PUSHER_SSL_CERT`       | [optional]<br/>Path to a PEM-encoded SSL certificate file.                     | `/full/path/to/certificate.pem` | -             |
+| `PUSHER_SSL_KEY`        | [optional]<br/>Path to a PEM-encoded private key file for the SSL certificate. | `/full/path/to/key.pem`         | -             |
+| `PUSHER_SSL_PASSPHRASE` | [optional]<br/>Passphrase for the private key file.                            | `change-me`                     | -             |
+
+Refer to the [advanced SSL configuration guide](./ssl.md) for additional details on how to set up secure connections (incoming & outgoing) to the Web Modeler components.
+
 ## Notes on host names and port numbers
 
 - _Internal_ refers to host names and port numbers that are only used inside a Docker Compose network or Kubernetes cluster for backend-to-backend communication.

docs/self-managed/modeler/web-modeler/configuration/identity.md

@@ -1,33 +1,9 @@
 ---
 id: identity
 title: "Identity"
-description: "Read details on how to connect Web Modeler with Identity securely."
+description: "Read details on how to connect Web Modeler to a custom OIDC provider."
 ---
 
-## Configuring secure connections to Identity
-
-By default, communication between Web Modeler and Identity is not encrypted, as it usually happens backend-to-backend within the same [Docker](/self-managed/setup/deploy/other/docker.md) network or [Kubernetes](/self-managed/setup/install.md) cluster.
-However, you can enable TLS-encrypted communication by following the steps below (for example, if backend-to-backend communication is not possible in a custom Camunda 8 installation setup).
-
-### Configure the Identity base URL
-
-Provide a URL that starts with `https://` (e.g. `https://identity.example.com`) as the base URL of the Identity instance:
-
-- For the `modeler-webapp` container, provide the URL via the environment variable `IDENTITY_BASE_URL`.
-- For the `modeler-restapi` container, provide the URL via the environment variable `RESTAPI_IDENTITY_BASE_URL`.
-
-### (Optional) Provide a custom certificate
-
-If you are using a custom (self-signed) TLS certificate for Identity, you need to make Web Modeler accept the certificate:
-
-- For the `modeler-webapp` container, provide the path to the certificate file via the environment variable `NODE_EXTRA_CA_CERTS` (make sure that the provided path is accessible from the container, e.g. via a mounted volume):
-  ```sh
-  NODE_EXTRA_CA_CERTS=/path/to/certificate.crt
-  ```
-- For the `modeler-restapi` container:
-  - Add the certificate to a custom Java trust store (using the [`keytool`](https://docs.oracle.com/en/java/javase/21/docs/specs/man/keytool.html) utility).
-  - Configure the trust store as described in the [Zeebe connection troubleshooting guide](../troubleshooting/troubleshoot-zeebe-connection.md#provide-the-certificate-to-the-jvm-trust-store).
-
 ## Using a different OpenID Connect (OIDC) authentication provider than Keycloak
 
 By default, Web Modeler uses Keycloak for providing authentication.

docs/self-managed/modeler/web-modeler/configuration/ssl.md

@@ -0,0 +1,102 @@
+---
+id: ssl
+title: "SSL"
+description: "Read details on additional SSL configuration for Web Modeler."
+---
+
+By default, communication between the Web Modeler and Identity and the Web Modeler components is not encrypted, as it usually happens backend-to-backend within the same [Docker](/self-managed/setup/deploy/other/docker.md) network or [Kubernetes](/self-managed/setup/install.md) cluster.
+However, you can enable TLS-encrypted communication by following the steps below (for example, if backend-to-backend communication is not possible in a custom Camunda 8 installation setup).
+
+## Configuring secure connections to Identity
+
+### Configure the Identity base URL
+
+Provide a URL that starts with `https://` (e.g. `https://identity.example.com`) as the base URL of the Identity instance:
+
+- For the `modeler-webapp` container, provide the URL via the environment variable `IDENTITY_BASE_URL`.
+- For the `modeler-restapi` container, provide the URL via the environment variable `RESTAPI_IDENTITY_BASE_URL`.
+
+## Configuring secure connections between Web Modeler components
+
+### Configure `restapi` SSL certificate
+
+SSL can be configured declaratively by setting the respective properties offered by Spring Boot, e.g. (make sure that the provided certificate path is accessible from the container, e.g. via a mounted volume):
+
+```
+RESTAPI_SERVER_URL=https://web-modeler.example.com
+
+SERVER_SSL_ENABLED=true
+SERVER_SSL_CERTIFICATE=file:/full/path/to/certificate.pem
+SERVER_SSL_CERTIFICATE_PRIVATE_KEY=file:/full/path/to/key.pem
+```
+
+Additionally, you can configure SSL separately for the management routes of the `restapi` component:
+
+```
+MANAGEMENT_SERVER_SSL_ENABLED=true
+MANAGEMENT_SERVER_SSL_CERTIFICATE=file:/full/path/to/certificate.pem
+MANAGEMENT_SERVER_SSL_CERTIFICATE_PRIVATE_KEY=file:/full/path/to/key.pem
+```
+
+Refer to the [Spring Boot documentation](https://docs.spring.io/spring-boot/how-to/webserver.html#howto.webserver.configure-ssl) for more information on configuration options.
+
+#### Use secure connections between the `restapi` and `websocket` components
+
+To use secure connections between the `restapi` and `websocket` components, provide the following environment variable:
+
+```
+RESTAPI_PUSHER_SSL_ENABLED=true
+```
+
+### Configure `webapp` SSL certificate
+
+To configure SSL for the `webapp` component, provide the following environment variables (make sure that the provided certificate path is accessible from the container, e.g. via a mounted volume):
+
+```
+SERVER_URL=https://web-modeler.example.com
+
+SSL_ENABLED=true
+SSL_CERTIFICATE=/full/path/to/certificate.pem
+SSL_KEY=/full/path/to/key.pem
+SSL_PASSPHRASE=your-passphrase
+```
+
+Additionally, you can configure SSL separately for the management routes of the `webapp` component:
+
+```
+MANAGEMENT_SSL_ENABLED=true
+MANAGEMENT_SSL_CERTIFICATE=/full/path/to/certificate.pem
+MANAGEMENT_SSL_KEY=/full/path/to/key.pem
+MANAGEMENT_SSL_PASSPHRASE=your-passphrase
+```
+
+#### Use secure connections between the `webapp` and `restapi` components
+
+To use secure connections between the `webapp` and `restapi` components, provide the following environment variable:
+
+```
+RESTAPI_SSL_ENABLED=true
+RESTAPI_MANAGEMENT_SSL_ENABLED=true
+```
+
+### Configure `websocket` SSL certificate
+
+SSL can be configured by setting the following environment variables (make sure that the provided certificate path is accessible from the container, e.g. via a mounted volume):
+
+```
+PUSHER_SSL_CERT=/full/path/to/certificate.pem
+PUSHER_SSL_KEY=/full/path/to/key.pem
+PUSHER_SSL_PASSPHRASE=your-passphrase
+```
+
+## (Optional) Provide a custom certificate
+
+If you are using a custom (self-signed) TLS certificate for either `restapi`, `webapp` or Identity, you need to make Web Modeler accept the certificate:
+
+- For the `modeler-webapp` container, provide the path to the certificate file via the environment variable `NODE_EXTRA_CA_CERTS` (make sure that the provided path is accessible from the container, e.g. via a mounted volume):
+  ```sh
+  NODE_EXTRA_CA_CERTS=/path/to/certificate.crt
+  ```
+- For the `modeler-restapi` container:
+  - Add the certificate to a custom Java trust store (using the [`keytool`](https://docs.oracle.com/en/java/javase/21/docs/specs/man/keytool.html) utility).
+  - Configure the trust store as described in the [Zeebe connection troubleshooting guide](../troubleshooting/troubleshoot-zeebe-connection.md#provide-the-certificate-to-the-jvm-trust-store).

optimize_sidebars.js

@@ -2918,6 +2918,10 @@ module.exports = {
                       "Logging",
                       "self-managed/modeler/web-modeler/configuration/logging/"
                     ),
+                    docsLink(
+                      "SSL",
+                      "self-managed/modeler/web-modeler/configuration/ssl/"
+                    ),
                   ],
                 },
 

sidebars.js

@@ -1421,6 +1421,7 @@ module.exports = {
                     "self-managed/modeler/web-modeler/configuration/database",
                     "self-managed/modeler/web-modeler/configuration/identity",
                     "self-managed/modeler/web-modeler/configuration/logging",
+                    "self-managed/modeler/web-modeler/configuration/ssl",
                   ],
                   Troubleshooting: [
                     "self-managed/modeler/web-modeler/troubleshooting/troubleshoot-database-connection",