Konfiguration¶
In diesem Kapitel erfährst du, wie du den Assistant Client korrekt einrichtest. Wie bei allen unseren Produkten erfolgt die Konfiguration über unser zentrales Konfigurationssystem. Allgemeine Informationen zur Struktur, zum Speicherort und zur Funktionsweise von Konfigurationsdateien findest du im Kapitel Konfigurationssystem.
Für den Betrieb benötigt der Assistant Client in der Regel zwei zentrale Module:
das
Application-Modul für die Hauptkonfiguration,und das
SSL-Modul zur Einrichtung verschlüsselter Verbindungen.
Optional empfehlen wir dir in Testumgebungen oder während der Ersteinrichtung zusätzlich das Log-Modul. Es hilft dir, Aufrufe, Fehler und Warnungen transparent nachzuvollziehen.
Ausführliche Anleitungen zur Konfiguration dieser Module findest du in den jeweiligen Kapiteln: Eigene SSL Zertifikate verwenden und Log-System.
Grundstruktur der Konfiguration¶
Die folgende XML-Datei zeigt eine typische Basiskonfiguration für das Assistant System:
1<?xml version="1.0" encoding="UTF-8" ?>
2<Configuration
3 version="1"
4 xmlns="http://educateit.ch/software/BlueStone/Configuration/1">
5
6 <Module name="Application">
7 <!-- Hauptkonfiguration des Assistant Clients -->
8 </Module>
9
10 <Module name="SSL">
11 <!-- SSL-Profile -->
12 </Module>
13
14</Configuration>
Das Application-Modul bildet das Herzstück deiner Konfiguration. Hier legst du alle grundlegenden Einstellungen für die Verbindung zum Assistant Server fest.
Das Konfigurationsschema¶
Module
Application
Must match this regular expression:
[-_:.a-z0-9]+
Must not be empty.
Must not be empty.
Must not be empty.
Der Parameter serverName¶
Mit dem Wert serverName legst du fest, zu welchem Host sich der AssistantClient.exe verbinden soll. Du kannst hier entweder den DNS-Namen oder die IP-Adresse des Zielservers eintragen.
Falls nötig, lässt sich dieser Wert zur Laufzeit über die Kommandozeilenoption --server-name überschreiben.
1<Module name="Application">
2 <Value name="serverName">example01</Value>
3 <Value name="sslProfile">client</Value>
4 <Value name="apiKey">3!2(...).NKn</Value>
5 <Value name="apiSecret">◀PKEY▶RFp(...)</Value>
6</Module>
Der Parameter serverPort¶
Der optionale Parameter serverPort bestimmt den TCP-Port, über den sich der Client mit dem Server verbindet. Wenn du diesen Wert nicht angibst, verwendet der Client standardmäßig den Port 17644.
Du kannst den Port bei Bedarf anpassen – erlaubt sind alle Werte im Bereich von 1 bis 65535. Auch dieser Wert lässt sich zur Laufzeit per Kommandozeile mit --server-port überschreiben.
1<Module name="Application">
2 <Value name="serverName">example01</Value>
3 <Value name="serverPort">17644</Value>
4 ...
5</Module>
Der Parameter sslProfile¶
Mit dem Wert sslProfile legst du fest, welche SSL-Konfiguration für die Verbindung zum Server verwendet wird. Der hier angegebene Profilname muss im SSL-Modul unter dem Eintrag profiles definiert sein.
Wie du ein SSL-Profil korrekt erstellst und einrichtest, erfährst du im Kapitel Eigene SSL Zertifikate verwenden.
In besonderen Fällen kannst du den Wert auch auf legacy setzen – zum Beispiel bei einer Migration oder wenn du ältere Installationen unterstützen möchtest. In diesem Modus greift das System auf integrierte Zertifikate zurück, die mit früheren Versionen des Assistant-Systems kompatibel sind.
Warnung
Wir raten dir jedoch dringend davon ab, dauerhaft auf legacy zu setzen. Verwende stattdessen eigene Zertifikate und private Schlüssel, die den tatsächlichen Servernamen enthalten und idealerweise von einer internen Zertifizierungsstelle deines Unternehmens ausgestellt wurden. Damit stellst du sicher, dass deine Verbindung nicht nur verschlüsselt, sondern auch zuverlässig authentifiziert ist.
1<Module name="Application">
2 <Value name="serverName">example01</Value>
3 <Value name="sslProfile">client</Value>
4 ...
5</Module>
Der Parameter apiKey¶
Mit dem Parameter apiKey gibst du den Bezeichner für die Verbindung zum Assistant Server an – vergleichbar mit einem Benutzernamen. Zusammen mit dem zugehörigen apiSecret (dem Passwort) authentifiziert sich dein Client eindeutig und sicher.
Das Schlüssel-Paar erzeugst du mit dem integrierten Secret Generator. Eine Schritt-für-Schritt-Anleitung findest du im Kapitel Das Secret System.
Zusätzliche Hinweise zum Schutz deiner Schlüssel und zur sicheren Systemkonfiguration findest du im Kapitel Sicherheit und Datenschutz.
1<Module name="Application">
2 <Value name="serverName">example01</Value>
3 <Value name="sslProfile">client</Value>
4 <Value name="apiKey">3!2(...).NKn</Value>
5 <Value name="apiSecret">◀PKEY▶RFp(...)</Value>
6</Module>
Der Parameter apiSecret¶
Der Parameter apiSecret ist das geheime Gegenstück zum apiKey – vergleichbar mit einem Passwort. Gemeinsam bilden beide Werte die Zugangsdaten für die Verbindung zum Assistant Server.
Dieser Wert ist zwingend erforderlich und darf auf keinen Fall leer sein.
Stelle sicher, dass du das apiSecret vertraulich behandelst – insbesondere dann, wenn du Konfigurationsdateien auf mehreren Clients verteilst. Mehr dazu, wie du Passwörter und Secrets in der Konfiguration schützen kannst, findest du im Kapitel Sicherheit und Datenschutz.
1<Module name="Application">
2 <Value name="serverName">example01</Value>
3 <Value name="sslProfile">client</Value>
4 <Value name="apiKey">3!2(...).NKn</Value>
5 <Value name="apiSecret">◀PKEY▶RFp(...)</Value>
6</Module>
Beispielkonfiguration¶
1<?xml version="1.0" encoding="UTF-8" ?>
2<Configuration
3 version="1"
4 xmlns="http://educateit.ch/software/BlueStone/Configuration/1">
5
6 <Module name="Application">
7 <Value name="serverName">example01</Value>
8 <Value name="sslProfile">client</Value>
9 <Value name="apiKey">3!2(...).NKn</Value>
10 <Value name="apiSecret">◀PKEY▶RFp(...)</Value>
11 </Module>
12
13 <Module name="SSL">
14 <List name="profiles">
15 <ListEntry>
16 <Value name="identifier">client</Value>
17 <Value name="key">●thisDirectory●/client.key</Value>
18 <Value name="keyAlgorithm">RSA</Value>
19 <Value name="caCertificates">●thisDirectory●/ca.crt</Value>
20 <Value name="localCertificateChain">●thisDirectory●/client.crt</Value>
21 <Value name="peerVerificationEnabled">Yes</Value>
22 <Value name="ignoreHostNameMismatch">Yes</Value>
23 </ListEntry>
24 </List>
25 </Module>
26
27</Configuration>
