Skip to content

WebDav-Server

Ermöglicht den Dokumentenzugriff für den CMI Web Client.

Inhaltsverzeichnis

Allgemeines

  • Status: Freigegeben
  • Nur für speziellen Kunde: Nein

Aufgabe

Dank dem WebDAV-Server können Office Dokumente direkt aus dem Web-Client bearbeitet werden. Im Gegensatz zum CMI Explorer wird hier nicht der Registraturplan und Dossier als Filesystem bereitgestellt, sondern die Funktionalität ist auf das Bearbeiten (lesen, speichern) von Dokumenten beschränkt.

Strategische_Einordnung

Ermöglicht den Dokumentenzugriff für den CMI Web Client.

Technisches

Technische Informationen zu der Komponente.

Eigenschaften

Die Komponente erfüllt folgende Eigenschaften:

  • Stateless: *Nein
  • Skalierbar/Multiinstanzfähig: *Nein
  • Mehrmandantenfähig: Nein
  • Proxyfähig: Ja, wenn X-Forwarded-Header gesendet werden
  • Laufzeitverhalten: Web-Anwendung - Die Anwendung wird durch http-Anfragen aktiviert, es gibt keine selbständig ablaufenden internen Prozesse.

* Grundsätzlich ist der WebDav-Server stateless, ausser während dem Anmeldeprozess, bei dem ein State im Memory gehalten wird.

Sonstiges:

OPTIONS Requests drüfen nicht durch eine Firewall blockiert werden. Sie sind für die Kommunikation erforderlich.

Der WebDav-Server sendet folgende Header an Microsoft Office, um Office anzuweisen, eine Anmeldung am CMI STS vorzunehmen. Diese Header dürfen nicht durch eine Firewall gefiltert werden.

CMI WebDavServer Response-Headers: * Für die CMI STS Anmeldung * X-FORMS_BASED_AUTH_REQUIRED * X-FORMS_BASED_AUTH_RETURN_URL * X-FORMS_BASED_AUTH_DIALOG_SIZE * X-FORMS_BASED_AUTH_ACCEPTED * Um das Dokument im Bearbeitungsmodus öffnen zu können * Allow: COPY, DELETE, GET, HEAD, LOCK, MOVE, OPTIONS, POST, PROPFIND, PROPPATCH, PUT, REPORT, UNLOCK * Public: COPY, DELETE, GET, HEAD, LOCK, MOVE, OPTIONS, POST, PROPFIND, PROPPATCH, PUT, REPORT, UNLOCK * Access-Control-* * X-Engine * DAV * MS-Author-Via

Microsoft Office Request-Headers: * X-Office-Major-Version * X-MS-CookieUri-Requested * X-FeatureVersion * X-MSGETWEBURL * X-IDCRL_ACCEPTED * X-IDCRL_OPTIONS

Abhängigkeiten

Folgende Services verwendet die Komponente:

Service Version Anbindung Protokoll Standardports Verfügbarkeit Fehlertoleranzklasse
CMI Server >=19.2 on request http/s 10004 muss Reconnect
CMI STS v2/v3 on request http/s 443 muss Reconnect

Der Web Client und Microsoft Office sind Clients dieser Komponente.

Fehlertoleranz

Ist einer der abhängigen Services nicht verfügbar, funktioniert die Komponente nicht. Da die Verbindungsversuche zu den abhängigen Services für jede Client-Anfrage erneut erfolgen, stellt die Komponente ihre Funktion selbstständig wieder hier, soabld die Umsysteme verfügbar sind.

Sequenzdiagramm

1) Der Web Client ruft folgenden Link auf (Office-Uri):

ms-word:ofv|u|<webdab-server-url>/<obj-guid>/<field-id>/<filename>.<extension> 2) Das Betriebssystem leitet diesen Link an Office weiter. 3) Word ruft den WebDAV-Server auf. 4) Authentifizierung (siehe Wiki). 5) Kommunikation via WebDAV-Protokoll zwischen Office und WebDAV-Server. Der WebDAV-Server holt Dokument-Informationen und Inhalt vom CMI Server. Dokument-Locks werden in der Datenbank des CMI Servers gespeichert.

Technologiestack

Folgende Technologien werden eingesetzt: * ASP.NET Core 8.0 * WebSockets

Change-Log

Version 4.1

  • TargetFramework auf NET8 erhöht
  • NuGet Pakete ITHit.WebDAV, ITHit.Server auf v13 aktualisiert

Version 3.0

Version 2.0

  • Der frühere Parameter ExternalBaseUrl wird nicht mehr ausgewertet. Stattdessen sollte der Proxy Forwarded-For-Header senden und der Service so konfiguriert werden, dass diese ausgewertet werden. Url-Pfade werden mit dem Parameter BasePath hinterlegt.

Installation

Systemvoraussetzungen

Grundsätzlich: * Der CMI Mandant muss in jedem Fall einen CMI STS bereitgestellt haben. * Der verwendete Web-Server muss WebSockets unterstützen.

Beispielsweise für den IIS:

Installationsanleitung

Es folgt eine Zusammenfassung, die den Betrieb vom WebDAV-Server mit IIS beschreibt. Grundsätzlich kann der IIS gemäss der Dokumentation von Microsoft für eine ASP.NET Core konfiguriert werden.

  1. Internet Information Services (IIS) Manager öffnen.
  2. Unter Application Pools neuen Application Pool hinzufügen.
  3. Name des Application Pools kann frei gewählt werden.
  4. .NET CLR version muss: No Managed Code sein.
  5. Start application pool immediately: Aktivieren.
  6. Mit OK bestätigen.
  7. Unter Sites eine neue Website hinzufügen.
  8. Name der Site kann frei gewählt werden.
  9. Application Pool: Den vorhin erstellten Application Pool auswählen.
  10. Physical path: Pfad in welchem sich da API-Applikation des WebDav Services befindet.
  11. Binding: Type: Entweder http oder https (wir empfehlen https)
  12. Binding: IP-Adresse: All Unassigned
  13. Binding: Port: Frei wählbar.
  14. Binding: Hostname: Domain (bei http optional)
  15. Binding: Require Server Name Indication: optional
  16. Binding: Wenn https: SSL certificate: Ein gültiges SSL-certificate, welches auf dem Host name gebunden ist.
  17. Binding: Start Website immediately: optional (wir empfehlen: aktiviert)

Entwicklerhinweise

Hinweise zur Einrichtung der Entwicklungsumgebung und Debug-Builds.

Konfigurationsmöglichkeiten

Die Konfiguration erfolgt in der Datei appsettings.json vom WebDAV-Server. Die nachfolgenden Unterkapitel beschreiben jeweils einen Toplevel-Eintrag.

Hinweis: Pfadangaben müssen mit doppelten Backslashes geschrieben werden.

Serilog

Es wird das Serilog-Logsystem ververwendet. Dazu kann die Dokumentation unter serilog-settings-configuration abgerufen werden.

Der folgende Ausschnitt ist eine Beispielkonfiguration. Unter WriteTo unter Args muss der Pfad (path) angepasst werden.

"Serilog": {
    "MinimumLevel": {
      "Default": "Debug",
      "Override": {
        "Microsoft": "Warning",
        "System": "Warning"
      }
    },
    "WriteTo": [
        {
            "Name": "File",
            "Args": {
                "rollingInterval": "Day",
                "rollOnFileSizeLimit": true,
                "fileSizeLimitBytes": 100000,
                "path": "%TEMP%\\webdav_mandant_log-{Date}.log"
            }
        }
    ]
  },

CMI Server

 "ServerService": {
    "ApiBaseUrl": "https://mandant.kunde.ch/private/"
  },

ApiBaseUrl ist die vollständige URL, die auf den OWIN-private Endpoint vom CMI Server zeigen muss. Falls ein Relay-Server im Einsatz ist, muss die URL von diesem angegeben werden.

Authentication

Es wird der CMI STS in Version 2 oder 3 unterstützt. Im Falle eines CMI STS 2 erfolgt ein Impersonate. Dies steht beim CMI STS 3 so nicht mehr zur Verfügung. Bei CMI STS 3 wird für den Anwendungsfall Office für iOS/Android ein kurzlebiges Web-Token in ein langlebiges umgewandelt (delegation).

Konfiguration für CMI STS 2.x

"security": {
    "authority": "https://sts.kunde.ch/identity",
    "client_id": "webAppClient",
    "client_secret": "E2cATXM4bIquHPVf",
    "acr_values": "tenant:kunde.mandant"
}
  • authority (erforderlich): Die Url vom CMI STS.
  • Die client_id (optional): Der Default ist webAppClient. Ein Client mit dieser ID muss beim CMI STS ebenfalls konfiguriert sein.
  • Das client_secret (erforderlich): Das Client Secret muss mit dem Client Secret übereinstimmten, dass beim CMI STS hinterlegt wurde.

Konfiguration für CMI STS 3

"security": {
    "authority": "https://sts3.kunde.ch/mandant",
    "client_id": "webdav",
    "client_secret": "E2cATXM4bIquHPVf"
}
  • authority (erforderlich): Die Url vom CMI STS. Beim CMI STS 3 inkl. der Mandantenkennung (im obigen Besispiel mandant)
  • client_id (erforderlich): Eine beliebige Client ID. Ein Client mit dieser ID muss beim CMI STS ebenfalls konfiguriert sein.
  • client_secret (erforderlich): Das Client Secret muss mit dem Client Secret übereinstimmten, dass beim CMI STS hinterlegt wurde.

Weitere optionale Einsellungen unter security

"security": {
    "login_dialog_size": "1200x800"
}
  • login_dialog_size (optional): Die Grösse des von Word angeziegten Anmeldefensters (default: 1200x800).

Achtung: Der frühere Parameter ExternalBaseUrl wird nicht mehr ausgewertet. Stattdessen sollte der Proxy Forwarded-For-Header senden und der Service so konfiguriert werden, dass diese ausgewertet werden. Url-Pfade werden mit dem Parameter BasePath hinterlegt.

WebDav-Einstellungen

Diese optionalen Einstellungen betreffen die WebDAV-Engine.

"DavEngineOptions": {
    "UseFullUris": true,
    "OutputXmlFormatting": true
  },
  "DavLoggerOptions": {
    "LogFile": "..\\logs\\WebDAVlog.txt",
    "IsDebugEnabled": true
  }

Bei LogFile handelt es sich um das Log der WebDAV-Engine. Dieser Pfad ist zu setzen.

Konfiguration der Umsysteme

Die folgenden KOnfigurationen müssen an den Umsystemen vorgenommen werden, damit diese mit dem WebDav-Server zusammenarbeiten.

Konfiguration des CMI Servers

Die Konfiguration erfolgt in der Datei metatool.ini vom CMI.Server.Service.

[WebDAV]
Url = https://cmi-webdav_mandant.kunde.ch

Konfiguration der Web Clients

Die Konfiguration erfolgt in der Datei config.json im Web Client.

"webDav": {
    "serviceUrl": "https://cmi-webdav-mandant.kunde.ch"
},

Konfiguration des CMI STS

CMI STS 2:

Bei STS 2 ist es notwendig, dass der Client mit der client_id aus der WebDAV-Server Konfiguration für Impersonat konfiguriert ist (Client-Secret).

CMI STS 3:

Für den Mandanten einen spezifischen Client anlegen:

"Clients": [
        {
          "ClientId": "webdav",
          "AccessTokenLifetime": 36000,
          "AllowAccessTokensViaBrowser": true,
          "AllowedGrantTypes": ["delegation", "implicit"],
          "RedirectUris":["<WebDav-Basis-Url>/account/callback"],
          "AllowedScopes": [
            "openid",
            "profile",
            "metatool"
          ],
          "ClientSecrets": [
            {
              "value": "Sha-512 encodiertes Client-Secret. Siehe hierzu auch die STS 3 Dokumentation zur Client-Konfiguration.",
              "description": "Eine optionale Beschreibung des Secrets."
            }
          ]
        }
    ]
  • Das AccessTokenLifetime muss hoch sein (aus fachlicher Sicht 12 Stunden).
  • AllowedGrantTypes muss sowohl implicit (Anmeldung bei Office für Desktop) als auch delegation enthalten (Office für iOS und Android).
  • In ClientSecrets.0.value wird das Secret eingetragen, dass der WebDAV-Server zum Lösen des Delegation-Token verwendet (wird nur bei Authentifizieng von Office für Android und iOS gebraucht).

Betrieb hinter einem Proxy

Wird der Service hinter einem Proxy betrieben, ist die Herkunft einer Anfrage nicht bekannt. Callback-Urls und Cookies werden nicht korrekt an den Client zurückgeliefert.

Microsoft dokumentiert das Szenario einer ASP.NET Core Anwendung hinter einem Proxy im Artikel "Configure ASP.NET Core to work with proxy servers and load balancers".

Um zu prüfen, welche Redirect-Uris der Service an Clients wie Microsoft Office sendet, kann der Diagnose-Endpunkt /info/discovery direkt mit einem Browser aufgerufen werden.

X-Forwarded Header

Viele Proxies senden zusätzliche http-Header um die Herkunft einer Anfrage dem Zielsystem mitzuteilen:

Der Service kann konfiguriert werden, diese Header anstatt der Verbindungsinformationen des Proxies zu verwenden. Wenn keine Konfiguration vorgenommen wird, werden die Header nicht verwendet.

Das Verhalten zu den Forward-Headern wird in der Sektion ForwardedHeaders konfiguriert. Es stehen alle Optionen der Klasse ForwardedHeadersOptions zur Verfügung.

In diesem Abschnitt wird die Dokumentation der Klasse ForwardedHeadersOptions von Microsoft nicht wiederholt, es werden nur Konfigurationshinweise zu einigen Optionen dokumentiert.

  • ForwardedHeaders: Wenn mehrere Optionen dieses Flags verwendet werden sollen, können die Flags kommagetrennt aufgeführt werden. All aktiviert alle Optionen.
  • KnownProxies: Bekannte Proxies können als Array von Ip-Adressen angegeben werden.
  • KnownNetworks: Bekannte Netzwerke können als Array in der CIDR-Notation 0.0.0.0/0 / 0:0:0:0:0:0:0:0/0 angegeben werden.
{
  "ForwardedHeaders": {
    "ForwardedHeaders": "XForwardedFor, XForwardedHost, XForwardedProto",
    "KnownProxies": ["10.0.0.6", "10.0.0.7"],
    "KnownNetworks": [ "10.0.0.0/8", "::1/128"]
  }
}

Basispfad / Hosting in einem anderen Unterverzeichnis

Beinhaltet die öffentliche Url einen Basis-Url-Pfad, werden Callback-Urls generiert, bei denen dieser Pfad fehlt. Der Basispfad muss dem Service bekannt gemacht werden:

{
  // Der Basis-Pfad muss mit einem Slash beginnen
  "BasePath": "/mybasepath"
}

Beispiel:

  • Öffentliche Url am Proxy: https://example.com/services/webdav
  • Binding am Web Server: https://myhost.local/webdav
  • Zu konfigurierender Pfad: /services/webdav

Hinweis: Dieses Beispiel muss mit den X-Forwarded-Host Header kombiniert werden, damit statt myhost.local, der Host example.com verwendet wird.

CORS konfigurieren

Wenn der Webclient sowie der WebDAV-Server auf unterschiedlichen URLs laufen, ist es nötig in der Config des WebDAVs die URL des Webclients zu hinterlegen damit Requests von diesem aus nicht fehlschlagen. Dies geschieht über AllowedCors unter Security:

"security": {
    "authority": "https://sts3.kunde.ch/mandant",
    "client_id": "webdav",
    "client_secret": "E2cATXM4bIquHPVf"
    "AllowedCors": "localhost:4200"
}

Troubleshooting

Ping / Versionsabfrage

Es gibt den anonymen Endpoint GET /info/version um die Version vom WebDAV-Server als Json abzufragen.

Office: Die Anmeldemethode könnte unsicher sein

Office zeigt die Meldung: Office hat diesen Inhalt blockiert, weil er eine Anmeldemethode verwendet, die unsicher sein könnte.

Office-Fehlermeldung

In diesem Fall muss die Domain des Web Clients den sicheren Anmeldemethoden im Trust Center hinzugefügt werden.

Möglicherweise kann der Benutzer diese Einstellungen selbst vornehmen oder diese Einstellungen werden von der Organisation gesteuert. Wenn der Benutzer selbst keine Einstellungen im Trust Center hinzufügen kann, muss der IT-Betreiber diese Einstellung zentral für alle Benutzer vornehmen.

Hinzufügen der Ausnahme im Trust Center

Den Button Trust Center öffnen anklicken und im Trust Center die Option Aktion für jeden Host anfragen aktivieren.

Office Trust Center

Anschliessend kann das Dokument erneut geöffnet werden. Office fragt den Benutzer, ob die angegebene Domain vertrauenswüdig ist. Wenn mit Ja bestätigt wird, kann das Dokument geöffnet werden.

Login Methode hinzufügen

Hinzufügen der Ausnahme in den Gruppenrichtlinien (zentrale Steuerung in der Organisation)

Der IT-Betreiber kann eine Gruppenrichtline erstellen, die die Domain des Web Clients (nicht des CMI STS) dem Trust Center hinzufügt.

Verwendet der Kunde beispielsweise die Url https://cmi.gemeinde.ch/webclient um den Web Client zu verwenden, so muss die Domain cmi.gemeinde.ch freigeschaltet werden.

  1. Möglicherweise muss der IT-Betreiber administrative Templates (ADMX/ADML) für Office auf den Domain Controller installieren:

https://www.microsoft.com/en-us/download/details.aspx?id=49030 2. Die folgende Ressource hilft, einen Gruppenrichtlinie zu erstellen:

https://admx.help/?Category=Office2016&Policy=office16.Office.Microsoft.Policies.Windows::L_AuthenticationFBABehavior

Eine mögliche Policy könnte wie gefolgt aussehen.

Trust Center Policy

Office: konnte nicht geöffnet werden

Office zeigt die Meldung: konnte leider nicht geöffnet werden.

Login Methode hinzufügen

Es handelt sich um eine allgemeine Fehlermeldung die die Ursache des Problems nicht benennt. In einem solchen Fall sind die Logs aller beteiltigen Systeme zu prüfen:

  • CMI Server
  • CMI WebDav-Server
  • CMI STS

Erscheint diese Fehlermeldung bevor das Anmeldefenster des CMI STS erscheint, wurde Office die Url des CMI STS nicht mitgeteilt oder die Kommunikation mit dem CMI STS war nicht möglich.

Die Login-Methode wird über Request-/Response-Header ausgehandelt. Wenn eine Firewall Request- und Response-Header filtert, weiss Office nicht, dass eine Anmeldung erforderlich. Die erforderlichen Header sind im Kapitel Technisches aufgelistet. Mit dem IT-Betreiber ist zu prüfen, ob diese Header bei Office ankommen.

Office: Schreibgeschützte Dokumente

Wenn Dokumente nur schreibgeschützt geöffnet werden können, wurden möglicherweise benötigte Response-Header aus der Kommunikation zwischen dem WebDav-Server und Microsoft Office durch eine Firewall entfernt. Die erforderlichen Header sind im Kapitel Technisches aufgelistet. Mit dem IT-Betreiber ist zu prüfen, ob diese Header bei Office ankommen.

Schreibgeschütztes Dokument

Office: Office öffnet sich, aber anschliessend wir kein Dokument geladen / kein STS Anmeldefester geöffnet

Mit den Developer-Tools des Browsers herausfinden, mit welche URL an Office übergeben wird.

Browser Developer Tools

Mit der URL das Powershell-Script auf dem betroffenen Endgerät ausführen:

try{
    Invoke-WebRequest -UseBasicParsing -Uri "https://[...].docx" -Headers @{ "X-FORMS_BASED_AUTH_ACCEPTED"="T"  }
}
catch{
    $headers = $_.Exception.Response.Headers
    $headers.AllKeys | ForEach-Object { "$($_) $($headers[$_])" }
}

Die Antwort sollte den Status-Code 403 (Unauthorized) haben und daher sollte das Script in den Catch-Block fallen. Die Script-Ausgabe sollte folgende Header enthalten:

X-FORMS_BASED_AUTH_REQUIRED https://sts.[...]/identity/connect/authorize?client_id=webdav&response_type=id_token%20token&scope=openid%20profile%20metatool&redirect_uri=[...]&state=[...]&nonce=[...]&acr_values=[...]&response_mode=form_post
X-FORMS_BASED_AUTH_RETURN_URL https://[...]/account/success
X-FORMS_BASED_AUTH_DIALOG_SIZE 1200x800
[...]
  • Kontrollieren, ob die X-FORMS-Header vorhanden sind.
  • Kontrollieren, ob die URL zum STS und WebDav korrekt sind.
  • Stimmt die Client-ID?
  • Stimmt die Redirect-Uri?