Client konfigurieren

Bevor du den Client das erste Mal startest, musst du auch ihn korrekt konfigurieren. Öffne dazu die Datei configuration.xml im Verzeichnis, in dem du den Client vorbereitet hast, und ersetze den Inhalt durch folgende Konfiguration:

<?xml version="1.0" encoding="UTF-8" ?>
<Configuration
        version="1"
        xmlns="http://educateit.ch/software/BlueStone/Configuration/1">

    <Module name="Application">
        <Value name="serverName">127.0.0.1</Value>
        <Value name="sslProfile">client</Value>
        <Value name="apiKey">[Dein Schlüssel]</Value>
        <Value name="apiSecret">[Dein Secret]</Value>
    </Module>

    <Module name="SSL">
        <List name="profiles">
            <ListEntry>
                <Value name="identifier">client</Value>
                <Value name="key">●thisDirectory●/client.key</Value>
                <Value name="keyAlgorithm">RSA</Value>
                <Value name="caCertificates">●thisDirectory●/ca.crt</Value>
                <Value name="localCertificateChain">●thisDirectory●/client.crt</Value>
                <Value name="peerVerificationEnabled">Yes</Value>
                <Value name="ignoreHostNameMismatch">Yes</Value>
            </ListEntry>
        </List>
    </Module>

    <Module name="Log">
        <List name="FileWriter">
            <ListEntry>
                <Value name="LogFilePath">C:/Test/Logs/AssistantClient.log</Value>
                <Value name="LevelFilter">Trace</Value>
                <Value name="Rotation">Daily</Value>
            </ListEntry>
        </List>
    </Module>

</Configuration>

Diese Vorlage enthält bereits eine vollständige Minimal-Konfiguration für den lokalen Testbetrieb. Du kannst sie direkt übernehmen und an deine Umgebung anpassen.

Im nächsten Schritt schauen wir uns die einzelnen Bereiche dieser Konfiguration im Detail an.

SSL-Konfiguration

Die Konfiguration des Moduls SSL entspricht weitgehend derjenigen, die du bereits auf der Serverseite vorgenommen hast. Der einzige Unterschied: Hier verwendest du die Schlüssel und Zertifikate des Clients – nicht die des Servers.

<Module name="SSL">
    <List name="profiles">
        <ListEntry>
            <Value name="identifier">client</Value>
            <Value name="key">●thisDirectory●/client.key</Value>
            <Value name="keyAlgorithm">RSA</Value>
            <Value name="caCertificates">●thisDirectory●/ca.crt</Value>
            <Value name="localCertificateChain">●thisDirectory●/client.crt</Value>
            <Value name="peerVerificationEnabled">Yes</Value>
            <Value name="ignoreHostNameMismatch">Yes</Value>
        </ListEntry>
    </List>
</Module>
Erklärung der einzelnen Werte

In dieser Konfiguration gibst du die Pfade zu den zuvor erstellten Schlüsseln und Zertifikaten an. Der Platzhalter ●thisDirectory● verweist dabei auf das Verzeichnis, in dem sich die Konfigurationsdatei befindet.

  • profiles
    → Liste definierter SSL-Profile. Du kannst hier auch mehrere Profile parallel konfigurieren.
  • identifier
    → Eindeutiger Bezeichner für das Profil. Er wird verwendet, um das Profil in anderen Modulen zu referenzieren.
  • key
    → Pfad zur Datei mit dem privaten Schlüssel im PEM-Format – passend zum Zertifikat.
  • keyAlgorithm
    → Der verwendete Algorithmus des Schlüssels, z. B. RSA. Nur erforderlich, wenn er nicht automatisch erkannt wird.
  • caCertificates
    → Pfad zu einer Datei mit CA-Zertifikaten im PEM-Format. Diese werden verwendet, um das Gegenüber zu überprüfen. Wenn nicht gesetzt, werden systemweite CAs verwendet.
  • localCertificateChain
    → Zertifikatskette des Clients im PEM-Format. Das eigentliche Zertifikat steht an erster Stelle, gefolgt von optionalen Zwischenzertifikaten.
  • peerVerificationEnabled
    → Legt fest, ob das Zertifikat der Gegenseite überprüft wird. Yes ist empfohlen und Standard.
  • ignoreHostNameMismatch
    → Bei Yes wird der Hostname im Zertifikat nicht geprüft. In produktiven Umgebungen mit korrekten Zertifikaten solltest du hier No setzen.

Weitere Details zu allen SSL-Optionen findest du im Kapitel Eigene SSL Zertifikate verwenden.

Logging-Konfiguration

In einer produktiven Umgebung ist es meist nicht nötig, eine eigene Logdatei für den Client zu definieren – dort wird typischerweise ein zentrales Logging verwendet.

Für unser Testsystem sind Logeinträge jedoch sehr hilfreich. Deshalb richten wir hier eine einfache Konfiguration ein, ähnlich wie auf der Serverseite. Achte dabei darauf, dass der in der Konfiguration angegebene Pfad tatsächlich auf ein beschreibbares Verzeichnis zeigt.

1<Module name="Log">
2    <List name="FileWriter">
3        <ListEntry>
4            <Value name="LogFilePath">C:/Test/Logs/AssistantServer.log</Value>
5            <Value name="LevelFilter">Trace</Value>
6            <Value name="Rotation">Daily</Value>
7        </ListEntry>
8    </List>
9</Module>
Erklärung der einzelnen Werte
  • FileWriter
    → Hier legst du fest, welche Logdateien geschrieben werden sollen. Du kannst mehrere Einträge definieren, z. B. für unterschiedliche Log-Level oder Zielpfade.
  • LogFilePath
    → Pfad und Dateiname der Logdatei. Stelle sicher, dass dieser Ort auf deinem System existiert und beschreibbar ist.
  • LevelFilter
    → Bestimmt, welche Logeinträge gespeichert werden. Mit Trace erhältst du die detaillierteste Ausgabe – ideal für Test- und Debugzwecke.
  • Rotation
    → Steuert, wann neue Logdateien erstellt werden. Mit dem Wert Daily beginnt das System jeden Tag eine neue Datei.

Weitere Optionen findest du im Kapitel Log-System.

Anwendungskonfiguration

Auch beim Assistant-Client übernimmt das Modul Application die zentrale Konfiguration der Anwendung.

1<Module name="Application">
2    <Value name="serverName">127.0.0.1</Value>
3    <Value name="sslProfile">client</Value>
4    <Value name="apiKey">[Dein Schlüssel]</Value>
5    <Value name="apiSecret">[Dein Secret]</Value>
6</Module>

Mit serverName gibst du die IP-Adresse oder den Hostnamen des Systems an, auf dem der Assistant-Server läuft. In unserem Beispiel verwenden wir 127.0.0.1, da wir davon ausgehen, dass Server und Client auf demselben System installiert sind. Falls deine Testumgebung anders aufgebaut ist, trage hier bitte die entsprechende IP-Adresse oder den Hostnamen deines Servers ein.

Mit dem Wert client bei sslProfile wird das gleichnamige SSL-Profil verwendet, das du weiter unten in der Konfigurationsdatei definiert hast. Dieses Profil wird für alle Verbindungen zum Server genutzt.

Du solltest jetzt noch das Fenster der Anwendung Secret-Generator geöffnet haben. Kopiere daraus den Client-Schlüssel sowie das Client-Secret und ersetze damit die Platzhalter [Dein Schlüssel] und [Dein Secret].

../../../_images/secret-generator-client.jpg

Im rot markierten Bereich des Screenshots findest du bereits den vollständigen XML-Text, den du direkt in deine Konfigurationsdatei übernehmen kannst. Das ist meist schneller und weniger fehleranfällig, als die Werte einzeln zu kopieren.

Bitte beachte: In manchen Konfigurationen können die Namen der Parameter abweichen – also zum Beispiel nicht apiKey und apiSecret heißen. In unserem Beispiel passt jedoch alles, du kannst die Werte direkt übernehmen.

Wichtig

In der Testumgebung ist das Secret des Clients absichtlich im Klartext gespeichert, um die Einrichtung zu vereinfachen. Für den produktiven Einsatz musst du die Konfiguration jedoch unbedingt absichern.

Wie du Passwörter und Secrets richtig schützt, erfährst du im Kapitel Sicherheit und Datenschutz.

Sicherheit und Datenschutz

Lies weiter: Client starten →