Konfiguration

Die Konfiguration erfolgt in der Datei appsettings.json vom WebDAV-Server.

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

Serilog

Es wird das Serilog-Logsystem verwendet. 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"
            }
        }
    ]
  },

Cache

Der WebDav-Service speichert Cache-Daten in einem Verzeichnis:

"FileDistributedCache":
{
  "Path": "../cache",
  "EnableCacheCleanup": true,
  "CleanupInterval": "0.00:05:00"
}

• Path (erforderlich): Verzeichnispfad, in dem Cache-Daten gespeichert werden. Lokale Verzeichnisse, SMB- und NFS-Verzeichnisse werden unterstützt.
• EnableCacheCleanup (optional): Aktiviert einen Background-Tasks der abgelaufene Cache-Items aus dem Verzeichnispfad löscht.
• CleanupInterval (optional, default: 0.00:05:00 (5 Minuten)): Intervall einer Hintergrundaufgabe um abgelaufene Cache-Daten zu entfernen.

CMI Server

Die Parameter für die Kommunikation mit dem CMI Server werden wie gefolgt hinterlegt:

 "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.

Backend-Authentifizierung

Der WebDav-Service muss dem CMI Server valide Access-Tokens präsentieren, um Daten abzurufen. Dazu muss der WebDav-Service eine Authentifizierung gegenüber CMI STS durchführen.

Es wird der CMI STS in Version >= 3 unterstützt.

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 Einstellungen unter security

"security": {
    "login_dialog_size": "1200x800"
}

• login_dialog_size (optional): Die Grösse des von Word angezeigten 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.

Frontend-Authentifizierung

Nutzende des WebDav-Service müssen durch diesen Authentifiziert werden. Dazu gibt es zwei Methoden:

• MS-OFBA, unterstützt ab CMI Server Release 20
• URL-Token-basiert, unterstützt ab CMI Server Release 25

Für MS-OFBA gibt es keine Konfigurationsoptionen. Für die URL-Token-basierte Methode gibt es folgende Optionen:

"UrlTokenSettings": {
    "DisableUrlToken": false,
    "RefreshIntervalInMinutes": 15,
    "UrlTokenLength": 32,
    "UrlTokenInitialLifetimeInSec": 120,
    "UrlTokenLifetimeInHours": 24
}

• DisableUrlToken (optional): Deaktiviert die URL-Token-basierte Methode.
• RefreshIntervalInMinutes (optional): Interval für eine Hintergrundaufgabe, die STS Access-Tokens am CMI STS durch neue Tokens ersetzt, bevor sie ablaufen.
• UrlTokenLength (optional): Länge des URL-Tokens, welche an Microsoft Office zum abrufen eines Dokuments weitergegeben wird.
• UrlTokenInitialLifetimeInSec (optional): Initiale Gültigkeitsdauer für das URL-Token, innerhalb dessen Microsoft Office diesen verwenden muss. Bei extrem langen Startzeiten von Microsoft Office muss dieser Wert erhöht werden.
• UrlTokenLifetimeInHours (optional): Maximale Vorhalte, für die ein URL-Token gültig ist und ein entsprechendes CMI STS Token vom WebDav-Service aktuell gehalten wird. Die Vorhaltezeit wird zurückgesetzt, wenn Microsoft Office mit dem WebDav-Service kommuniziert.

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.

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

• Url (erforderlich): URL zum WebDav-Service, unter der der CMI Server und die Clients den Service erreichen können.
• MSOFBADisabled (optional): 0 aktiviert die Authentifizierungsmethode MS-OFBA, 1 deaktiviert diese.
• UrlToken (optional): 0 deaktiviert die Token-basierte Authentifizierungsmethode, 0 deaktiviert diese.

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

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",
            "webdav-api"
          ],
          "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 Authentifizieren 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:

• X-Forwarded-For
• X-Forwarded-Proto
• X-Forwarded-Host

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"
}