From 999b4d73161981d4a368968796dd1543a03e28d2 Mon Sep 17 00:00:00 2001 From: Thomas Lenz Date: Thu, 20 Feb 2014 17:19:21 +0100 Subject: add inital version of MOA-ID 2.0 handbook --- id/server/doc/handbook/install/install.html | 319 ++++++++++++++++++++++++++++ 1 file changed, 319 insertions(+) create mode 100644 id/server/doc/handbook/install/install.html (limited to 'id/server/doc/handbook/install/install.html') diff --git a/id/server/doc/handbook/install/install.html b/id/server/doc/handbook/install/install.html new file mode 100644 index 000000000..5a1f5f2fe --- /dev/null +++ b/id/server/doc/handbook/install/install.html @@ -0,0 +1,319 @@ + + + + + MOA SS und SP - Installation + + +< + + + + + + +
Logo BKADokumentationLogo EGIZ
+
+

MOA-ID (Identifikation)

+

Installation

+
+

Inhalt

+
    +
  1. +

    Übersicht

    +
    2. +
  2. +

    MOA-ID-Auth

    +
      +
    1. Basisinstallation +
        +
      1. Einführung
        2. +
      2. Installation +
          +
        1. Vorbereitung
          2. +
        2. Konfiguration von Apache Tomcat +
            +
          1. Konfiguration des HTTP Connectors
            2. +
          2. Konfiguration des HTTPS Connectors
            3. +
          +
          3. +
        3. Einsatz des Moduls MOA-ID-Auth in Tomcat
          4. +
        4. Einsatz des Moduls MOA-ID-Configuration in Tomcat
          5. +
        5. Starten und Stoppen von Tomcat +
            +
          1. Unter Windows
            2. +
          2. Unter Unix
            3. +
          3. Prüfen des erfolgreichen Starts
            4. +
          +
          6. +
        6. Änderung der Konfiguration im laufenden Betrieb
          7. +
        +
        3. +
      3. Logging +
          +
        1. Format der Log-Meldungen
          2. +
        2. Wichtige Log-Meldungen
          3. +
        +
        4. +
      +
      2. +
    2. Erweiterungsmöglichkeiten
        +
      1. Vorgeschalteter Webserver
          +
        1. Microsoft Internet Information Server (MS IIS)
            +
          1. Konfiguration von mod_jk im MS IIS
            2. +
          2. Konfiguration von Tomcat
            3. +
          3. Konfiguration von SSL
            4. +
          +
          2. +
        2. Apache
            +
          1. Konfiguration von mod_jk im Apache
            2. +
          2. Konfiguration von Tomcat
            3. +
          3. Konfiguration von SSL mit mod_SSL
            4. +
          +
          3. +
        +
        2. +
      +
      3. +
    +
+
    +
  1. Referenzierte Software
    2. +
+
+

1 Übersicht

+

Die Module MOA-ID-Auth und MOA-ID-Configuration sind als plattformunabhängige Module ausgelegt. MOA-ID-Auth bietet Webservices über HTTPS zur Identifizierung und Authentifizierung an. Das Modul MOA-ID-Configuration stellt eine Weboberfläche zur Konfiguration des MOA-ID-Auth Modules zur Verfügung.

+

Dieses Handbuch beschreibt die Installation der beiden Module.

+

2 MOA-ID-Auth

+

Dieser Abschnitt beschreibt die Installation von MOA SP/SS als Webservice. Im ersten Unterkapitel wird eine minimale Basisinstallation beschrieben. Das zweite Unterkapitel zeigt eine Reihe von optionalen Erweiterungsmöglichkeiten auf.

+

2.1 Basisinstallation

+

2.1.1 Einführung

+

Die Basisinstallation der Module MOA-ID-Auth und MOA-ID-Configuration stellt einerseits die minimalen Anforderungen für den Betrieb von MOA-ID dar, andererseits dient sie als Ausgangspunkt für optionale Erweiterungsmöglichkeiten.

+

Die Mindestanforderungen für die Basisinstallation sind:

+ +

Wir empfehlen jedoch jeweils aktuelle Version zu verwenden:

+ +

In diesem Betriebs-Szenario wird das MOA-ID-Auth Webservice und das MOA-ID Konfgurationstool in Tomcat zum Einsatz gebracht. Beide Module können sowohl in der selben Tomcat-Instanz, als auch in seperaten Tomcat-Instanzen betrieben werden. Für den Fall des seperation Betriebs muss die Installation auf beiden Tomcat-Instanzen ausgeführt werden. In beiden Fällen fungiert der Tomcat gleichzeitig als HTTP- und HTTPS-Endpunkt für beide Module. Beide Protokolle werden direkt in Tomcat konfiguriert, wobei MOA-ID-Auth und MOA-ID-Configuration Log4j als Logging Toolkit verwenden.

+

2.1.2 Installation

+

2.1.2.1 Vorbereitung

+

Die folgenden Schritte dienen der Vorbereitung der Installation.

+
+
Installation von Java SE
+
Installieren Sie Java SE in ein beliebiges Verzeichnis. Das Wurzelverzeichnis der Java SE Installation wird im weiteren Verlauf als $JAVA_HOME bezeichnet.
+
Installation von Apache Tomcat
+
Installieren Sie Apache Tomcat in ein Verzeichnis, das keine Leerzeichen im Pfadnamen enthält. Verwenden Sie bitte die zu Ihrer Java SE passende Distribution von Tomcat. Das Wurzelverzeichnis der Tomcat-Installation wird im weiteren Verlauf als $CATALINA_HOME bezeichnet.
+
Entpacken der MOA-ID-Auth Webservice Distribution
+
Entpacken Sie die Datei moa-id-auth-2.0.0.zip in ein beliebiges Verzeichnis. Dieses Verzeichnis wird im weiteren Verlauf als $MOA_ID_AUTH_INST bezeichnet.
+
Installation der Kryptographiebibliotheken von SIC/IAIK
+
+

Kopieren Sie alle Dateien aus dem Verzeichnis $MOA_SPSS_INST/ext in das Verzeichnis $JAVA_HOME/jre/lib/ext. Zusätzlich müssen Sie die Rechtedateien Ihrer Java SE austauschen. Laden Sie dazu die passenden Unlimited Strength + + + Jurisdiction Policy Files von der Java SE Downloadseite und achten Sie darauf die für ihre verwendete Java SE Installation richtige Version zu nehmen. Anschließend folgen Sie der darin enthaltenen Installationsanweisung.

+
+
Installation einer Datenbank
+
TODO: inmemory Database
+
+

 

+
+
+

2.1.2.2 Konfiguration von Apache Tomcat

+

Die zentrale Konfigurations-Datei von Tomcat ist $CATALINA_HOME/conf/server.xml. Tomcat wird grundsätzlich mit einer funktionierenden Default-Konfiguration ausgeliefert.

+
2.1.2.2.1 Konfiguration des HTTP Connectors
+

Die Tomcat Default-Konfiguration schaltet ausschließlich den Connector für HTTP auf Port 8080 frei. Wir empfehlen diese Konfiguration nur für Fälle, in denen das MOA-ID-Configuration Modul in einer abgeschlossenen Netzwerkumgebung betrieben wird. Das Modul MOA-ID-Auth verlangt für Authentifizierunganfragen zwingend HTTPS.

+
2.1.2.2.2 Konfiguration des HTTPS Connectors
+

Für den sicheren Betrieb von MOA-ID-AUTH ist die Verwendung von SSL Voraussetzung, sofern nicht ein vorgelagerter WebServer (Apache oder IIS) das SSL-Handling übernimmt. Ebenso kann SSL auch für MOA-ID-Configuration verwendet werden.

+

Für die dazu notwendige Konfiguration kann die im vorigen Abschnitt besprochene minimale Tomcat-Konfiguration als Ausgangspunkt verwendet werden: Zunächst ist der HTTP Connector abzuschalten (auszukommentieren). Anschließend ist der HTTPS Connector zu konfigurieren. Das Dokument Tomcat SSL Configuration HOW-TO gibt einen guten Überblick dazu. Grob zusammengefasst sind folgende Schritte durchzuführen:

+ +

Die Konfiguration des HTTPS Connectors kann entfallen, wenn Tomcat ein Webserver vorgeschaltet ist, und dieser die SSL-Kommunikation mit dem Kunden übernimmt (siehe Abschnitt 2.2.1).

+
2.1.2.3 Einsatz des Moduls MOA-ID-Auth in Tomcat
+

Um die Module MOA-ID-Auth und MOA-ID-Configuratuion in Tomcat für den Einsatz vorzubereiten, sind folgende Schritte notwendig:

+ +
2.1.2.4 Einsatz des Moduls MOA-ID-Configuration in Tomcat
+ +

2.1.2.4 Starten und Stoppen von Tomcat

+
2.1.2.4.1 Unter Windows
+
+

Das Verzeichnis $MOA_IA_AUTH_INST/tomcat/win32 enthält Script-Dateien zum Starten und Stoppen von Tomcat. Vor der erstmaligen Verwendung der Scripts müssen in den ersten Zeilen die Umgebungsvariablen JAVA_HOME (Basisverzeichnis der eingesetzten Java SE) und CATALINA_HOME (Basisverzeichnis der eingesetzten Tomcat-Installation) angepasst werden. Evtl. müssen Sie auch noch die in den Script-Dateien gesetzten, in Abschnitt 2.1.2.3 besprochenen System Properties anpassen.

+
+
2.1.2.4.2 Unter Unix
+

Zunächst müssen die in Abschnitt 2.1.2.3 besprochenen System Properties mit Hilfe der Umgebungsvariablen CATALINA_OPTS gesetzt sein. Die Datei $MOA_ID_AUTH_INST/tomcat/unix/moa-env.sh enthält ein Beispiel dafür. Weiters müssen noch die Umgebungsvariablen JAVA_HOME (Basisverzeichnis der eingesetzten Java SE) und CATALINA_HOME (Basisverzeichnis der eingesetzten Tomcat-Installation) angepasst werden.

+

Nun kann Tomcat aus seinem Basisverzeichnis mit

+
bin/catalina.sh start
+gestartet werden. Das Stoppen von Tomcat erfolgt analog mit +
bin/catalina.sh stop
+
2.1.2.4.3 Prüfen des erfolgreichen Starts
+
+

Ein erfolgreicher Start des MOA-ID-Auth Modules ist an folgender Log-Meldung ersichtlich:
+

+
+
32131 [localhost-startStop-1] INFO moa.id.auth  - MOA ID Authentisierung wurde erfolgreich gestartet 
+32131 [localhost-startStop-1] INFO moa.id.auth  - Dispatcher Servlet initialization finished.
+

Analog bei MOA-ID-Configuration

+

TODO:

+

Bei leichten Fehlern in der Konfiguration geben WARN Log-Meldungen unmittelbar davor Aufschluss über fehlerhafte Konfigurations-Einträge. + Nach dem Starten von Tomcat stehen MOA-ID-Auth und MOA-ID-Configuration zur Verfügung. Die Einsprungpunkte der unterschiedlichen Authentifizierungsprotokolle von MOA-ID-Auth werden im Abschnitt Protokolle im Detail beschrieben.

+
+http://<host>:<port>/moa-id-auth/
+http://<host>:<port>/moa-id-configuration/
+

bzw. +

+
+https://<host>:<port>/moa-id-auth/
+https://<host>:<port>/moa-id-configuration/
+

Die Verfügbarkeit des Services können Sie einfach überprüfen, indem Sie die Endpunkte mit einem Web-Browser aufgerufen; dies sollte nach erfolgreichem Start zur Anzeige einer Informationsseite führen.

+

2.1.3 Logging

+

Beide Module verwenden Log4j für die Ausgabe von Log-Meldungen am Bildschirm bzw. in Log-Dateien. Log4j bietet zahlreiche Konfigurationsmöglichkeiten, die ausführlich im Log4j Handbuch beschrieben sind. Unter anderem gibt es die Möglichkeit, folgende Einstellungen vorzunehmen: +

+

Hierbei wird folgende Log-Hierarchien verwendet:

+ +

Eine für beide Module passende Konfigurationsdatei für Log4j finden Sie hier. Wird diese Datei als Logging-Konfiguration verwendet, so werden alle Log-Meldungen sowohl in die Konsole, als auch in die Dateien moa-id-auth.log und moa-id-configuration.log geschrieben.

+

2.1.3.1 Format der Log-Meldungen

+

Anhand einer konkreten Log-Meldung wird das Format der MOA SP/SS Log-Meldungen erläutert:

+

TODO:

+ 
+INFO | 01 21:25:26,540 | Thread-3 | TID=1049225059594-100 NID=node1 
+  MSG=Starte neue Transaktion: TID=1049225059594-100, Service=SignatureVerification
+
+

Der Wert INFO besagt, dass die Log-Meldung im Log-Level INFO entstanden ist. Folgende Log-Levels existieren:

+ +

Der nächste Wert 01 21:25:26,540 gibt den Zeitpunkt an, zu dem die Log-Meldung generiert wurde (in diesem Fall den 1. Tag im aktuellen Monat, sowie die genaue Uhrzeit).

+

Der Wert Thread-3 bezeichnet den Thread, von dem die Anfrage bearbeitet wird.

+

Der Rest der Zeile einer Log-Meldung ist der eigentliche Text, mit dem das System bestimmte Informationen anzeigt. Im Fehlerfall ist häufig ein Java Stack-Trace angefügt, der eine genauere Ursachen-Forschung ermöglicht.

+

2.1.3.2 Wichtige Log-Meldungen

+

Neben den im Abschnitt 2.1.2.4.3 beschriebenen Log-Meldungen, die anzeigen, ob das Service ordnungsgemäß gestartet wurde, geben nachfolgenden Log-Meldungen Aufschluss über die Abarbeitung von Anfragen.

+

Die Entgegennahme einer Anfrage wird angezeigt durch: + +

+ 
125690 [ajp-bio-129.27.142.119-38609-exec-1] INFO moa.id.auth  - REQUEST: /moa-id-auth/dispatcher
+125690 [ajp-bio-129.27.142.119-38609-exec-1] INFO moa.id.auth  - QUERY  : mod=id_pvp2x&action=Post&
+

Ein Fehler beim Abarbeiten der Anfrage wird angezeigt durch: +

2435298 [ajp-bio-129.27.142.119-38609-exec-10] ERROR moa.id.auth  - Failed to generate a valid protocol request!
+
+

In diesem Fall gibt der mitgeloggte Stacktrace Auskunft über die Art des Fehlers.

+

Die tatsächlich übertragenen Anfragen bzw. Antworten werden aus Effizienzgründen nur im Log-Level DEBUG angezeigt.

+
+

2.2 Erweiterungsmöglichkeiten

+

Ausgehend von der Basisinstallation können die optionalen Erweiterungen, die in den nachfolgenden Abschnitten beschrieben werden, unabhängig und in beliebiger Kombination aufgesetzt werden.

+

2.2.1 Vorgeschalteter Webserver

+

2.2.1.1 Microsoft Internet Information Server (MS IIS)

+

Den MOA SP/SS Webservices kann optional ein MS IIS vorgeschaltet sein. In diesem Fall übernimmt der MS IIS die HTTP- bzw. HTTPS-Kommunikation mit dem Aufrufer des Webservices. Die Kommunikation zwischen MS IIS und dem in Tomcat eingerichteten MOA-ID Modulen wird durch mod_jk durchgeführt. Die angeführten Konfigurationsschritte gehen von einer MS IIS Standard-Installation aus.

+
2.2.1.1.1 Konfiguration von mod_jk im MS IIS
+

Für die Kommunikation des MS IIS mit dem im Tomcat eingerichteten MOA SP/SS Webservice wird das ISAPI-Modul von mod_jk im MS IIS installiert und konfiguriert. Eine detaillierte Installations- und Konfigurationsanleitung gibt das mod_jk IIS HowTo. Beispiele für workers.properties und uriworkermap.properties Dateien liegen im Verzeichnis $MOA_ID_AUTH_INST/tomcat bei.

+
2.2.1.1.2 Konfiguration von Tomcat
+

Damit Tomcat die Aufrufe entgegennehmen kann, die von MS IIS mittels mod_jk weiterleitet werden, muss in $CATALINA_HOME/conf/server.xml der AJP Connector aktiviert werden. Im Gegenzug können die Konnektoren für HTTP und HTTPS deaktiviert werden. Das geschieht am einfachsten durch Ein- bzw. Auskommentieren der entsprechenden Connector Konfigurations-Elemente in dieser Datei.

+
2.2.1.1.3 Konfiguration von SSL
+

Die Dokumentation zum Einrichten von SSL auf dem MS IIS steht nach Installation des IIS unter http://localhost/iisHelp/ oder aber auch auf den Webseiten von Mircrosoft zur Verfügung.

+

2.2.1.2 Apache

+

Den MOA SP/SS Webservices kann ein Apache Webserver vorgeschaltet sein. Das Prinzip funktioniert wie bei MS IIS, auch hier wird mod_jk für die Kommunikation zwischen Webserver und Tomcat eingesetzt. Die angeführten Konfigurationsschritte gehen von einer Standard-Installation des Apache Webservers aus.

+
2.2.1.2.1 Konfiguration von mod_jk im Apache
+

Um die MOA-ID Module hinter einem Apache Webserver zu betreiben, ist die Konfiguration des Apache-Moduls mod_jk erforderlich. Eine detaillierte Installations- und Konfigurationsanleitung gibt das mod_jk Apache HowTo. Ein Beispiel für eine workers.properties Datei liegt im Verzeichnis $MOA_ID_AUTH_INST/tomcat bei.

+

Um die MOA-ID Module dem Apache Webserver bekannt zu machen, sind zumindest folgende Einträge im globalen Kontext der Apache-Konfigurationsdatei notwendig:

+
LoadModule jk_module /usr/lib/apache/mod_jk.so
AddModule jk_module
JkOptions +ForwardKeySize +ForwardURICompat -ForwardDirectories
JkWorkersFile conf/workers.properties 
JkMount /moa-spss/* moaworker
+

Die Pfad- und Dateinamen können je nach existierender Apache Installation geringfügig variieren.

+
2.2.1.2.2 Konfiguration von Tomcat
+

Die Konfiguration von Tomcat ist analog zu Abschnitt 2.2.1.1.2 durchzuführen.

+
2.2.1.2.2 Konfiguration von SSL mit mod_SSL
+

Apache kann in Verbindung mit mod_SSL als SSL-Endpunkt für die MOA-ID Module fungieren. In diesem Fall entfällt die SSL-Konfiguration in Tomcat, da Apache und Tomcat auch im Fall von SSL Daten via mod_jk austauschen. Eine detaillierte Installations- und Konfigurationsanleitung enthält die Online-Dokumentation von mod_SSL.

+

Bei der Verwendung von Client-Authentisierung muss darauf geachtet werden, dass mod_ssl die HTTP-Header mit den Informationen über das Client-Zertifikat exportiert. Dies wird durch Angabe der folgenden Option in der Apache-Konfiguration erreicht:

+ 
SSLOptions +ExportCertData +StdEnvVars
+

Je nach vorhandener SSL-Konfiguration des Apache Webservers kann diese Option im globalen Kontext, im Kontext des Virtual Hosts oder im Kontext eines Verzeichnisses spezifiziert werden.

+

A Referenzierte Software

+

Auf folgende Software-Pakete wird in diesem Handbuch verwiesen:

+ + + + + + + + + + + + + + + + + +
NameBeschreibung
Apache Tomcat Apache Tomcat Servlet-Container
Java SEJava Standard Edition (Software Development Kit bzw. Java Runtime Environment)
Log4J Logging Framework
+ + + -- cgit v1.2.3