Skip to content

Installation und Konfiguration

Systemvoraussetzungen

Vor der Installation des Audit-Servers muss sichergestellt sein, dass die folgenden Systemvoraussetzungen erfüllt sind:

  • MSSQL Server oder PostgreSQL vorhanden
  • .Net Core 8 IIS Hosting Bundle (IIS Betrieb) oder .Net Core 8 Runtime (Windows Service Betrieb) sind installiert.
  • Eine neue Datenbank erstellt und ein Benutzer mit entsprechenden Rechten angelegt

Installation

Der Audit-Server kann auf zwei verschiedene Arten installiert und betrieben werden.

IIS

Der Audit-Server kann auf einem Windows Server durch IIS betrieben werden. Führen Sie folgende Schritte durch für die Installation:

  1. Den neusten Audit-Server Release herunterladen und entpacken.
  2. Im IIS einen neuen Application-Pool mit der Einstellung .NET CLR No Maanged Code erstellen.
  3. Eine neue IIS-Site erstellen die den vorher erstellen Application-Pool verwendet. Speicherot für den Website-Ordner kann frei gewählt werden.
  4. Den Inhalt des Ordners cmi-audit-server aus dem entpackten Release in den Website-Ordner kopieren.
  5. Im IIS nach bedarf weitere Konfigurationen für die Site vornehmen (bspw. SSL-Zertifikat, Domain-Binding, etc.).
  6. In den Einstellungen des Application-Pools den startMode auf "AlwaysRunning" setzen.
  7. Sicherstellen, dass der Application-Pool Lese- und Schreibrechte auf den Website-Ordner hat.

Windows Service

Ist kein Windows Server mit IIS vorhanden, ist ein Betrieb als Windows Service möglich. Befolgen Sie hierzu folgende Schritte:

  1. Den neusten Audit-Server Release herunterladen und entpacken.
  2. Auf dem Server einen neuen Ordner erstellen, in welchem die Audit-Server Binaries abgelegt werden können (bspw. C:\Program Files\CMI-Audit-Server).
  3. Den Inhalt des Ordners cmi-audit-server aus dem entpackten Release in den neuen Ordner kopieren.
  4. Powershell als Administrator öffnen und folgenden Befehl ausführen: New-Service -Name "CMI-Audit-Server" -BinaryPathName "<Installations_Ordner>\CMI.AuditServer.Api.exe --windows-service" -DisplayName "CMI Audit Server" -StartupType Automatic -Description "CMI Audit Server"

Im Windows Service Betrieb nutzt der Audit-Server Kestrel als Webserver. Kestrel ist ein in .NET Core integrierte Webserver von Microsoft. Die Konfiguration erfolgt über die appsettings.Production.json Datei. Weitere Informationen zur Konfiguration von Kestrel finden Sie hier.

Die folgende Kestrel-Konfiguration dient als einfaches Beispiel:

{
  "Kestrel": {
    "Endpoints": {
      "Http": {
        "Url": "https://*:5000"
      },
    },
    "Certificates": {
      "Default": {
        "Path": "<path to .pfx file>",
        "Password": "$CREDENTIAL_PLACEHOLDER$"
      }
    }
  }
}

RabbitMQ

Als Queue-Schnittstelle zwischen CMI Server und Audit-Server wird RabbitMQ verwendet. Für die Installation auf Windows müssen folgende Schritte durchgeführt werden:

  1. Installieren Sie die neuste Version von Erlang als Administrator.
  2. Laden Sie den RabbitMQ Server Windows Installer herunter und installieren Sie ebenfalls als Administrator.
  3. Öffnen Sie PowerShell als Administrator und aktivieren Sie das RabbitMQ Management Plugin mit den folgenden Befehlen:
cd "C:\Program Files\RabbitMQ Server\rabbitmq_server-4.0.7\sbin"
.\rabbitmq-plugins.bat enable rabbitmq_management
  1. Die RabbitMQ-CLI-Tools verwenden zur Authentifizierung ein Cookie. Dieses muss im aktuellen User-Profil hinterlegt werden, damit die CLI-Tools verwendet werden können:
cp "C:\Windows\system32\config\systemprofile\.erlang.cookie" "$($env:USERPROFILE)\.erlang.cookie" -force
  1. RabbitMQ ist nun installiert und das Management UI unter http://localhost:15672 erreichbar. Eine Anmeldung ist mit dem Benutzernamen guest und dem Passwort guest möglich.

Konfiguration des Audit-Servers

Nachdem der Audit-Server installiert wurde, muss dieser noch konfiguriert werden. Die Konfiguration befindet sich in der Datei appsettings.Production.json im Installations-Ordner.

{
  "Serilog": {
    "Using": [
      "Serilog.Sinks.Console",
      "Serilog.Sinks.File",
      "Serilog.Enrichers.Thread",
      "Serilog.Enrichers.Environment"
    ],
    "Enrich": [
      "FromLogContext",
      "WithMachineName",
      "WithThreadId"
    ],
    "MinimumLevel": {
      "Default": "Information",
      "Override": {
        "Microsoft": "Warning",
        "System": "Warning",
        "MassTransit": "Warning",
        "CMI": "Debug"
      }
    },
    "WriteTo": [
      {
        "Args": {
          "path": "./logs/log-.log",
          "rollingInterval": "Day",
          "outputTemplate": "[{Timestamp:HH:mm:ss} {Level} <{ThreadId}> {SourceContext}] [t:{Tenant}] {Message:lj}{NewLine}{Exception}"
        },
        "Name": "File"
      },
      {
        "Name": "Console",
        "Args": {
          "outputTemplate": "[{Timestamp:HH:mm:ss} {Level} <{ThreadId}> {SourceContext}] [t:{Tenant}] {Message:lj}{NewLine}{Exception}"
        }
      }
    ]
  },
  "Database": {
    "DatabaseProvider": "MSSQL",
    "PerformMigrationOnStartup": false,
    "ConnectionStrings": {
      "POSTGRESQL": "host=localhost:5434;database=<database>;username=<user>;password=<password>",
      "MSSQL": "Server=localhost,1440;Database=<database>;User Id=<user>;Password=<password>"
    }
  },
  "AuditServer": {
    "HashingSecret": "<hashingSecret>",
    "CleanupJobsRunTime": "05:00:00",
    "TenantCleanup": {
      "Enabled": false
    }
  },
  "RabbitMq": {
    "Nodes": [
      "localhost:5672"
    ],
    "ManagementApiBaseUrl": "http://localhost:15672",
    "Username": "<rabbit_mq_admin_user>",
    "Password": "<rabbit_mq_admin_password>",
    "MaxMessageConcurrency": 80
  },
  "Tenants": {
    "<your_tenant_id>": {
      "Authentication": {
        "StsUri": "https://<sts-url>/<your_tenant_id>/identity",
        "AuthorizedStsUserIds": [
          "<user_id>"
        ]
      },
      "ServiceBusConfig": {
        "SecretHash": "<cmi_server_queue_user_secret_hash>"
      },
      "AuditCleanup": {
        "Enabled": true,
        "AuditLogRetentionPeriod": "365.00:00:00"
      }
    }
  }
}

Datenbank

Als Datenbank kann wahlweise MSSQL Server oder PostgreSQL verwendet werden. Die Konfiguration erfolgt in der Section Databse. Je nach Datenbank muss der Wert für DatabaseProvider auf MSSQL oder POSTGRES gesetzt werden. Anschliessend muss der entsprechende Connection-String mit dem korrekten Host, Database, User und Password konfiguriert werden.

Der Audit-Server ist in der Lage, das Datenbank-Schema selbstständig zu erstellen. Hierzu kann die Option PerformMigrationOnStartup aktiviert werden. Der verwendete User muss die entsprechenden Rechte auf die Datenbank besitzen. Alternativ können die Tabellen auch manuell mithilfe der SQL-Scripts erstellt werden, die im Release enthalten sind. Die Option PerformMigrationOnStartup darf nicht aktiviert werden, wenn der Audit-Server in einem skaliert betrieben wird, da sonst mehrere Instanzen gleichzeitig versuchen, das Schema zu erstellen.

RabbitMq

Der Audit-Server verwendet RabbitMq als Schnittstelle zwischen dem CMI Server und sich selbst. Der Audit-Server kommuniziert sowohl über AMQP als auch HTTP(s) mit dem RabbitMq Server. Die Konfiguration erfolgt in der Section RabbitMq. Ist RabbitMq auf dem gleichen Server wie der Audit-Server installiert und verwendet die Standard-Ports, muss lediglich ein Benutzer mit Admin-Rechten konfiguriert werden. Mit der einstellung MaxMessageConcurrency kann die konfiguriert werden, wie viele Audit-Logs eine Server-Instanz gleichzeitig verarbeiten kann. Der Wert sollte nach folgender Formel berechnet und konfiguriert werden: MaxDatenbankVerbindungen * 0.8 / AnzahlAuditServerInstanzen. Unterstützt die Datenbank 1000 gleichzeitige Client-Verbindungen und es sind 2 Audit-Server-Instanzen im einsatzt, ergibt dies 1000 * 0.8 / 2 = 400.

Wird RabbitMq als Cluster betrieben, könnenden mehrere Cluster-Nodes in der Liste Nodes konfiguriert werden.

Audit-Einstellungen

In der Section AuditServer befinden sich einige globale Einstellungen für den Audit-Server.

Name Erforderlich Beschreibung
HashingSecret Ja Das Secret das zum Signieren von Audit-Logs verwendet wird. Dieses darf nicht mehr geändert werden, da sonst die Validierung von bestehenden Einträgen fehlschlägt.
MaxExportCount Nein Die maximale Anzahl Audit-Logs die in einem einzigen Export exportiert werden können. Standard: 5'000'000
CleanupJobsRunTime Nein Ausführungszeit der Cleanup-Jobs. Standard: 05:00 Uhr.
TenantCleanup:Enabled Nein Ob nicht mehr konfigurierte Tenants nach der DeleteTenantsAfter Zeitspanne aus der Datenbank gelöscht werden sollen (inkl. Audit-Logs des Tenant). Standardmässig deaktiviert.
TenantCleanup:DeleteTenantsAfter Nein Zeitspanne nach welcher nicht mehr konfigurierte Tenants aus der Datenbank gelöscht werden (sofern aktiviert). Standard: 180 Tage.

Tenant-Konfiguration

Mandanten können über die Section Tenants konfiguriert werden. Der Key entspricht der TenantID. Folgende Einstellungen stehen zur Verfügung:

Name Erforderlich Beschreibung
ServiceBusConfig:SecretHash Nein RabbitMq Password Hash, das in RabbitMq für den User des CMI Servers konfiguriert wird. Wird kein Wert eingetragen, erstellt der Server einen User ohne Passwort. Das Passwort kann anschliessend im RabbitMq-Management für den User gesetzt werden.
Authentication:StsUri Ja STS3-Identity FQDN für den Mandanten.
Authentication:AuthorizedStsUserIds Ja Liste von CMI User die zugriff auf den Audit-Server erhalten sollen. Enthält die Liste einen Eintrag mit dem Wert "*" sind alle Benutzer mit einem gültigen STS Token zugelassen.
Authentication:UserIdentityClaim Nein STS-Token-Claim der zur Authorisierung eines Users verwendet wird. Standard: user_id.
AuditCleanup:Enabled Nein Löscht Audit-Logs wenn diese älter als die konfigurierte Zeitspanne sind. Standardmässig deaktiviert.
AuditCleanup:AuditLogRetentionPeriod Nein Zeitspanne nach welcher Audit-Logs gelöscht werden (sofern aktiviert). Standard nach 180 Tagen.

RabbitMQ CMI Server User

Der Audit-Server erstellt für jeden konfigurierten Mandanten einen User in RabbitMQ mit entsprechenden Berechtigungen auf die Exchange und Queue des Tenants. Der Name des Users hat das Format cmi-<tenant_id>. Der User kann für den CMI Server zur authentifizierung an RabbitMQ verwendet werden. Das Passwort des Users kann durch eine der beiden Methoden konfiguriert werden:

Provisionierung durch Audit-Server

Mit dem folgenden Befehl kann ein Hash für ein Passwort erstellt werden, welches anschliessend in der Tenant-Konfiguration ServiceBusConfig:SecretHash eingetragen werden muss:

.\CMI.AuditServer.Api.exe cli generate-rabbitmq-password-hash "<your_password>"

Der Audit-Server hinterlegt den Passwort-Hash anschliessend automatisch im RabbitMQ-User.

Manuelle Konfiguration über RabbitMQ Management

Das Passwort kann in der Management-UI des RabbitMQ-Servers manuell für den User konfiguriert werden:

  1. Öffnen Sie das Management-Portal des RabbitMQ-Servers.
  2. Melden Sie sich mit einem Administrator-Account an.
  3. Wechseln Sie in den Admin Bereich.
  4. Suchen Sie den entsprechenden User cmi-<tenant_id>.
  5. Setzen Sie unter Update this user ein neues Passwort.

Konfiguration des CMI Servers

Befolgen Sie die nachfolgenden Schritte, um den Audit-Server im CMI zu konfigurieren:

  1. Melden Sie sich mit einem User mit Administrator-Rechten (Built-in Administrator kann nicht verwendet werden) am CMI an.
  2. Stellen Sie sicher, dass der CMI-Server über die AUDIT-Lizenz verfügt.
  3. Wenn Sie von der Audit-Server Version >3.0.0 aktualisieren, löschen Sie den geplanten Task zum Senden der Logs an den Audit-Server. Send_Audit.png
  4. Öffnen Sie die Systemeinstellungen und gehen Sie zu Audit Log.
  5. Konfigurieren Sie die folgenden Einstellungen:
  6. URL: Wird ab Version 3.0.0 nicht mehr benötigt, tragen Sie als Platzhalter eine beliebige URL ein.
  7. Security Token: Wird ebenfalls ab Version 3.0.0 nicht mehr benötigt, tragen Sie einen beliebigen Text ein.
  8. Kurzname Gekobereich: Den Gekobereich des Servers.
  9. RabbitMqConnection:Port: Den AMQP Port des RabbitMq Servers.
  10. RabbitMqConnection:Benutzer-ID: Den RabbitMq Benutzer cmi-<tenant-id>
  11. RabbitMqConnection:Password: Passwort des RabbitMq Benutzers.
  12. RabbitMqConnection:Queue: Name der RabbitMq Queue cmi-<tenant-id>
  13. RabbitMqConnection:Exchange: Name der RabbitMq Exchange cmi-<tenant-id>

CMI_Server_Config.png

Befindet sich der Audit-Server nicht auf dem gleichen Server wie RabbitMq, muss der Hostname des RabbitMq Servers eingetragen werden:

RabbitMq_Hostname.png