Minor enhancements

SailReal · SailReal · commit be479deedf7c · 2026-08-05T07:58:36.000+02:00
diff --git a/docs/hub/deployment.mdx b/docs/hub/deployment.mdx
@@ -116,82 +116,6 @@ Before running this deployment
 
 Troubleshooting: If you encounter problems, check the log files in `logs/traffik.log` and `logs/access.log`. Make sure you entered `srv` as `Public Network` in the Setup Wizard of Hub.
 
-## Trusting a Private Certificate Authority {/* #trusting-a-private-certificate-authority */}
-
-If Hub connects to a Keycloak instance whose TLS certificate was not issued by a well-known certificate authority, you have to make the issuing CA known to Hub. Hub runs on the JVM, which uses its own trust store and ignores the certificates trusted by the host system.
-
-Start by preparing a file `rootWithIntermediates.pem` that contains the root certificate and all intermediate certificates that are not publicly available, in PEM format. Then create a PKCS12 trust store from it:
-
-```bash
-keytool -importcert \
-    -alias keycloak-ca-chain \
-    -file rootWithIntermediates.pem \
-    -keystore keycloak-truststore.p12 \
-    -storepass changeit \
-    -noprompt
-```
-
-Replace `changeit` with a password of your own. You can verify the result with `keytool -list -v -keystore keycloak-truststore.p12 -storepass changeit`.
-
-Hub reads the trust store from the Java system properties `javax.net.ssl.trustStore` and `javax.net.ssl.trustStorePassword`, which you pass as arguments to the application command.
-
-In Docker Compose, mount the file into the container and override the command:
-
-```yaml
-services:
-  hub:
-    image: ghcr.io/cryptomator/hub:latest
-    command: >
-      ./application
-      -Djavax.net.ssl.trustStore=/etc/certs/keycloak-truststore.p12
-      -Djavax.net.ssl.trustStorePassword=changeit
-    volumes:
-      - './certs/keycloak-truststore.p12:/etc/certs/keycloak-truststore.p12:ro'
-```
-
-In Kubernetes, store the trust store in a secret and mount it as a volume. Encode the file with `base64 -w0 keycloak-truststore.p12` and add the output to a secret:
-
-```yaml
-apiVersion: v1
-kind: Secret
-metadata:
-  namespace: hub
-  name: instance-secrets
-type: Opaque
-data:
-  keycloak-truststore-p12: BASE64_ENCODED_TRUSTSTORE
-```
-
-Then reference it in the deployment:
-
-```yaml
-apiVersion: apps/v1
-kind: Deployment
-metadata:
-  name: cryptomator-hub
-  namespace: hub
-spec:
-  template:
-    spec:
-      containers:
-        - name: cryptomator-hub
-          image: ghcr.io/cryptomator/hub:latest
-          command: ['./application']
-          args:
-            - '-Djavax.net.ssl.trustStore=/etc/certs/keycloak-truststore-p12'
-            - '-Djavax.net.ssl.trustStorePassword=changeit'
-          volumeMounts:
-            - name: keycloak-truststore-p12
-              mountPath: /etc/certs
-              readOnly: true
-```
-
-:::note
-Quarkus also offers the configuration options `QUARKUS_OIDC_CERTIFICATE_CHAIN_TRUST_STORE_FILE` and `QUARKUS_OIDC_CERTIFICATE_CHAIN_TRUST_STORE_PASSWORD`. These do not work for this purpose, so use the Java system properties shown above.
-:::
-
-If the Cryptomator desktop app also needs to talk to that Hub instance, the same applies there. Add `java-options=-Djavax.net.ssl.trustStore=/path/to/your/truststore` to the `Cryptomator.cfg` file in the installation directory.
-
 ## Backup {/* #backup */}
 
 Cryptomator Hub and Keycloak both write to the connected Postgres database. So the best and easiest way is to backup it cyclically using e.g. a Cron Job. Depending on your deployment, here is a sample command that you can run on the host system to backup the entire databases to a file using the Postgres container, which you than could import in a similar way:
@@ -268,3 +192,78 @@ A successful run prints `Verified OK`.
 
 The Hub image itself is attested by the `build.yml` workflow of the same repository. To verify it, use the corresponding image name and adjust `--certificate-identity-regexp` to that workflow and the Git reference the release was built from.
 
+## Trusting a Private Certificate Authority {/* #trusting-a-private-certificate-authority */}
+
+If Hub connects to a Keycloak instance whose TLS certificate was not issued by a well-known certificate authority, you have to make the issuing CA known to Hub. Hub runs on the JVM, which uses its own trust store and ignores the certificates trusted by the host system.
+
+Start by preparing a file `rootWithIntermediates.pem` that contains the root certificate and all intermediate certificates that are not publicly available, in PEM format. Then create a PKCS12 trust store from it:
+
+```bash
+keytool -importcert \
+    -alias keycloak-ca-chain \
+    -file rootWithIntermediates.pem \
+    -keystore keycloak-truststore.p12 \
+    -storepass changeit \
+    -noprompt
+```
+
+Replace `changeit` with a password of your own. You can verify the result with `keytool -list -v -keystore keycloak-truststore.p12 -storepass changeit`.
+
+Hub reads the trust store from the Java system properties `javax.net.ssl.trustStore` and `javax.net.ssl.trustStorePassword`, which you pass as arguments to the application command.
+
+In Docker Compose, mount the file into the container and override the command:
+
+```yaml
+services:
+  hub:
+    image: ghcr.io/cryptomator/hub:latest
+    command: >
+      ./application
+      -Djavax.net.ssl.trustStore=/etc/certs/keycloak-truststore.p12
+      -Djavax.net.ssl.trustStorePassword=changeit
+    volumes:
+      - './certs/keycloak-truststore.p12:/etc/certs/keycloak-truststore.p12:ro'
+```
+
+In Kubernetes, store the trust store in a secret and mount it as a volume. Encode the file with `base64 -w0 keycloak-truststore.p12` and add the output to a secret:
+
+```yaml
+apiVersion: v1
+kind: Secret
+metadata:
+  namespace: hub
+  name: instance-secrets
+type: Opaque
+data:
+  keycloak-truststore-p12: BASE64_ENCODED_TRUSTSTORE
+```
+
+Then reference it in the deployment:
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: cryptomator-hub
+  namespace: hub
+spec:
+  template:
+    spec:
+      containers:
+        - name: cryptomator-hub
+          image: ghcr.io/cryptomator/hub:latest
+          command: ['./application']
+          args:
+            - '-Djavax.net.ssl.trustStore=/etc/certs/keycloak-truststore-p12'
+            - '-Djavax.net.ssl.trustStorePassword=changeit'
+          volumeMounts:
+            - name: keycloak-truststore-p12
+              mountPath: /etc/certs
+              readOnly: true
+```
+
+:::note
+Quarkus also offers the configuration options `QUARKUS_OIDC_CERTIFICATE_CHAIN_TRUST_STORE_FILE` and `QUARKUS_OIDC_CERTIFICATE_CHAIN_TRUST_STORE_PASSWORD`. These do not work for this purpose, so use the Java system properties shown above.
+:::
+
+If the Cryptomator desktop app also needs to talk to that Hub instance, the same applies there. Add `java-options=-Djavax.net.ssl.trustStore=/path/to/your/truststore` to the `Cryptomator.cfg` file in the installation directory.
diff --git a/docs/hub/keycloak.mdx b/docs/hub/keycloak.mdx
@@ -16,10 +16,6 @@ Connecting external identity and access management (IAM) solutions is available
 Visit [cryptomator.org](https://cryptomator.org/hub/) for more information about Enterprise features.
 :::
 
-:::warning
-Your Hub instance always contains the two system users `admin` and `syncer`. **Do not edit or delete them!** These accounts are required for administration and synchronization tasks.
-:::
-
 ## Connecting an External Identity Provider {/* #connecting-an-external-identity-provider */}
 
 You can connect Hub to your existing identity provider so that users authenticate with the credentials they already have. Keycloak supports two fundamentally different approaches, and the choice affects when users become visible in Hub.
@@ -28,17 +24,6 @@ With user federation over LDAP or Active Directory, Keycloak reads the directory
 
 With identity brokering over OpenID Connect or SAML, Keycloak redirects users to the external provider. Users only appear in Hub after their first successful login, so you cannot grant vault access to someone who has never signed in.
 
-### LDAP and Active Directory {/* #ldap-and-active-directory */}
-
-To federate users from an LDAP directory, add an LDAP provider under *User federation* in the `cryptomator` realm and enter the connection URL, the bind credentials, and the base DN of your directory. The [Keycloak documentation on LDAP](https://www.keycloak.org/docs/latest/server_admin/#_ldap) describes the individual settings.
-
-Hub additionally requires two mappers on the LDAP provider:
-
-1. Add a *group-ldap-mapper* so that directory groups are imported into Keycloak. Without it, only users are synchronized and you cannot assign vault permissions to groups.
-2. Add a *hardcoded-ldap-role-mapper* that assigns the realm role `user` to every imported user. Users without this role cannot log in to Hub.
-
-Once both mappers are in place, run *Sync all users* on the LDAP provider. Afterwards, verify the setup by logging in to Hub — not Keycloak — with one of the imported accounts.
-
 ### OpenID Connect {/* #openid-connect */}
 
 To delegate authentication to an OpenID Connect provider such as Microsoft Entra ID, add an OpenID Connect provider under *Identity providers* in the `cryptomator` realm and enter the discovery endpoint, client ID, and client secret issued by your provider.
@@ -55,6 +40,17 @@ In Keycloak, open your identity provider and add one *Claim to Role* mapper per
 
 These mappers are evaluated lazily as well. A role is only assigned when the affected user logs in.
 
+### LDAP and Active Directory {/* #ldap-and-active-directory */}
+
+To federate users from an LDAP directory, add an LDAP provider under *User federation* in the `cryptomator` realm and enter the connection URL, the bind credentials, and the base DN of your directory. The [Keycloak documentation on LDAP](https://www.keycloak.org/docs/latest/server_admin/#_ldap) describes the individual settings.
+
+Hub additionally requires two mappers on the LDAP provider:
+
+1. Add a *group-ldap-mapper* so that directory groups are imported into Keycloak. Without it, only users are synchronized and you cannot assign vault permissions to groups.
+2. Add a *hardcoded-ldap-role-mapper* that assigns the realm role `user` to every imported user. Users without this role cannot log in to Hub.
+
+Once both mappers are in place, run *Sync all users* on the LDAP provider. Afterwards, verify the setup by logging in to Hub — not Keycloak — with one of the imported accounts.
+
 ### Using the Identity Provider as Default Login {/* #using-the-identity-provider-as-default-login */}
 
 By default, Keycloak shows a login form with the external provider as an additional button. You can skip that screen and redirect users straight to your provider by entering its alias as the default identity provider in the browser authentication flow, as described in the [Keycloak documentation](https://www.keycloak.org/docs/latest/server_admin/index.html#default_identity_provider).
@@ -73,10 +69,6 @@ When a user logs in through an external provider for the first time, Keycloak as
 4. Select *Identity providers* in the left panel and open your identity provider.
 5. Scroll down to *First login flow*, select the duplicated flow, and save.
 
-:::note
-On hosted Hub instances you cannot create authentication flows yourself, but you can select any flow that already exists.
-:::
-
 ### Customizing the Username {/* #customizing-the-username */}
 
 Keycloak derives the username of brokered accounts from the email address reported by the identity provider. If you need a different scheme, add a *Username Template Importer* mapper to your identity provider and set its target to `LOCAL`.
diff --git a/docs/hub/user-group-management.mdx b/docs/hub/user-group-management.mdx
@@ -188,9 +188,3 @@ Setting up LDAP synchronization is described in the [Keycloak documentation](htt
 For OpenID Connect and SAML, the Keycloak documentation provides [general information](https://www.keycloak.org/docs/latest/server_admin/#_identity_broker).
 
 The [Keycloak](keycloak.mdx) page covers the configuration steps that are specific to Hub, such as [connecting an external identity provider](keycloak.mdx#connecting-an-external-identity-provider), [restricting who may access Hub](keycloak.mdx#restricting-access-to-hub), and [migrating to another identity provider](keycloak.mdx#migrating-to-another-identity-provider).
-
-
-:::warning
-Regardless of your IAM setup, your Hub instance always contains two system users: `admin` and `syncer`. **Do not edit or delete them!** These accounts are required for administration and synchronization tasks.
-:::
-
