Module für Online-Applikationen
 
Projekt moa 

MOA-ID

Basis-Installation

Basis-Installation v.1.1

Bei der Basis-Installation von MOA-ID-AUTH und von MOA-ID-PROXY ist grundsätzlich gleichartig vorzugehen. Unterschiede sind in der Installationsanweisung angeführt.

Vorbereitung

Installation des JDK
Installieren Sie das JDK 1.3.1 oder JDK 1.4.1 in ein beliebiges Verzeichnis. Das Wurzelverzeichnis der JDK-Installation wird im weiteren Verlauf als $JAVA_HOME bezeichnet.

Installation von Tomcat
Installieren Sie Tomcat in ein Verzeichnis, das keine Leerzeichen im Pfadnamen enthält. Das Wurzelverzeichnis der Tomcat-Installation wird im weiteren Verlauf als $CATALINA_HOME bezeichnet. Hinweis: Tomcat wird in einer Distribution für JDKs ab Version 1.2 und in einer Distribution speziell für JDK 1.4 ausgeliefert. Installieren Sie die zur Version Ihres JDK passende Tomcat-Version.

Entpacken der MOA ID Webapplikation
Entpacken Sie die ausgelieferten Dateien der Webapplikation (moa-id-auth-x.y.zip oder moa-id-proxy-x.y.zip; ersetzen Sie x.y durch die Releasenummer von MOA-ID-AUTH bzw. MOA-ID-PROXY) in ein beliebiges Verzeichnis. Diese Verzeichnisse werden im weiteren Verlauf als $MOA_ID_INST_AUTH bzw. $MOA_ID_INST_PROXY bezeichnet.

Installation der IAIK JCE, des IAIK LDAP Protocol Handlers und von JSSE (JDK 1.3.1)
Da Java in der Version 1.3.1 ohne Unterstützung für Kryptographie, LDAP und SSL ausgeliefert wird, müssen diese Funktionalitäten nachträglich installiert werden. Es stehen hierfür zwei Möglichkeiten zur Verfügung:
1. Installation innerhalb des JDK 1.3.1:
Die Dateien aus dem Verzeichnis $MOA_ID_INST_AUTH/ext13 (oder $MOA_ID_INST_PROXY/ext13) müssen in das Verzeichnis $JAVA_HOME/jre/lib/ext kopiert werden. Anschließend steht eine Unterstützung für Kryptographie und SSL jeder Java-Anwendung die dieses JDK verwendet zur Verfügung.
2. Installation ausschließlich für Applikationen innerhalb von Tomcat:
Um die o.g. Unterstützung nur Tomcat-Anwendungen zu ermöglichen, können die Dateien aus dem Verzeichnis $MOA_ID_INST_AUTH/ext13 (oder $MOA_ID_INST_PROXY/ext13) in ein beliebiges Verzeichnis kopiert werden. Im Folgenden wird dieses Verzeichnis $MOA_ID_EXT genannt. Anschließend muss der Tomcat-Klassenpfad angepasst werden:
Für Windows-Betriebssysteme ist dafür die Datei $CATALINA_HOME\bin\setclasspath.bat anzupassen:
Hinter 'set CLASSPATH=%JAVA_HOME%\lib\tools.jar' müssen nun jeweils mit Semikolon getrennt, die Dateien aus $MOA_ID_EXT inklusive der vollständigen Pfadangaben angefügt werden.
Anschließend sieht diese Zeile beispielsweise folgendermaßen aus: 
	set CLASSPATH=%JAVA_HOME%\lib\tools.jar;
		      $MOA_ID_EXT\iaik_jce_full.jar;
		      $MOA_ID_EXT\iaik_ldap.jar;
		      $MOA_ID_EXT\jcert.jar;
		      $MOA_ID_EXT\jnet.jar;
		      $MOA_ID_EXT\jsse.jar
($MOA_ID_EXT ist durch den tatsächlichen Pfad zu ersetzen)
Unix/Linux-Anwender verfahren analog mit der Datei $CATALINA_HOME/bin/setclasspath.sh wobei ';' durch ':' zu ersetzen ist.

Installation der IAIK JCE und des IAIK LDAP Protocol Handlers (JDK 1.4.1)
Die Dateien aus dem Verzeichnis $MOA_ID_INST_AUTH/ext14 (oder $MOA_ID_INST_PROXY/ext14) müssen in das Verzeichnis $JAVA_HOME/jre/lib/ext kopiert werden. Anschließend steht eine Unterstützung für Kryptographie und SSL jeder Java-Anwendung die dieses JDK verwendet zur Verfügung.
Zusätzlich müssen die so genannten "Unlimited Strength Jurisdiction Policy Files 1.4.1" heruntergeladen, entpackt und ins Verzeichnis $JAVA_HOME/jre/lib/security kopiert werden. Der Download für diese Dateien findet sich am unteren Ende der Download-Seite für das JDK 1.4.1 in der Sektion "Other Downloads".

 

Konfiguration von Tomcat

Minimale Konfiguration
Die zentrale Konfigurations-Datei von Tomcat ist $CATALINA_HOME/conf/server.xml. Tomcat wird grundsätzlich mit einer funktionierenden Default-Konfiguration ausgeliefert, die jedoch einiges an Ballast enthält und viele Ports offen lässt. Die Datei $MOA_ID_INST_AUTH/tomcat/server.xml (bzw. $MOA_ID_INST_PROXY/tomcat/server.xml) enthält eine minimale Tomcat-Konfiguration, die je einen Connector für HTTP und für HTTPS freischaltet.

SSL
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-PROXY verwendet werden. Das Dokument Tomcat SSL Configuration HOW-TO gibt einen guten Überblick über die Konfiguration von SSL in Tomcat. Da die für SSL notwendigen Bibliotheken bereits im Abschnitt "Vorbereitung" eingebunden wurden, sind nur noch folgende Schritte notwendig:
  • Erstellung eines Server-Keystores, welches den privaten Schlüssel des Servers sowie das Server-Zertifikat enthält, z.B. mit dem Java Keytool.
    Hinweis: Standardmäßig wird beim Erzeugen eines neuen Keystores im Home-Verzeichnis des Benutzers die Datei ".keystore" angelegt. Möchte man den Dateinamen und Pfad ändern, kann man das dem SSL-Connector in $CATALINA_HOME/conf/server.xml durch hinzufügen des Attributes keystoreFile="NAME DES KEYSTORES" im Element <Factory> bekannt machen. Das zum Keystore gehörende Passwort übergibt man Tomcat mittels des Attributes keystorePass= "PASSWORT DES KEYSTORES" im Element <Factory>.
  • Erstellung eines Keystores mit vertrauenswürdigen Client-Zertifikaten, z.B. mit dem Java Keytool (nur, wenn SSL Client-Authentisierung verwendet werden soll)
  • Falls eine Client-Authentisierung gewünscht ist, muss die Konfiguration des SSL-Connectors in $CATALINA_HOME/conf/server.xml angepasst werden.
MOA Administrator
Der Aufruf der URL für die dynamische Konfiguration von MOA-ID-AUTH ist durch eine Passwort-Abfrage geschützt, und kann nur von Benutzern aufgerufen werden, die der Benutzer-Rolle moa-admin zugeordnet werden können.
Um diese Benutzer-Rolle und einen oder mehrere Benutzer einzurichten, müssen in der Datei $CATALINA_HOME/conf/tomcat-users.xml unter dem Element <tomcat-users> sinngemäß folgende Einträge hinzugefügt werden: 
<role rolename="moa-admin"/>
<user username="moa" password="moa" roles="moa-admin"/>

 

Deployment von MOA-ID-AUTH in Tomcat

Um MOA-ID-AUTH in Tomcat für den Ablauf vorzubereiten, sind folgende Schritte notwendig:
  • Die Datei $MOA_ID_INST_AUTH/moa-id-auth.war wird ins Verzeichnis $CATALINA_HOME/webapps kopiert. Dort wird sie beim ersten Start von Tomcat automatisch ins Verzeichnis $CATALINA_HOME/webapps/moa-id-auth entpackt.
  • Die MOA-ID Konfigurationsdatei und die zugehörigen Verzeichnisse "certs" und "transforms" werden in ein beliebiges Verzeichnis im Filesystem kopiert (z.B. $CATALINA_HOME/conf/moa-id).
    In $MOA_ID_INST_AUTH/conf/moa-id befindet sich eine funktionsfähige Konfiguration, die als Ausgangspunkt für die Konfiguration von MOA-ID-AUTH dienen kann.
  • Die endorsed Libraries für Tomcat müssen aus dem Verzeichnis $MOA_ID_INST_AUTH/endorsed in das Tomcat-Verzeichnis $CATALINA_HOME/common/endorsed kopieren werden. Folgende Libraries sind für das Deployment im endorsed Verzeichnis vorgesehen:
    • Xerces-J-2.0.2 (bestehend aus xercesImpl.jar und xmlParserAPIs.jar)
    Eventuell vorhandene Dateien mit dem gleichen Namen müssen ersetzt werden.
  • Folgende Java System Properties sind zu setzen:
    • moa.id.configuration=Name der MOA ID Konfigurationsdatei. Eine beispielhafte MOA ID Konfiguration ist in $MOA_ID_INST_AUTH/conf/moa-id/ SampleMOAIDConfiguration.xml enthalten.
    • log4j.configuration=URL der Log4j Konfigurationsdatei. Eine beispielhafte Log4j-Konfiguration ist in $MOA_ID_INST_AUTH/conf/moa-id/log4j.properties enthalten.
    • javax.net.ssl.trustStore=Name des Truststores für vertrauenswürdige SSL Client-Zertifikate (optional; nur, wenn SSL Client-Authentisierung durchgeführt werden soll).
    Diese Java System-Properties werden Tomcat über die Umgebungsvariable CATALINA_OPTS mitgeteilt (siehe Beispiele für Windows und für Linux).

 

Deployment von MOA-ID-PROXY in Tomcat

Um MOA-ID-PROXY in Tomcat für den Ablauf vorzubereiten, sind folgende Schritte notwendig:
  • Die Datei $MOA_ID_INST_PROXY/moa-id-proxy.war wird in ein beliebiges Verzeichnis (bspw. $CATALINA_HOME) kopiert. HINWEIS: Das Verzeichnis darf NICHT $CATALINA_HOME/webapps sein!
    Anschliessend muss in der Datei $CATALINA_HOME/conf/server.xml der Tomcat-Root-Context auf diese Datei gesetzt werden: wenn das war-file sich in $CATALINA_HOME befindet, geschieht dies mit dem Einfügen von folgendem Element innerhalb von <Server>...<Service>...<Engine>...<Host>: 
    • <Context path="" docBase="../moa-id-proxy.war" debug="0"/>
    Anmerkung: Der Root-Context von Tomcat ist normalerweise auskommentiert.

  • Die MOA-ID Konfigurationsdatei und die zugehörigen Verzeichnisse "certs" und "oa" werden in ein beliebiges Verzeichnis im Filesystem kopiert (z.B. $CATALINA_HOME/ conf/moa-id).
    In $MOA_ID_INST_PROXY/conf/moa-id befindet sich eine funktionsfähige Konfiguration, die als Ausgangspunkt für die Konfiguration von MOA-ID-PROXY dienen kann.
  • Die endorsed Libraries für Tomcat müssen aus dem Verzeichnis $MOA_ID_INST_PROXY/endorsed in das Tomcat-Verzeichnis $CATALINA_HOME/common/endorsed kopiert werden. Folgende Libraries sind für das Deployment im endorsed Verzeichnis vorgesehen:
    • Xerces-J-2.0.2 (bestehend aus xercesImpl.jar und xmlParserAPIs.jar)
    Eventuell vorhandene Dateien mit dem gleichen Namen müssen ersetzt werden.
  • Folgende Java System Properties sind zu setzen:
    • moa.id.configuration=Name der MOA ID Konfigurationsdatei. Eine beispielhafte MOA ID Konfiguration ist in $MOA_ID_INST_AUTH/conf/moa-id/ SampleMOAIDConfiguration.xml enthalten.
    • log4j.configuration=URL der Log4j Konfigurationsdatei. Eine beispielhafte Log4j-Konfiguration ist in $MOA_ID_INST_AUTH/conf/moa-id/log4j.properties enthalten.
    • javax.net.ssl.trustStore=Name des Truststores für vertrauenswürdige SSL Client-Zertifikate (optional; nur, wenn SSL Client-Authentisierung durchgeführt werden soll).
    Diese Java System-Properties werden Tomcat über die Umgebungsvariable CATALINA_OPTS mitgeteilt (siehe Beispiele für Windows und für Linux).

 

Starten und Stoppen von Tomcat

Nach dem Deployment und der Konfiguration kann Tomcat aus seinem Wurzelverzeichnis mit 
    bin\catalina start (unter Windows) oder 
    bin/catalina.sh start (unter Unix/Linux)
gestartet werden. Das Stoppen von Tomcat erfolgt analog mit 
    bin\catalina stop  (unter Windows) oder 
    bin/catalina.sh stop (unter Unix/Linux)
Ein erfolgreicher Startvorgang von MOA-ID-AUTH ist an folgender Log-Meldung ersichtlich: 
    INFO | 08 13:33:38,497 | main | 
    	MOA ID Authentisierung wurde 
    	erfolgreich gestartet
Analog bei MOA-ID-PROXY: 
    INFO | 08 13:35:49,876 | main | 
    	MOA ID Proxy wurde erfolgreich gestartet
Nach dem erfolgreichen Starten von Tomcat steht MOA-ID-AUTH unter der URL 
http(s)://host:port/moa-id-auth/StartAuthentication
zur Verfügung. Der WebService ist unter 
http(s)://host:port/moa-id-auth/services/GetAuthenticationData
erreichbar. Die Verfügbarkeit der Anwendung kann überprüft werden, indem die URLs mit einem Web-Browser aufgerufen werden.

Dynamische Konfigurations-Updates
Dynamische Konfigurations-Updates können für MOA-ID-AUTH durch den Aufruf der URL http://hostname:port/moa-id-auth/ConfigurationUpdate (z.B. durch Eingabe in einem Browser) durchgeführt werden. Analog wird die Konfiguration von MOA-ID-PROXY mittels http://hostname:port/ConfigurationUpdate aktualisiert.

Hinweis: Konfigurationsänderungen für die Online-Applikationen betreffen grundsätzlich sowohl die Auth- als auch die Proxy-Komponente. Wenn bspw. das publicURLPrefix der OA geändert wird, muss sowohl für die Auth- als auch für die Proxy-Komponente ein ConfigurationUpdate durchgeführt werden.

Konnte MOA-ID-AUTH bzw. MOA-ID-PROXY nicht ordnungsgemäß konfiguriert und gestartet werden, geht das aus der Log-Meldung hervor: 
FATAL | 03 13:19:06,924 | main | Fehler 
	beim Starten des Service MOA ID Authentisierung
bzw. 
FATAL | 03 13:19:06,924 | main | Fehler 
	beim Starten des Service MOA ID Proxy
In diesem Fall geben die WARN bzw. ERROR Log-Meldungen unmittelbar davor Aufschluss über den genaueren Grund.

 

Logging

Die MOA ID Webapplikation verwendet Jakarta 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.
Es werden folgende Log-Hierarchien verwendet:
  • moa.id.auth für alle Log-Meldungen aus dem MOA-ID-AUTH Modul
  • moa.id.proxy für alle Log-Meldungen aus dem MOA-ID-PROXY Modul
  • moa.spss.server für alle Log-Meldungen aus dem MOA-SPSS Modul
  • iaik.server für alle Log-Meldungen aus den IAIK Kryptographie-Modulen
Als Ausgangspunkt für die Logging-Konfiguration liegt die Datei $MOA_ID_INST_AUTH/conf/moa-id/log4j.properties (bzw. $MOA_ID_INST_PROXY/conf/moa-id/log4j.properties) bei. Wird diese Datei als Logging-Konfiguration verwendet, so werden alle Log-Meldungen sowohl in die Konsole, als auch in die Datei $CATALINA_HOME/logs/moa-id.log geschrieben.

Format der Log-Meldungen
Anhand einer konkreten Log-Meldung wird das Format der MOA ID Log-Meldungen erläutert: 
    INFO | 09 08:23:59,385 | Thread-8 | 
    	Anmeldedaten zu MOASession -5468974113772848113 
    	angelegt, SAML Artifakt 
    	AAF/BrdRfnMaQVGIbP/Gf9OwDUwwsXChb7nuT+VXQzOoHbV
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 informative Status-Informationen über den Ablauf der Webapplikation, wie z.B., dass eine neue Anfrage eingelangt ist.
  • WARN: Bei der Ausführung einer Operation sind leichte Fehler aufgetreten. Der Ablauf der Webapplikation ist nicht weiter beeinträchtigt.
  • ERROR: Die Ausführung einer Operation musste abgebrochen werden. Die Webapplikation ist davon nicht beeinträchtigt.
  • FATAL: Es ist ein Fehler aufgetreten, der den weiteren Betrieb der Webapplikation nicht mehr sinnvoll macht.
Der nächste Wert 09 08:23:59,385, gibt den Zeitpunkt an, an dem die Log-Meldung generiert wurde (in diesem Fall den 9. Tag im aktuellen Monat, sowie die genaue Uhrzeit).
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.

Wichtige Log-Meldungen
Neben den im Abschnitt "Starten und Stoppen von Tomcat" beschriebenen Log-Meldungen, die anzeigen, ob die Webapplikation ordnungsgemäß gestartet wurde, geben nachfolgenden Log-Meldungen Aufschluss über die Abarbeitung von Anfragen. Die Annahme einer Anfrage wird beispielsweise angezeigt durch: 
    INFO | 09 08:37:17,663 | Thread-9 | 
      MOASession 6576509775379152205 angelegt  
     	
    INFO | 09 08:37:20,828 | Thread-9 | 
      Anmeldedaten zu MOASession 6576509775379152205 
      angelegt, SAML Artifakt 
      AAF/BrdRfnMaQVGIbP/Gf9OwDUwwsXChb7nuT+VXQzOoHbV
Die 1. Log-Meldung besagt, dass sich ein Benutzer an MOA-ID-AUTH angemeldet und eine eindeutige SessionID zugewiesen bekommen hat.
Die 2. Log-Meldung informiert darüber, dass die Anmeldedaten des Benutzers unter dem angezeigten SAML Artifakt abgeholt werden können.
Wenn nun versucht wird, eine Transaktion mit einer ungültigen SessionID fortzusetzen erhält man folgende Log-Meldung:
    ERROR | 09 09:34:27,105 | Thread-8 | 
	at.gv.egovernment.moa.id.AuthenticationException: 
	MOASessionID ist unbekannt 
	(MOASessionID=-8650403497547200032)
In diesem Fall gibt der mitgeloggte Stacktrace Auskunft über die Art des Fehlers. Der Aufrufer der MOA ID Webapplikation bekommt einen Fehlercode sowie eine kurze Beschreibung des Fehlers als Antwort zurück.

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



© 2003