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.

- -

-

- - - - - - -

-
- - -