Konfiguration (Connect 2021)
Inhalt
- 1 Inhalt
- 2 Allgemein
- 3 Standardkonfiguration
- 4 Installationsspezifische Konfiguration
- 5 Umgebungsspezifische Konfiguration
- 6 Explizite Konfiguration
- 7 Struktur der Konfigurationsdatei
- 7.1 Der Abschnitt „Logging“ (JSON Objekt)
- 7.2 Der Abschnitt „IdentityServer“ (JSON Objekt)
- 7.3 Der Abschnitt „AllowedHosts“ (JSON Wert vom Typ String)
- 7.4 Der Abschnitt „Connect“ (JSON Objekt)
- 7.5 Der Abschnitt „Connect/Server“ (JSON Objekt)
- 7.5.1 Der Abschnitt „BaseUri“ (JSON Wert vom Typ String)
- 7.5.2 Der Abschnitt „Debug“ (JSON Objekt)
- 7.5.3 Der Abschnitt „Passwords“ (JSON Objekt)
- 7.5.4 Der Abschnitt „Paths“ (JSON Objekt)
- 7.5.5 Der Abschnitt „Database“ (JSON Objekt)
- 7.5.6 Der Abschnitt „SupportedLanguages“ (JSON Array mit Werten vom Typ String)
- 7.5.7 Der Abschnitt “Webserver“ (JSON Objekt)
- 7.6 Besonderheiten bei der Konfiguration des Identity Servers
- 7.7 Beispielkonfiguration
- 8 Übersteuerung von Konfigurationseinstellungen
Allgemein
Die Konfiguration des Connect Servers erfolgt in der Regel mit Hilfe von JSON-Dateien, welche sich im Installationsverzeichnis der Applikation befinden. In Spezialfällen ist eine Übersteuerung über Umgebungsvariablen oder über Kommandozeilenparameter möglich.
Standardkonfiguration
Die Standardkonfiguration befindet sich in der Datei “appsettings.Default.json”. Diese Datei sollte nicht direkt verändert werden, da diese Änderungen ggf. durch ein späteres Upgrade überschrieben werden.
Installationsspezifische Konfiguration
Soll eine installationsspezifische Konfiguration angelegt werden, so empfiehlt es sich die Datei „appsettings.Default.json“ in eine Datei mit dem Namen “appsettings.json” zu kopieren. Diese Datei wird bei einem eventuellen Upgrade nicht überschrieben, somit bleiben die hier hinterlegten Konfigurationseinstellungen bestehen.
Die Standardkonfiguration wird hierbei weiterhin berücksichtigt. Die installationsspezifische Konfiguration muss daher nur die gewünschten Deltas enthalten.
Umgebungsspezifische Konfiguration
Wird ein Installationsverzeichnis in verschiedenen Umgebungen genutzt (z. B. in einem Template für Container), so können umgebungsspezifische Konfigurationen angelegt werden. Hierfür wird die Datei „appsettings.Default.json“ in eine Datei mit dem Namen “appsettings.{environment}.json” kopiert ({environment} ist hierbei durch den Namen der entsprechenden Umgebung zu ersetzen).
In diesem Szenario kann die Umgebung zur Laufzeit mit Hilfe der Umgebungsvariablen “ASPNETCORE_ENVIRONMENT” spezifiziert werden. In der Regel werden hier die Werte “Development”, “Staging” und “Production” verwendet, der Standardwert ist “Production”.
Die Standardkonfiguration sowie ein evtl. vorhandene installationsspezifische Konfiguration werden weiterhin berücksichtigt. Die umgebungsspezifischen Konfigurationen müssen daher nur die gewünschten Deltas enthalten.
Die Verwendung der Umgebung “Development” sollte in Produktionsumgebungen vermieden werden, da hierbei zusätzliche Debugging-Funktionalitäten aktiviert werden.
Explizite Konfiguration
Bei Bedarf können in der Kommandozeile über das Argument “settings=…”, “-settings=…”, “—settings=…” oder “/settings=…” zusätzliche Konfigurationsdateien angegeben werden. Hierbei wird geprüft, ob die angegebene Konfigurationsdatei vorhanden ist und gegebenenfalls eine Fehlermeldung ausgegeben. Diese Prüfung kann deaktiviert werden, indem an den Dateinamen ein Fragezeichen angehängt wird. Dadurch lassen sich auch optionale Konfigurationsdateien in der Kommandozeile spezifizieren.
Die Standardkonfiguration sowie die installationsspezifische Konfiguration und die umgebungsspezifische(n) Konfiguration(en) werden weiterhin berücksichtigt. Die expliziten Konfigurationen müssen in diesem Fall nur die gewünschten Deltas enthalten.
Struktur der Konfigurationsdatei
Die Konfigurationsdatei für den Connect Server ist eine JSON Datei mit eine JSON Objekt als Wurzelelement. Die entsprechenden untergeordneten Elemente werden in den folgenden Kapiteln beschrieben.
Der Abschnitt „Logging“ (JSON Objekt)
Dieser Abschnitt enthält ein weiteres JSON Objekte mit dem Namen “LogLevel”, welches den Detailgrad der Protokollausgaben festlegt. Hierbei enthält die Eigenschaft “Default” die Standardeinstellung, weitere vorhandene Eigenschaften definieren ggf. abweichende Einstellungen für bestimmte .NET Namensräume. Für den Detailgrad werden folgende die Werte “Trace”, “Debug”, “Information”, “Warning” und “Error” unterstützt.
Beispiel:
...
"Logging": {
"LogLevel": {
"Default": "Information",
"IdentityServer4": "Warning",
"Microsoft": "Warning",
"Microsoft.Hosting.Lifetime": "Information"
}
},
...Bei Bedarf kann der Detailgrad in Abhängigkeit vom Protokollierungsziel (Konsole, Event Log, etc.) spezifiziert werden. Weitergehende Informationen finden sie unter folgendem Link:
Der Abschnitt „IdentityServer“ (JSON Objekt)
Dieser Abschnitt Konfigurationen für den im Connect Server integrierten Identity Server. Dieser ist für die Authentifizierung der Benutzer zuständig. Die Standardkonfiguration ist für Entwicklungsumgebungen oder für abgeschlossene Netzwerke sinnvoll, da sie keinerlei weitergehende Einstellungen benötigt. Soll der Connect Server jedoch über das Internet erreichbar sein, so sollten diese Einstellungen unbedingt angepasst werden. Weitere Informationen hierzu finden Sie unter folgendem Link:
Beispiel:
...
"IdentityServer": {
"Key": {
"Type": "Development"
},
"Clients": {
"GalileoGroup.Connect.Server.Frontend": {
"Profile": "IdentityServerSPA"
}
}
},
...Der Abschnitt „AllowedHosts“ (JSON Wert vom Typ String)
Dieser Abschnitt erlaubt die Einschränkung der Host-Namen, an welche der Webserver gebunden werden kann. Somit lässt sich der Zugriff über unerwünschte Hostnamen oder über IP-Adressen verhindern. Mehrere Werte können durch ein Semikolon getrennt werden. Weitere Informationen finden Sie unter folgendem Link:
Beispiel:
...
"AllowedHosts": "connect.mycompany.com;localhost",
...Der Abschnitt „Connect“ (JSON Objekt)
Dieser Abschnitt fasst sämtliche Connect Framework spezifischen Konfigurationen zusammen.
Der Abschnitt „Connect/Server“ (JSON Objekt)
Dieser Abschnitt enthält alle Einstellungen im Zusammenhang mit den integrierten Serverfunktionalitäten.
Der Abschnitt „BaseUri“ (JSON Wert vom Typ String)
Dieser Wert gib die Basis URI an, unter welcher der Connect Server von extern erreichbar ist. Die hier angegebene URI muss nicht zwangsläufig einem Endpoint der Webservers entsprechen, es kann sich auch um eine von extern erreichbare URI handeln, welche durch einen Router auf einen der Endpoints des Webservers weitergeleitet wird.
Wird dieser Wert auf “auto” gesetzt, so versucht der Server die Basis URI aus den Daten des ersten Webserver Endpoints automatisch zu ermitteln.
Der Abschnitt „Debug“ (JSON Objekt)
Dieser Abschnitt enthält Einstellungen zur Fehleranalyse. Derzeit werden folgende Einstellungen unterstützt:
Eigenschaft | Typ | Funktion |
EnableHttpRequestLogging | Boolean | Aktiviert die Protokollierung aller eingehenden http-Anfragen. |
Der Abschnitt „Passwords“ (JSON Objekt)
Dieser Abschnitt hat in der aktuellen Version des Connect Servers noch keine Funktionalität. In Zukünftigen Versionen können hier die Parameter für eine reversible Verschlüsselung der Passwörter für SSL-Zertifikate und Verbindungszeichenfolgen definiert werden, so dass diese nicht mehr im Klartext hinterlegt werden müssen.
Der Abschnitt „Paths“ (JSON Objekt)
In diesem Abschnitt können Variablen für die Benutzung in Dateipfaden definiert werden. Nachfolgende Variablen können bereits zuvor definierte Variablen verwenden. Unabhängig vom Betriebssystem muss stets das Zeichen „/“ als Trennzeichen zwischen Verzeichnissen verwendet werden.
Folgende Variablen sind vom Connect Framework vordefiniert, können jedoch redefiniert werden:
Variable | Standardwert |
ApplicationPath | Das Installationsverzeichnis des Connect Servers. |
CertificatePath | {ApplicationPath}/Certificates |
RepositoryPath | {ApplicationPath}/Repositories |
Diese Voreinstellungen werden immer dann verwendet, wenn kein anderer Variablenwert definiert oder wenn der Variable der Wert „auto“ zugewiesen wurde.
Zur Verwendung innerhalb eines Dateipfads müssen die Pfadvariablen in geschweifte Klammern gesetzt werden.
Der Abschnitt „Database“ (JSON Objekt)
Dieser Abschnitt enthält Konfigurationsdaten für die Verbindung zu den von der Applikation verwendeten Datenbanken. Für jede Datenbank muss ein untergeordnetes JSON Objekt angelegt werden, dessen Name der internen ID der zugehörigen Datenbank entspricht. Der Connect Server verwendet im Moment folgende Datenbanken:
Datenbank ID | Funktion |
Identity | Benutzer und Berechtigungen des Identity Servers |
Monitoring | Datenbank zur Sammlung von Monitoring-Daten |
Operations | Datenbank zur Speicherung von Ablaufdaten |
Für jede Datenbank können die folgenden Informationen hinterlegt werden:
Eigenschaft | Typ | Funktion |
Type | String | Typ der Datenbank. Normalerweise wird hier “Sqlite” verwendet, ”SqlServer” wird aktuell experimentell unterstützt. Eine Unterstützung für “MySql” ist in Planung, derzeit ist jedoch die finale Implementierung der EF Core Adapter für .NET 5.0 noch nicht verfügbar. |
ConnectionString | String | Die Verbindungszeichenfolge für die zu verwendete Datenbank. |
LogLevel | String | Der gewünschte Detailgrad für Datenbank-spezifische Protokollausgaben. Es werden die Werte “Trace”, “Debug”, “Information”, “Warning” und “Error” unterstützt. |
EnableSensitiveDataLogging | Boolean | Wird dieser Wert auf “true” gesetzt, so werden bei der Protokollierung auch Feldinhalte mit ausgegeben, andernfalls werden diese stets unterdrückt. |
EnableDetailedErrors | Boolean | Wird dieser Wert auf “true” gesetzt, so werden bei der Protokollierung detaillierte Fehlermeldungen der Datenbank ausgegeben. |
Der Abschnitt “RetentionPeriods” (JSON Objekt)
Für die Operations-Datenbank können zusätzlich Aufbewahrungszeiträume für Workflow-Kontexte definiert werden. Die Zeiträume werden in einem separaten Abschnitt “RetentionPeriods” definiert und können folgende Informationen enthalten.
Eigenschaft | Typ | Funktion |
|---|---|---|
OpenContexts | Number | Aufbewahrungszeitraum für nicht abgeschlossene Transaktionen in Tagen. |
CompletedContexts | Number | Aufbewahrungszeitraum für abgeschlossene Transaktionen in Tagen. |
Beispiel:
Der Abschnitt „SupportedLanguages“ (JSON Array mit Werten vom Typ String)
Dieser Abschnitt definiert die im Dialog zur Pflege von Sprachabhängigen Texte auswählbaren Sprachen. Hierbei werden sowohl generische Sprachschlüssel (wie “en” oder “de”) als auch gebietsspezifische Sprachschlüssel (wie “en-US”, “en-UK”, “de-DE” oder “de-AT”) unterstützt.
Der Abschnitt “Webserver“ (JSON Objekt)
Dieser Abschnitt dient zur Konfiguration des integrierten Webservers. Hier können folgende Werte hinterlegt werden:
Eigenschaft | Typ | Funktion |
Type | String | Um den integrierten Webserver zu verwenden, sollte hier der Wert “Kestrel” stehen. Da es sich hierbei um die Standradeinstellung handelt, wird auch beim Fehlen dieser Eigenschaft der Wert “Kestrel” angenommen. Unter Windows kann auch der Wert “IIS” verwendet werden. In diesem Fall wird der Modus für das Hosting innerhalb eines IIS aktiviert. Die hier konfigurierten Endpoints haben im IIS Modus keine Funktionalität, da diese über die Bindings im IIS definiert werden. Weiter Informationen zum Thema Hosting im IIS finden Sie unter folgendem Link: |
RootPath | String | Spezifiziert das Root-Verzeichnis des Webservers. Es wird empfohlen diesen Wert nicht zu ändern, da dies zu Seiteneffekten beim Hosting des WebAssembly basierten Frontends führen kann. |
Endpoints | Array | Dieses Array von JSON Objekten spezifiziert die Endpoints des integrierten Webservers. Die Eigenschaft “Uri” enthält die URI des gewünschten Endpoints. Schema und Host werden zwingend benötigt, die Angabe eines Ports ist optional. Ist kein Port angegeben, so werden die jeweiligen Standard-Ports (80 bei HTTP und 443 bei HTTPS) verwendet. Wird als Host keine IP-Adresse angegeben, so wird der angegebene Name mittels DNS Lockup in eine IP-Adresse umgewandelt. Die IP-Adressen 0.0.0.0 oder * stehen für alle verfügbaren IP-Adressen des Servers. Bei der Verwendung von HTTPS muss zusätzlich die Eigenschaft “CertificateSource” angegeben werden, welche unterschiedliche Werte annehmen kann. Welcher Wert angegeben werden muss wird dadurch definiert, wo sich das Zertifikat befindet. Wenn sich das Zertifikat im Store befindet, muss der Wert dem Antragssteller entsprechen. Wenn z. B. der Antragssteller des Zertifikats “CN = localhost” lautet, muss der Wert für “CertificateSource” “localhost” lauten. Es kann auch der direkte Pfad zu einem Zertifikat bzw. dessen Dateiname angegeben werden. Wird nur ein Dateiname angegeben, so wird diese in dem durch die Pfadvariable “CertificatePath” definierten Pfad gesucht. Hierfür kann der Wert z.B. wie “test.cer|” oder “test.cer|NochEinPassword” aussehen. Hierbei ist “test.cer” ist der Dateiname des Zertifikats und “NochEinPassword” das Passwort für den Zugriff auf den privaten Schlüssel des Zertifikats. Das Trennzeichen “|” ist obligatorische, egal ob ein Password eingetragen wird oder nicht. Falls es kein Password gibt, endet der Wert mit einem “|”. Die Verwendung mehrerer Zertifikate am selben Endpoint wird derzeit nicht unterstützt. Ist ein Endpoint über verschiedene Hostnamen erreichbar, so müssen diese in einem Zertifikat aufgelistet sein. Wildcard-Zertifikate werden ohne Einschränkungen unterstützt. |
Besonderheiten bei der Konfiguration des Identity Servers
In der Standardkonfiguration verwendet der Connect Server den Identity Server zur Authentifizierung und Autorisierung der Benutzer. Hierbei gibt es eine Konfigurationsvariante, welche vom Standard abweicht:
Wird innerhalb des Abschnitts „Key“ ein Wert mit dem Namen „AutoCreate“ und dem Wert „true“ erstellt, so wird, sofern die referenzierte Zertifikatdatei nicht vorhanden ist, beim Start ein selbstsigniertes Zertifikat generiert. Dieses Verhalten dient im Wesentlichen dazu, das der Server ohne manuelle Eingriffe in die Konfiguration gestartet werden kann.
Beispiel:
Ist im unter “CertificatePath” spezifizierten Verzeichnis keine Datei mit dem Namen “connect.pfx” vorhanden, so wird bei Start ein selbstsigniertes Zertifikat erstellt und unter diesem Namen gespeichert. Für die Verschlüsselung des privaten Schlüssels wird das hier hinterlegte Passwort „Connect!“ verwendet.
Beispielkonfiguration
Das folgende Beispiel zeigt die möglichen Connect-spezifischen Konfigurationseinstellungen:
Übersteuerung von Konfigurationseinstellungen
Die in den JSON-Dateien hinterlegten Konfigurationseinstellungen können bei Bedarf übersteuert werden. Diese Vorgehensweise macht insbesondere bei der Automatisierung von Docker-basierten Umgebungen Sinn.
Übersteuerung mit Hilfe von Umgebungsvariablen
Um den Wert einer Konfigurationseinstellung zu übersteuern kann eine Umgebungsvariable mit dem Präfix “DOTNET_” oder “ASPNETCORE_” gefolgt vom Pfad der Einstellung in der JSON Datei definiert werden. Als Pfadtrennzeichen sollte hier ein doppelter Underscore (__) verwendet werden.
Weitere Informationen zu diesem Thema finden Sie unter folgendem Link:
Beispiel:
Übersteuerung über die Kommandozeile
Bei Bedarf können Konfigurationen auch mit Hilfe von Schlüssel-Wert-Paaren als Kommandozeilenparameter übersteuert werden. Der Name entspricht hierbei dem Pfad der Einstellung, wobei das Zeichen „:“ als Pfadtrennzeichen verwendet wird. Die Angabe von Schlüssel-Wert-Paaren kann auf verschiedene Art und Weisen erfolgen:
<name1>=<wert1> <name2>=<wert2> …/<name1> <wert1> /<name2> <wert2> …--<name1> <wert1> --<name2> <wert2> …
Weitere Informationen zu diesem Thema finden Sie unter folgendem Link:
Beispiel: