Skip to content

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

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"