Configuration

Configuring HTTPS

To authenticate desktop applications, the server must have HTTPS enabled. Here are simple instructions for configuring HTTPS in your development environment.

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.

Creating a Keystore File

  1. Generate a keystore using the keytool utility provided by JDK:

    keytool -genkey -keyalg RSA -alias localhost -keystore localhost.jks -validity 365 -keysize 2048

    You will be asked for the keystore password and then for some names. Remember the password and the names.

  2. Export certificate from the keystore:

    keytool -export -keystore localhost.jks -storepass <password> -alias localhost -file localhost.cer

    Use the password entered on the first step instead of <password>.

  3. Register the certificate as trusted in your operating system.

    • On Windows operating system:

      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.

        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.

  1. Install mkcert from the following repo: 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.

  2. Once having mkcert in path you can generate and install root certificate:

    mkcert -install

  3. Navigate to keystore directory and create signed certificates for your development server:

    mkcert -pkcs12 localhost 127.0.0.1 ::1

  4. Create .jks keystore file with certificates for your project:

    keytool -importkeystore -srckeystore localhost+2.p12 -srcstoretype pkcs12 -destkeystore localhost.jks

Configuring Server

This section explains how to use the certificate generated in the previous section in your application when it runs from the IDE or as an executable JAR.

  1. Create src/main/resources/<base-package>/keystore directory and copy localhost.jks into it.

  2. Set the following properties in the application.properties file replacing <base-package> and <password> with actual values:

    # Enables HTTPS
server.ssl.enabled=true
# The format used for the keystore
server.ssl.key-store-type = JKS
# The path to the keystore containing the certificate
server.ssl.key-store = classpath:<base-package>/keystore/localhost.jks
# The password used to generate the keystore
server.ssl.key-store-password = <password>
# The alias mapped to the certificate
server.ssl.key-alias = localhost

# Changes the server's port
server.port = 8443

    The <base-package> in the path to the keystore (server.ssl.key-store property) should be presented as a slash-separated path:

    server.ssl.key-store = classpath:com/example/demo/keystore/localhost.jks

  3. Open the main application class and change the printApplicationUrl() method. The URL should be changed to https:// after configuring HTTPS:

    @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")));
    }

Maintenance Tasks

The WebDAV add-on includes several maintenance tasks, as described below. To run these tasks regularly, include the Quartz add-on in your project as outlined in the Quartz / Installation section.

ExpiredLockCleaningJob

This job removes expired lock objects. By default, it runs every two hours.

To modify the job schedule, use the jmix.webdav.expired-lock-cleaning-cron property.

WebdavDocumentVersionsCleaningJob

This job removes WebdavDocumentVersion instances that are not associated with any documents. By default, it runs once a month.

To change the job schedule, use the jmix.webdav.document-versions-cleaning-cron property.

Configuring Security

Access restrictions for documents are set up using resource and row-level roles.

Predefined Roles

The Jmix application with the WebDAV add-on includes two default resource roles:

  • WebDAV: minimal access - a fundamental WebDAV role necessary for all users utilizing WebDAV functionality.

  • WebDAV: view document browser - provides permission to access the WebDAV documents view.