Logo BKA Dokumentation Logo EGIZ

MOA: Identifikation (ID)

Basis-Installation

Inhalt

  1. Vorbereitung

  2. Konfiguration von Tomcat

  3. Deployment von MOA-ID-AUTH in Tomcat

  4. Deployment von MOA-ID-PROXY in Tomcat

  5. Starten und Stoppen von Tomcat

  6. Logging

1 Vorbereitung

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.

Installation des JDK
Installieren Sie das JDK 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 Leer- und Sonderzeichen im Pfadnamen enthält. Am Besten verwenden die referenzierte Version von Tomcat im zip-Format. (Hinweis f. Windows: nicht die selbstinstallierende exe Version verwenden.) Das Wurzelverzeichnis der Tomcat-Installation wird im weiteren Verlauf als $CATALINA_HOME bezeichnet.

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 und des IAIK LDAP Protocol Handlers
Die Dateien aus dem Verzeichnis $MOA_ID_INST_AUTH/ext (oder $MOA_ID_INST_PROXY/ext) 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 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 des jeweiligen JDK in der Sektion "Other Downloads". D.h. JDK hier für 1.4.0, das JDK hier für 1.4.2, das JDK hier für 1.5.0 bzw. das JDK hier für 1.6.0

2 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 server.xml im Verzeichnis mit der Versionsnummer des verwendeten Tomcats unter $MOA_ID_INST_AUTH/tomcat (bzw. $MOA_ID_INST_PROXY/tomcat) enthält eine minimale Tomcat-Konfiguration, die je einen Connector für HTTP und für HTTPS freischaltet. Die jeweilige Datei server.mod_jk.xml schaltet zusätzlich den AJP Connector Port für den Apache Webserver frei (falls diese Datei verwendet werden soll ist sie zuvor noch auf server.xml umzubenennen).

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

3 Deployment von MOA-ID-AUTH in Tomcat

Um MOA-ID-AUTH in Tomcat für den Ablauf vorzubereiten, sind folgende Schritte notwendig:

4 Deployment von MOA-ID-PROXY in Tomcat

Um MOA-ID-PROXY in Tomcat für den Ablauf vorzubereiten, sind folgende Schritte notwendig:

Tomcat Konfiguration:

5 Starten und Stoppen von Tomcat

Nach dem Deployment und der Konfiguration kann Tomcat aus seinem Wurzelverzeichnis ($CATALINA_HOME) mit 
    startTomcat (unter Windows) oder
    moa-id-env.sh
    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.

Musterseite (MOA-Template zur Bürgerkartenauswahl)
Nach dem erfolgreichen Starten von Tomcat steht eine Musterseite unter der URL

http(s)://host:port/moa-id-auth/index.html

zur Verfügung. Diese Musterseite bietet eine integrierte Darstellung der Bürgerkartenauswahl bei MOA-ID. Die Musterseite stellt dabei beispielhaft dar, wie eine Bürgerkartenauswahl möglichst nahtlos in MOA-ID integriert werde kann. Sie umfaßt dabei vorkonfigurierte Loginmöglichkeiten mittels Online-BKU, lokaler BKU und Handy-BKU. Anmerkung: Um sich über die Musterseite einloggen zu können, müssen noch die Parameter für den MOA-ID Aufruf angegeben werden - siehe Dokumentation der Musterseite, die über die Musterseite verlinkt ist bzw. über folgende URL abgerufen werden kann

http(s)://host:port/moa-id-auth/BKAuswahl-MOA-Template-Howto.pdf

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.

6 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:
Es werden folgende Log-Hierarchien verwendet: 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:
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.