From b0b70fbb35a06c947371121c7e753090ebe06827 Mon Sep 17 00:00:00 2001 From: Thomas Lenz Date: Wed, 5 Mar 2014 19:10:28 +0100 Subject: finalize moa-id handbook for 2.0 RC1 --- id/server/doc/moa_id/id-admin_1.htm | 393 ------------------------------------ 1 file changed, 393 deletions(-) delete mode 100644 id/server/doc/moa_id/id-admin_1.htm (limited to 'id/server/doc/moa_id/id-admin_1.htm') diff --git a/id/server/doc/moa_id/id-admin_1.htm b/id/server/doc/moa_id/id-admin_1.htm deleted file mode 100644 index 940ef4d2d..000000000 --- a/id/server/doc/moa_id/id-admin_1.htm +++ /dev/null @@ -1,393 +0,0 @@ - - - MOA-ID Administration - - - - - - - - - - - - -
Logo BKADokumentationLogo EGIZ
-
-

MOA: Identifikation (ID)

-

Basis-Installation

-
-

Inhalt

-
    -
  1. -

    Vorbereitung

    -
    2. -
  2. -

    Konfiguration von Tomcat

    -
    3. -
  3. -

    Deployment von MOA-ID-AUTH in Tomcat

    -
    4. -
  4. -

    Deployment von MOA-ID-PROXY in Tomcat

    -
    5. -
  5. -

    Starten und Stoppen von Tomcat

    -
    6. -
  6. -

    Logging

    -
    7. -
-
-

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.

- - - -- cgit v1.2.3