MOA ID-Administration

+ + +

+ Module für Online-Applikationen +

+ +

+Projekt moa +

+
+ + + + + + +

MOA-ID

+ Übersicht

+ Basis-Installation

+ Konfiguration

+ Optionale
Komponenten

+
+

+ Zurück

+

+

+Installationsschritte: +
+Vorbereitung
+Tomcat Konfiguration
+Deployment
MOA-ID-AUTH
+Deployment
MOA-ID-PROXY
+Tomcat Start/Stop
+Logging
+

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"/>

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. +

+

+ + + + + + +

+
+ + +

+ + \ No newline at end of file -- cgit v1.2.3