Konfiguration

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

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

Serilog

{
  "Serilog": {
    "MinimumLevel": {
      "Default": "[LEVEL]"
    },
    "WriteTo": [
      {
        "Name": "Console"
      },
      {
        "Name": "File",
        "Args": {
          "rollingInterval": "Day",
          "path": "[PATH]"
        }
      }
    ]
  }
}

Dies ist die Serilog-Konfiguration. Serilog wird insbesondere für das File-Logging gebraucht.

MinimumLevel.Default

Folgende Log-Level werden unterstützt:

Verbose
Debug
Information
Warning
Error
Fatal

Die Log-Level Verbose und Debug sollten nur für Fehlersuche gesetzt werden, da die geloggte Menge gross werden kann.

WriteTo.Args.Path

Hier wird der Pfad zum Log-File gesetzt. Bsp.: C:\\temp\\logs-cmi-api\\cmi-api-.log

Weitere Konfigurationen

Weitere Konfigurationsmöglichkeiten siehe https://github.com/serilog/serilog-settings-configuration.

ForwardedHeaders

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

Api-Config

{
  "ApiConfig": {
    "AutoRebootOnConfigChangeEnabled": true,
    "WebHookOnConfigChange": {
      "Uri": null,
      "HttpMethod": "Get"
    },
    "EnableMonitoring": true,
    "ClearMonitoringDataAfterXMinutes": 60
  }
}

Dieser Abschnitt steuert das allgemeine Verhalten der CMI API und betrifft alle Mandanten.

AutoRebootOnConfigChangeEnabled

Mit der Einstellung AutoRebootOnConfigChangeEnabled lässt sich steuern, ob die API nach einer Änderung in irgendeinem Tenant automatisch neu gestartet werden soll. Wird bei einem Tenant etwas geändert, so startet die komplette API automatisch neu.

Diese Einstellung ist standardmässig true.

WebHookOnConfigChange

Mit der Einstellung WebHookOnConfigChange lässt sich steuern, ob die API nach einer Änderung in irgendeinem Tenant, einen Web Hook an die konfigurierte URL sendet (wenn WebHookOnConfigChange.Uri ungleich null).

WebHookOnConfigChange.Uri: URL des Web Hooks
WebHookOnConfigChange.HttpMethod: Http-Request-Methode, der Standardwert ist Get

Es wird ein Http-Response-Status Code von >=200 und <=299 erwartet. Ist der Http-Request nicht erfolgreich, wird dem Benutzer gemeldet, dass das Speichern der Konfiguration nicht erfolgreich war. Die Änderungen wurden zwar persistiert, jedoch konnten externe Systeme nicht über die Änderung informiert werden.

EnableMonitoring

Mit der Einstellung EnableMonitoring lässt sich das Monitoring ein- und ausschalten.

ClearMonitoringDataAfterXMinutes

Mit der Einstellung ClearMonitoringDataAfterXMinutes lässt sich einstellen, wie lange die Monitoring-Daten gespeichert bleiben.

Mandant (Tenant)

{
  "Tenants": {
    "[Tenant-Key]": {
      "CmiStsUri": "[STS-URL]",
      "CmiStsClientId": "[STS-Client-ID]",
      "CmiPrivateUri": "[PROTOKOLL]://[DOMAIN]:[OWIN-PRIVATE-PORT]",
      "PathApiConfig": "[PATH]",
      "Throttling": {
        "MaxWaitingRequests": 2,
        "MaxConcurrentRequests": 1
      },
      "KpfProcessLayerNamespaces": [
        "[Namespace]"
      ]
    }
  }
}

In der "Tenants"-Sektion werden einzelne Mandanten als eigenständige JSON-Objekte innerhalb des "Tenants"-Objekts definiert. Der Schlüssel des jeweiligen Objekts entspricht dabei dem Namen des Mandanten. Hier ist ein Beispiel mit den Mandanten prod und test:

{
  "Tenants": {
    "prod": {
      ...
    },
    "test": {
      ...
    }
  }
}

CmiStsUri

Url zum STS inkl. Mandant. Beispiel.: https://sts3.cloud.ch/<MANDANT>/identity

CmiStsClientId

ClientID für den OpenId Connect flow. Der Client muss den Grant-Type "authorization_code" unterstützen.

Die Minimalkonfiguration vom STS ist hier zu finden.

CmiPrivateUri

Url zur Metatool API. Die Url muss auf dem Owin-Privateport gerichtet sein. Beispiel.: https://mandant.cmicloud.ch:10004

PathApiConfig

Path zum Konfigurationsfile der CMI API. Das File muss nicht existieren. Es muss jedoch sichergestellt werden, dass genügend Rechte vorhanden sind damit die API das File selbst erstellen kann. Wird die API in einem IIS betrieben, so muss der ApplicationPool genügend Rechte haben um im jeweiligen Ordner ein File zu erstellen. Beispiel.: C:\\CMI-API\\Mandant\\apiconfig.txt"

ThrottlingConfig

Die ThrottlingConfig beinhaltet die Einstellungen für das Throttling der API. Hierbei handelt es sich um ein sogenanntes Concurrency-Throttling. Der Zweck dieses Throttle-Mechanismus besteht darin, sicherzustellen, dass nicht zu viele parallele Requests gleichzeitig ausgeführt werden können. Beim Concurrency-Throttling gibt es zwei einstellbare Parameter:

MaxConcurrentRequests: Dies steuert die maximale Anzahl von parallelen Anfragen, die gleichzeitig laufen dürfen.
MaxWaitingRequests: Dies steuert die maximale Anzahl von Anfragen, die in der Warteschlange stehen dürfen, wenn bereits die maximale Anzahl von parallelen Anfragen ausgeführt wird.

Wenn kein Platz mehr für gleichzeitige Anfragen oder in der Warteschlange verfügbar ist, wird der StatusCode 429 ( TooManyRequests) zurückgegeben.

Die Throttling-Einstellungen werden für jeden Mandanten separat auf Tenant-Ebene festgelegt. Dabei wird jedoch die Verwaltung (wie viele Requests gemacht werden dürfen) für jede CMI-API-Gruppe separat durchgeführt. Das bedeutet, dass die Throttling-Konfiguration individuell für jeden Mandanten angepasst werden kann, während gleichzeitig das Throttling-Verhalten für jede spezifische CMI-API-Gruppe des Mandanten separat verfolgt und gesteuert wird.

Geblockte Anfragen aufgrund des Throttle-Mechanismus werden im Debug-Endpoint zur Verfügung gestellt.

MaxWaitingRequests

Maximale Anzahl von Anfragen, die in der Warteschlange stehen dürfen. Standard ist hier 2.

Der Wert kleiner oder gleich 0 wird als unendlich interpretiert.

MaxConcurrentRequests

Maximale Anzahl von parallelen Anfragen. Standard ist hier 1.

Der Wert kleiner oder gleich 0 wird als unendlich interpretiert.

KpfProcessLayerNamespaces

Namespace-Auflistung der KPF Prozess-Layer. Die KPF Prozess-Layer (inkl. alle möglichen Namespaces) sind hier beschrieben.