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 MOA-ID-Auth v.1.5 und MOA-ID-Proxy v.2.0.0

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

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:

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).
Im Verzeichnis $MOA_ID_INST_AUTH/conf/moa-id befinden sich acht verschiedene Beispielkonfigurationen, die als Ausgangspunkte für die Konfiguration von MOA-ID-AUTH dienen können:
- SampleMOAIDConfiguration.xml: Konfiguration von MOA-ID für eine Anwendung aus dem öffentlichen Bereich.
  Karte: Bürgerkarte
  Konfiguration ohne Proxykomponente
- SampleMOAIDConfiguration_withTestBKs.xml: Konfiguration von MOA-ID für eine Anwendung aus dem öffentlichen Bereich.
  Karte: Bürgerkarte und Testkarte
  Konfiguration ohne Proxykomponente
- SampleMOAWIDConfiguration.xml: Konfiguration von MOA-ID für eine Anwendung aus dem privatwirtschaftlichen Bereich (MOA-WID Modus).
  Karte: Bürgerkarte
  Konfiguration ohne Proxykomponente
- SampleMOAWIDConfiguration_withTestBKs.xml: Konfiguration von MOA-ID für eine Anwendung aus dem privatwirtschaftlichen Bereich (MOA-WID Modus).
  Karte: Bürgerkarte und Testkarte
  Konfiguration ohne Proxykomponente
- SampleMOAIDConfigurationProxy.xml: Konfiguration von MOA-ID für eine Anwendung aus dem öffentlichen Bereich.
  Karte: Bürgerkarte
  Konfiguration mit Proxykomponente.
- SampleMOAIDConfiguration_withTestBKsProxy.xml: Konfiguration von MOA-ID für eine Anwendung aus dem öffentlichen Bereich.
  Karte: Bürgerkarte und Testkarte
  Konfiguration mit Proxykomponente
- SampleMOAWIDConfigurationProxy.xml: Konfiguration von MOA-ID für eine Anwendung aus dem privatwirtschaftlichen Bereich (MOA-WID Modus).
  Karte: Bürgerkarte
  Konfiguration mit Proxykomponente
- SampleMOAWIDConfiguration_withTestBKsProxy.xml: Konfiguration von MOA-ID für eine Anwendung aus dem privatwirtschaftlichen Bereich (MOA-WID Modus).
  Karte: Bürgerkarte und Testkarte
  Konfiguration mit Proxykomponente
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. Für Tomcat 6 müssen die Dateien in das Verzeichnis $CATALINA_HOME/endorsed kopiert werden (das Verzeichnis endorsed ist dabei im Allgemein erst anzulegen). Folgende Libraries sind für das Deployment im endorsed Verzeichnis vorgesehen:
- xalan.jar
- serializer.jar (für Xalan benötigt)
- xml-apis.jar
- xercesImpl.jar
Eventuell vorhandene Dateien mit dem gleichen Namen müssen ersetzt werden. Die ggf. in diesem Verzeichnis vorhandene Datei xmlParserAPIs.jar muss gelöscht 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 (Beispiel-Skripte zum Setzen dieser Properties für Windows und für Unix bzw. Linux finden sie unter $MOA_ID_INST_AUTH/tomcat/win32 bzw. $MOA_ID_INST_AUTH/tomcat/unix). Diese Skripte können sie nach $CATALINA_HOME kopieren und in Folge von dort starten nachdem die Variablen CATALINA_HOME sowie JAVA_HOME in den Skripten entsprechend den Pfaden der Installation gesetzt wurden.

Deployment von MOA-ID-PROXY in Tomcat

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

Für Tomcat 4.1.31:
- Die Datei $MOA_ID_INST_PROXY/moa-id-proxy.war wird in ein beliebiges Verzeichnis (bspw. $CATALINA_HOME/webappsProxy) kopiert. HINWEIS: Das Verzeichnis darf sich NICHT unterhalb $CATALINA_HOME/webapps befinden!
- Anschließend 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/webappsProxy befindet, geschieht dies mit dem Einfügen von folgendem Element innerhalb von <Server>...<Service>...<Engine>...<Host>:
```
<Context path=""
    docBase="../webappsProxy/moa-id-proxy.war"
    debug="0"/>
```
  Anmerkung: Der Root-Context von Tomcat ist normalerweise auskommentiert.
Für Tomcat 5.0.28:
- Die Datei $MOA_ID_INST_PROXY/moa-id-proxy.war ist in ein beliebiges Verzeichnis (bspw. $CATALINA_HOME/webappsProxy) zu entpacken (diese Datei ist mittels ZIP Algorithmus komprimiert und kann mit jedem Tool, das mit .ZIP-Dateien umgehen kann, geöffnet werden). HINWEIS: Das Verzeichnis darf sich NICHT unterhalb $CATALINA_HOME/webapps befinden!
- Anschließend muss in der Datei $CATALINA_HOME/conf/server.xml der Tomcat-Root-Context auf diese Datei gesetzt werden: wenn die Proxy Web-Applikation nach $CATALINA_HOME\webappsProxy entpackt wurde, geschieht dies mit dem Einfügen von folgendem Element innerhalb von <Server>...<Service>...<Engine>...<Host>:

Tomcat Konfiguration:

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).
Im Verzeichnis $MOA_ID_INST_PROXY/conf/moa-id befinden sich vier verschiedene Beispielkonfigurationen, die als Ausgangspunkte für die Konfiguration von MOA-ID-PROXY dienen können.
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.4.0 (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).

moa-id-env.sh.txt

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.

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.