|
Dokumentation | |
Installation
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.
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.
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.
Die folgenden Schritte dienen der Vorbereitung der Installation.
$JAVA_HOME bezeichnet. $CATALINA_HOME bezeichnet.moa-id-auth-2.0.0.zip in ein beliebiges Verzeichnis. Dieses Verzeichnis wird im weiteren Verlauf als $MOA_ID_AUTH_INST bezeichnet. 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.
Die zentrale Konfigurations-Datei von Tomcat ist $CATALINA_HOME/conf/server.xml. Tomcat wird grundsätzlich mit einer funktionierenden Default-Konfiguration ausgeliefert.
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.
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:
keytool erstellen, einem Programm, das Ihrer Java SE beiliegt.$CATALINA_HOME/conf/server.xml.$CATALINA_HOME/conf/server.xml angepasst werden.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).
Um die Module MOA-ID-Auth und MOA-ID-Configuratuion in Tomcat für den Einsatz vorzubereiten, sind folgende Schritte notwendig:
$MOA_ID_AUTH_INST/moa-id_auth.war enthält das einsatzfertige MOA-ID-Auth Webarchiv und muss ins Verzeichnis $CATALINA_HOME/webapps kopiert werden. Dort wird sie beim ersten Start von Tomcat automatisch ins Verzeichnis $CATALINA_HOME/webapps/moa-id-auth entpackt. $CATALINA_HOME/conf/moa-id). Eine funktionsfähige Konfiguration, die als Ausgangspunkt für die Basiskonfiguration des MOA-ID-Auth Modules dienen kann, finden Sie hier. xalan.jar, xercesImpl.jar, serializer.jar und xml-apis.jar aus dem Verzeichnis $MOA_ID_AUTH_INST/endorsed müssen in das Tomcat-Verzeichnis $CATALINA_HOME/endorsed (bzw. $CATALINA_HOME/common/endorsed bis Apache Tomcat Version 5.5) kopiert werden. Sind gleichnamige Dateien dort bereits vorhanden, müssen sie überschrieben werden. Die ggf. in diesem Verzeichnis vorhandene Datei xmlParserAPIs.jar muss gelöscht werden. Sollte das Verzeichnis endorsed nicht vorhanden sein, dann muss dieses zuerst erstellt werden.CATALINA_OPTS in der Form -D<name>=<wert> übergeben):
moa.id.configuration: Pfad und Name der Basiskonfigurationsdatei für MOA-ID-Auth. Eine beispielhafte Konfigurationsdatei fnden Sie hier. Wird ein relativer Pfad angegeben, wird dieser relativ zum Startverzeichnis der Java Virtual Machine interpretiert.moa.spss.server.configuration: Pfad und Name der zentralen Konfigurationsdatei für MOA SP/SS. Eine beispielhafte Konfigurationsdatei finden Sie hier. Wird ein relativer Pfad angegeben, wird dieser relativ zum Startverzeichnis der Java Virtual Machine interpretiert. Ist diese System Property nicht gesetzt, wird automatisch eine im Webarchiv unter WEB-INF/conf enthaltene Default-Konfiguration herangezogen.log4j.configuration: URL der Log4j Konfigurationsdatei. Eine beispielhafte Log4j-Konfiguration finden Sie hier. Wird eine relative URL angegeben, wird diese als File-URL relativ zum Startverzeichnis der Java Virtual Machine interpretiert. Ist diese System Property nicht gesetzt, wird automatisch eine im Webarchiv unter WEB-INF/classes enthaltene Default-Konfiguration herangezogen.javax.net.ssl.trustStore: Pfad und Dateiname des Truststores für vertrauenswürdige SSL Client-Zertifikate (optional; nur, wenn SSL Client-Authentisierung durchgeführt werden soll). Ein relativer Pfad werden relativ zum Startverzeichnis der Java Virtual Machine interpretiert.javax.net.ssl.trustStorePassword: Passwort für den Truststore (optional; nur, wenn SSL Client-Authentisierung durchgeführt werden soll). javax.net.ssl.trustStoreType: Truststore-Typ (optional; nur, wenn SSL Client-Authentisierung durchgeführt werden soll). Je nach verwendetem Keystore-Typ muss jks (Java Key Store) oder pkcs12 (PKCS#12-Datei) angegeben werden.$MOA_ID_AUTH_INST/moa-id_configuration.war enthält das einsatzfertige MOA-ID-Configuration Webarchiv und muss ins Verzeichnis $CATALINA_HOME/webapps kopiert werden. Dort wird sie beim ersten Start von Tomcat automatisch ins Verzeichnis $CATALINA_HOME/webapps/moa-id-configuration entpackt. $CATALINA_HOME/conf/moa-id-configuration). Eine funktionsfähige Konfiguration, die als Ausgangspunkt für die Basiskonfiguration des MOA-ID-Auth Modules dienen kann, finden Sie hier. xalan.jar, xercesImpl.jar, serializer.jar und xml-apis.jar aus dem Verzeichnis $MOA_ID_AUTH_INST/endorsed müssen in das Tomcat-Verzeichnis $CATALINA_HOME/endorsed (bzw. $CATALINA_HOME/common/endorsed bis Apache Tomcat Version 5.5) kopiert werden. Sind gleichnamige Dateien dort bereits vorhanden, müssen sie überschrieben werden. Die ggf. in diesem Verzeichnis vorhandene Datei xmlParserAPIs.jar muss gelöscht werden. Sollte das Verzeichnis endorsed nicht vorhanden sein, dann muss dieses zuerst erstellt werden.CATALINA_OPTS in der Form -D<name>=<wert> übergeben):
moa.id.webconfig: Pfad und Name der Basiskonfigurationsdatei für MOA-ID-Configuration. Eine beispielhafte Konfigurationsdatei fnden Sie hier. Wird ein relativer Pfad angegeben, wird dieser relativ zum Startverzeichnis der Java Virtual Machine interpretiert.log4j.configuration: URL der Log4j Konfigurationsdatei. Eine beispielhafte Log4j-Konfiguration finden Sie hier. Wird eine relative URL angegeben, wird diese als File-URL relativ zum Startverzeichnis der Java Virtual Machine interpretiert. Ist diese System Property nicht gesetzt, wird automatisch eine im Webarchiv unter WEB-INF/classes enthaltene Default-Konfiguration herangezogen.javax.net.ssl.trustStore: Pfad und Dateiname des Truststores für vertrauenswürdige SSL Client-Zertifikate (optional; nur, wenn SSL Client-Authentisierung durchgeführt werden soll). Ein relativer Pfad werden relativ zum Startverzeichnis der Java Virtual Machine interpretiert.javax.net.ssl.trustStorePassword: Passwort für den Truststore (optional; nur, wenn SSL Client-Authentisierung durchgeführt werden soll). javax.net.ssl.trustStoreType: Truststore-Typ (optional; nur, wenn SSL Client-Authentisierung durchgeführt werden soll). Je nach verwendetem Keystore-Typ muss jks (Java Key Store) oder pkcs12 (PKCS#12-Datei) angegeben werden.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.
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 startgestartet werden. Das Stoppen von Tomcat erfolgt analog mit
bin/catalina.sh stop
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.
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:
Das verwendete Log-Level (DEBUG, INFO, WARN, ERROR, FATAL);
Name und maximale Größe der Log-Datei(en);
Das Aussehen der Log-Einträge.
Hierbei wird folgende Log-Hierarchien verwendet:
at.gv.egovernment.moa.id.configuration für alle Log-Meldungen aus MOA-ID-Configuration
moa.id.auth für alle Log-Meldungen aus MOA-ID-Auth moa.spss.server für alle Log-Meldungen aus dem MOA/SPSS
iaik.server für alle Log-Meldungen aus den SIC/IAIK Kryptographie-Modulen.
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.
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:
DEBUG: Log-Meldungen im Log-Level DEBUG geben Auskunft über die innere Arbeitsweise des Systems. Sie sind hauptsächlich für Entwickler interessant.
INFO: Diese Log-Meldungen geben Status-Informationen über den Ablauf des Webservices, wie z.B. über das Einlangen einer neuen Anfrage.
WARN: Bei der Ausführung einer Anfrage sind leichte Fehler aufgetreten. Der Ablauf des Webservices ist nicht weiter beeinträchtigt.
ERROR: Die Ausführung einer Anfrage musste abgebrochen werden. Das Webservice ist davon nicht beeinträchtigt.
FATAL: Es ist ein Fehler aufgetreten, der den weiteren Betrieb des Webservices nicht mehr erlaubt.
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.
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.
Ausgehend von der Basisinstallation können die optionalen Erweiterungen, die in den nachfolgenden Abschnitten beschrieben werden, unabhängig und in beliebiger Kombination aufgesetzt werden.
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.
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.
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.
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.
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.
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.
Die Konfiguration von Tomcat ist analog zu Abschnitt 2.2.1.1.2 durchzuführen.
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.
Auf folgende Software-Pakete wird in diesem Handbuch verwiesen:
| Name | Beschreibung |
|---|---|
| Apache Tomcat | Apache Tomcat Servlet-Container |
| Java SE | Java Standard Edition (Software Development Kit bzw. Java Runtime Environment) |
| Log4J | Logging Framework |