Update WebDAV Configuration #1008

knstvk · knstvk · commit 4b07964181ba · 2025-09-03T18:04:17.000+04:00
diff --git a/content/modules/webdav/pages/configuration.adoc b/content/modules/webdav/pages/configuration.adoc
@@ -5,77 +5,39 @@
 
 To authenticate desktop applications, the server must have HTTPS enabled. Here are simple instructions for configuring HTTPS in your development environment.
 
-[IMPORTANT]
-====
-Self-signed certificates are suitable solely for testing purposes. When running production applications, it's essential to utilize SSL certificates issued by a trusted authority.
-====
+[[trusted-certificate]]
+=== Generating Trusted Certificate
+
+Trusted  certificates can be obtained from SSL certificate providers or generated with `certbot`. But for the development purposes you can issue your own root certificate and sign development server's certificate with it. To simplify this task, we recommend using the `mkcert` tool.
 
-[[keystore-file]]
-=== Creating a Keystore File
+. Install `mkcert` by following the instructions provided in its repository: https://github.com/FiloSottile/mkcert[https://github.com/FiloSottile/mkcert^].
 
-. Generate a keystore using the https://docs.oracle.com/en/java/javase/11/tools/keytool.html[keytool utility^] provided by JDK:
+. Generate and install the root certificate:
 +
-[source,text]
+[source]
 ----
-keytool -genkey -keyalg RSA -alias localhost -keystore localhost.jks -validity 365 -keysize 2048
+mkcert -install
 ----
-+
-You will be asked for the keystore password and then for some names. Remember the password and the names.
 
-. Export certificate from the keystore:
+. Create a certificate for localhost:
 +
-[source,text]
+[source]
 ----
-keytool -export -keystore localhost.jks -storepass <password> -alias localhost -file localhost.cer
+mkcert -pkcs12 localhost 127.0.0.1 ::1
 ----
 +
-Use the password entered on the first step instead of `<password>`.
+You will see the `localhost+2.p12` file in the current folder.
 
-. Register the certificate as trusted in your operating system.
+. Create a keystore file with the certificate for your project:
 +
-* On Windows operating system:
+[source]
+----
+keytool -importkeystore -srckeystore localhost+2.p12 -srcstoretype pkcs12 -destkeystore localhost.jks
+----
 +
-1. Press the `Windows` key + `R` to open the *Run* dialog, then type `"certmgr.msc"` and press *Enter*. This will open the *Certificate Manager*.
-
-2. In the left pane of the *Certificate Manager*, expand the *Trusted Root Certification Authorities* folder.
-
-3. Right-click on the folder and select *All Tasks > Import...* from the context menu. This will open the *Certificate Import Wizard*.
-
-4. In the *Certificate Import Wizard*, click *Next* and then browse to the location where your certificate file is stored. Select the certificate file and click *Next*.
-
-5. Choose the option to place the certificate in the *Trusted Root Certification Authorities* store and click *Next*.
-
-6. Review the information and click *Finish* to complete the import process.
-
-7. You should see a message indicating that the import was successful. Click *OK* to close the wizard.
+Enter `changeit` as the source keystore password.
 +
-Once these steps are completed, the certificate should be registered as trusted in the Windows operating system.
-* On macOS:
-1. Double-click on `localhost.cer` file in Finder. The *Keychain Access* application will open.
-2. Find your certificate under the name entered on the first step as "your first and last name" on the *Certificates* tab.
-3. Double-click the certificate and select *Trust -> When using this certificate: Always Trust*.
-
-=== Generate trusted certificate
-
-Some use cases like opening WebDAV files in recent LibreOffice and Firefox versions may not work with self-signed certificates. Trusted
-certificates can be obtained from SSL-providers or generated with `certbot`. But for the development purposes you can issue
-your own root certificate and sign development server's certificate with it. To simplify this task we recommend to use
-`mkcert` generation/maintenance tool. You can skip this section in case you are ok with HTTPS warnings and restrictions.
-
-. Install `mkcert` from the following repo: https://github.com/FiloSottile/mkcert[https://github.com/FiloSottile/mkcert].
-You can build it either from source (requires golang to be installed) and copy binary to `/usr/local/bin` or use binaries provided by vendor.
-
-. Once having `mkcert` in path you can generate and install root certificate:
-
-    mkcert -install
-
-. Navigate to keystore directory and create signed certificates for your development server:
-
-    mkcert -pkcs12 localhost 127.0.0.1 ::1
-
-. Create `.jks` keystore file with certificates for your project:
-
-    keytool -importkeystore -srckeystore localhost+2.p12 -srcstoretype pkcs12 -destkeystore localhost.jks
+You will see the `localhost.jks` file in the current folder.
 
 [[configuring-server]]
 === Configuring Server
diff --git a/content/modules/webdav/pages/configuring-https.adoc b/content/modules/webdav/pages/configuring-https.adoc
@@ -1,56 +1,52 @@
-= 3. Configuring to Work with Desktop Applications
+= 3. Working with Desktop Applications
 
 To authenticate desktop applications, the server must have HTTPS enabled. Here are simple instructions for configuring HTTPS in your development environment.
 
-[IMPORTANT]
-====
-Self-signed certificates are suitable solely for testing purposes. When running production applications, it's essential to utilize SSL certificates issued by a trusted authority.
-====
+[[using-libreoffice]]
+== Using LibreOffice
+
+Install LibreOffice and configure the xref:webdav-properties.adoc#jmix.webdav.applications[jmix.webdav.applications] property to open all files in it:
+
+[source,properties]
+----
+jmix.webdav.applications = {"vnd.libreoffice.command":\
+  {"name":"LibreOffice","protocols":\
+  {"writable":"vnd.libreoffice.command:ofe|u|",\
+  "read_only":"vnd.libreoffice.command:ofv|u|"},\
+  "extensions":["odt", "ods", "odp", "doc", "docx", "xls", "xlsx", "ppt", "pptx"]}}
+----
 
 [[keystore-file]]
 == Creating a Keystore File
 
-. Generate a keystore using the https://docs.oracle.com/en/java/javase/11/tools/keytool.html[keytool utility^] provided by JDK:
+. Install `mkcert` utility by following the instructions provided in its repository: https://github.com/FiloSottile/mkcert[https://github.com/FiloSottile/mkcert^].
+
+. Generate and install the root certificate:
 +
-[source,text]
+[source]
 ----
-keytool -genkey -keyalg RSA -alias localhost -keystore localhost.jks -validity 365 -keysize 2048
+mkcert -install
 ----
-+
-You will be asked for the keystore password and then for some names. Remember the password and the names.
 
-. Export certificate from the keystore:
+. Create a certificate for localhost:
 +
-[source,text]
+[source]
 ----
-keytool -export -keystore localhost.jks -storepass <password> -alias localhost -file localhost.cer
+mkcert -pkcs12 localhost 127.0.0.1 ::1
 ----
 +
-Use the password entered on the first step instead of `<password>`.
+You will see the `localhost+2.p12` file in the current folder.
 
-. Register the certificate as trusted in your operating system.
+. Create a keystore file with the certificate for your project:
 +
-* On Windows operating system:
+[source]
+----
+keytool -importkeystore -srckeystore localhost+2.p12 -srcstoretype pkcs12 -destkeystore localhost.jks
+----
 +
-1. Press the `Windows` key + `R` to open the *Run* dialog, then type `"certmgr.msc"` and press *Enter*. This will open the *Certificate Manager*.
-
-2. In the left pane of the *Certificate Manager*, expand the *Trusted Root Certification Authorities* folder.
-
-3. Right-click on the folder and select *All Tasks > Import...* from the context menu. This will open the *Certificate Import Wizard*.
-
-4. In the *Certificate Import Wizard*, click *Next* and then browse to the location where your certificate file is stored. Select the certificate file and click *Next*.
-
-5. Choose the option to place the certificate in the *Trusted Root Certification Authorities* store and click *Next*.
-
-6. Review the information and click *Finish* to complete the import process.
-
-7. You should see a message indicating that the import was successful. Click *OK* to close the wizard.
+Enter `changeit` as the source keystore password.
 +
-Once these steps are completed, the certificate should be registered as trusted in the Windows operating system.
-* On macOS:
-1. Double-click on `localhost.cer` file in Finder. The *Keychain Access* application will open.
-2. Find your certificate under the name entered on the first step as "your first and last name" on the *Certificates* tab.
-3. Double-click the certificate and select *Trust -> When using this certificate: Always Trust*.
+You will see the `localhost.jks` file in the current folder.
 
 [[configuring-server]]
 == Configuring Server
@@ -90,12 +86,12 @@ server.ssl.key-store = classpath:com/example/demo/keystore/localhost.jks
 [source,java,indent=0]
 ----
 @EventListener
-    public void printApplicationUrl(final ApplicationStartedEvent event) {
-        LoggerFactory.getLogger(DemoApplication.class).info("Application started at "
-                + "https://localhost:"
-                + environment.getProperty("local.server.port")
-                + Strings.nullToEmpty(environment.getProperty("server.servlet.context-path")));
-    }
+public void printApplicationUrl(final ApplicationStartedEvent event) {
+    LoggerFactory.getLogger(DemoApplication.class).info("Application started at "
+            + "https://localhost:"
+            + environment.getProperty("local.server.port")
+            + Strings.nullToEmpty(environment.getProperty("server.servlet.context-path")));
+}
 ----
 
 [[running-application]]
@@ -107,13 +103,7 @@ Choose the *Knowledge base* item from the *Application* menu. Click on the WebDA
 
 image::open-webdav-doc1.png[align="center", width="1432"]
 
-The browser will display a dialog prompting the user to open the WebDAV file in a desktop office application.
-
-image::open-webdav-doc2.png[align="center", width="1432"]
-
-Agree to open the file and ensure that the WebDAV document opens in desktop office applications.
-
-image::open-office.png[align="center", width="1080"]
+The browser will display a dialog prompting the user to open the WebDAV file in LibreOffice. Agree to open the file.
 
 Once the WebDAV document is edited and saved, a new version of the document will be created, which will be the latest version.
 
diff --git a/content/modules/webdav/pages/index.adoc b/content/modules/webdav/pages/index.adoc
@@ -49,8 +49,10 @@ implementation 'io.jmix.webdav:jmix-webdav-flowui-starter'
 Desktop applications use basic authentication for server connections via WebDAV, so you have to set up HTTPS for your web application. Refer to the xref:configuration.adoc#https[Configuring HTTPS] section for guidance on configuring HTTPS on localhost for development purposes.
 
 [[requirements]]
-== Minimal Requirements
+== Requirements
 
-The minimum version of Microsoft Office needed to access documents via the WebDAV protocol is MS Office 2010 SP2 or higher. For LibreOffice, the minimum required version is 6.3.
+IMPORTANT: Due to recently disabled Basic authentication in Microsoft 365 applications (see https://learn.microsoft.com/en-us/microsoft-365-apps/security/basic-authentication-prompts-blocked[^]), the WebDAV add-on cannot work with the latest versions of Microsoft Office.
+
+The minimum version of Microsoft Office needed to access documents via the WebDAV protocol is MS Office 2010 SP2. For LibreOffice, the minimum required version is 6.3.
 
 To verify the installed versions of Microsoft Office and Service Pack (SP) on your computer, open MS Word and navigate to the *Product Information* section via *File → Help*. Service Pack 2 for MS Office 2010 (and subsequent versions) should display the following number: 14.0.7015.1000 (or higher). To update your Service Pack, click on this https://www.microsoft.com/en-US/download/details.aspx?id=39667[link^].
diff --git a/content/modules/webdav/pages/view-with-webdav-documents.adoc b/content/modules/webdav/pages/view-with-webdav-documents.adoc
@@ -99,5 +99,5 @@ In this section, you have created the basic feature of the application: a knowle
 
 You have learned that:
 
-* The WebDAV add-on offers the `WebdavDocument` entity, which represents a document within the WebDAV functionality. This entity facilitates editing and viewing documents using external applications such as Microsoft Word and Excel, managing document versions, and controlling access to specific documents.
+* The WebDAV add-on offers the `WebdavDocument` entity, which represents a document within the WebDAV functionality. This entity facilitates editing and viewing documents using external applications, managing document versions, and controlling access to specific documents.
 * The xref:flow-ui:vc/components/entityPicker.adoc[entityPicker] component is used by default to select a reference in a generated detail view. Clicking the ellipsis button for the *WebDAV document* field will open the standard xref:webdav:webdav-documents.adoc[WebDAV documents view] provided by the add-on.
