<html>
<head>
	<title>MOA-ID Administration</title>
	<meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type" />
	<link rel="stylesheet" href="./common/MOA.css" type="text/css">
</head>

<body link="#990000"> 

<table class="logoTable" width="100%" border="0" cellspacing="0" cellpadding="10">
    <tr>
      <td align="center" class="logoTitle" width="267"><img src="common/LogoBKA.png" alt="Logo BKA" width="267" height="37" align="left"></td>
      <td align="center" class="logoTitle">Dokumentation</td>
      <td align="center" class="logoTitle" width="123"><img src="common/LogoEGIZ.png" alt="Logo EGIZ" width="230" height="81" align="right"></td>
    </tr>
</table>
  <hr/> 
  <p class="title"><a href="./moa.htm">MOA: Identifikation (ID)</a></p> 
  <p class="subtitle">Basis-Installation</p> 
  <hr/>
<h1>Inhalt</h1>
  <ol> 
    <li> 
      <p><a href="#vorbereitung">Vorbereitung</a></p>
    </li>
    <li>
      <p><a href="#Tomcat">Konfiguration von Tomcat</a></p>
    </li>
    <li>
      <p><a href="#deployment_ak">Deployment von MOA-ID-AUTH in Tomcat</a></p>
    </li>
    <li>
      <p><a href="#deployment_pk">Deployment von MOA-ID-PROXY in Tomcat</a></p>
    </li>
    <li>
      <p><a href="#Tomcat_Start">Starten und Stoppen von Tomcat</a></p>
    </li>
    <li>
      <p><a href="#Logging">Logging</a></p>
    </li>
</ol>
    <hr/>
<h1><a name="vorbereitung" id="vorbereitung">1 Vorbereitung</a></h1>
<p>Bei der Basis-Installation von MOA-ID-AUTH und von MOA-ID-PROXY ist grunds&auml;tzlich gleichartig vorzugehen.
Unterschiede sind in der Installationsanweisung angef&uuml;hrt.</p>
<p><b>Installation des JDK</b><br />
Installieren Sie das JDK in ein
              beliebiges Verzeichnis. Das Wurzelverzeichnis der JDK-Installation
              wird im weiteren Verlauf als $JAVA_HOME bezeichnet. <br />
              <br />
              <b>Installation von Tomcat</b><br />
Installieren Sie Tomcat in ein Verzeichnis, das <b>keine Leer- und
              Sonderzeichen</b> im Pfadnamen enth&auml;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.<br />
        <br />
        <b>Entpacken der MOA ID Webapplikation</b><br />
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. <br />
              <br />
              <b>Installation der IAIK JCE und des IAIK LDAP Protocol Handlers</b><br />
Die Dateien aus dem Verzeichnis $MOA_ID_INST_AUTH/ext (oder $MOA_ID_INST_PROXY/ext)
              m&uuml;ssen in das Verzeichnis $JAVA_HOME/jre/lib/ext kopiert werden.
              Anschlie&szlig;end steht eine Unterst&uuml;tzung f&uuml;r Kryptographie
              und SSL jeder Java-Anwendung die dieses JDK verwendet zur Verf&uuml;gung.<br>
              <br />
Zus&auml;tzlich m&uuml;ssen die so genannten Unlimited Strength
              Jurisdiction Policy Files  heruntergeladen, entpackt
und ins Verzeichnis $JAVA_HOME/jre/lib/security kopiert werden. </p>
<p>Der Download f&uuml;r diese Dateien findet sich am unteren Ende
  der Download-Seite des jeweiligen JDK in der Sektion "Other
  Downloads". D.h. JDK <a href="http://java.sun.com/j2se/1.4.0/download.html"> hier f&uuml;r 1.4.0</a>, das JDK <a href="http://java.sun.com/j2se/1.4.2/download.html">hier
    f&uuml;r 1.4.2</a>, das JDK <a href="http://java.sun.com/j2se/1.5.0/download.html">hier
      f&uuml;r 1.5.0</a> bzw. das JDK <a href="http://www.oracle.com/technetwork/java/javase/downloads/index.html">hier
        f&uuml;r 1.6.0</a></p>
        
        
<h1><a name="Tomcat" id="Tomcat"></a>2 Konfiguration von Tomcat</h1>
<b>Minimale Konfiguration</b> <br />
  Die zentrale Konfigurations-Datei von Tomcat ist $CATALINA_HOME/conf/server.xml. Tomcat wird grunds&auml;tzlich mit
  einer funktionierenden Default-Konfiguration ausgeliefert, die jedoch einiges an Ballast enth&auml;lt und viele Ports
  offen l&auml;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&auml;lt eine minimale
  Tomcat-Konfiguration, die je einen Connector f&uuml;r HTTP und f&uuml;r HTTPS freischaltet. Die jeweilige Datei server.mod_jk.xml schaltet zus&auml;tzlich den AJP Connector Port f&uuml;r den Apache Webserver frei (falls diese Datei verwendet werden soll ist sie zuvor noch auf server.xml umzubenennen).<br />
  <br />
  <b>SSL</b><br />
  F&uuml;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 &uuml;bernimmt.
  Ebenso kann SSL auch f&uuml;r MOA-ID-PROXY verwendet werden.
  Das Dokument <a href="http://jakarta.apache.org/tomcat/tomcat-4.1-doc/ssl-howto.html" target="_new">Tomcat SSL Configuration HOW-TO</a> gibt einen guten &Uuml;berblick &uuml;ber die Konfiguration von SSL in Tomcat. Da die f&uuml;r SSL notwendigen Bibliotheken bereits im Abschnitt "Vorbereitung" eingebunden wurden, sind nur noch folgende Schritte notwendig:<ul>
  <li>Erstellung eines Server-Keystores, welches den privaten Schl&uuml;ssel des Servers sowie das Server-Zertifikat enth&auml;lt,
    z.B. mit dem <a href="http://java.sun.com/j2se/1.3/docs/tooldocs/win32/keytool.html" target="_new"> Java Keytool</a>. <br />
    <b>Hinweis:</b> Standardm&auml;&szlig;ig wird beim Erzeugen eines neuen Keystores im Home-Verzeichnis des Benutzers die Datei ".keystore" angelegt. M&ouml;chte man den Dateinamen und Pfad &auml;ndern, kann man das dem SSL-Connector in $CATALINA_HOME/conf/server.xml durch hinzuf&uuml;gen des Attributes <i>keystoreFile="NAME DES KEYSTORES"</i> im Element &lt;Factory&gt; bekannt machen. Das zum Keystore geh&ouml;rende Passwort &uuml;bergibt man Tomcat mittels des Attributes <i>keystorePass= "PASSWORT DES KEYSTORES"</i> im Element &lt;Factory&gt;. </li>
  <li>Erstellung eines Keystores mit vertrauensw&uuml;rdigen Client-Zertifikaten, z.B. mit dem <a href="http://java.sun.com/j2se/1.3/docs/tooldocs/win32/keytool.html" target="_new"> Java Keytool</a> (nur, wenn SSL Client-Authentisierung verwendet werden soll) </li>
  <li>Falls eine Client-Authentisierung gew&uuml;nscht ist, muss die Konfiguration des SSL-Connectors in $CATALINA_HOME/conf/server.xml angepasst werden.</li>
</ul>
<b>MOA Administrator</b><br />
  Der Aufruf der URL f&uuml;r die dynamische Konfiguration von MOA-ID-AUTH ist durch eine Passwort-Abfrage gesch&uuml;tzt, und kann nur von Benutzern aufgerufen werden, die der Benutzer-Rolle <tt>moa-admin</tt> zugeordnet werden k&ouml;nnen.<br />
  Um diese Benutzer-Rolle und einen oder mehrere Benutzer einzurichten, m&uuml;ssen in der Datei $CATALINA_HOME/conf/tomcat-users.xml unter dem Element <tt>&lt;tomcat-users&gt;</tt> sinngem&auml;&szlig; folgende Eintr&auml;ge hinzugef&uuml;gt werden:
<pre>
&lt;role rolename="moa-admin"/&gt;
&lt;user username="moa" password="moa" roles="moa-admin"/&gt;</pre>

<h1><a name="deployment_ak" id="deployment_ak"></a>3 Deployment von MOA-ID-AUTH in Tomcat</h1>
Um MOA-ID-AUTH in Tomcat f&uuml;r den Ablauf vorzubereiten, sind folgende Schritte notwendig: <br />

<ul>
  <li>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. </li>
  <li>Die MOA-ID Konfigurationsdatei und die zugeh&ouml;rigen Verzeichnisse
    "certs" und "transforms" werden in ein beliebiges Verzeichnis
    im Filesystem kopiert (z.B. $CATALINA_HOME/conf/moa-id). <br />
    Im Verzeichnis $MOA_ID_INST_AUTH/conf/moa-id befinden sich
    acht verschiedene Beispielkonfigurationen, die als Ausgangspunkte
    f&uuml;r die Konfiguration von MOA-ID-AUTH dienen k&ouml;nnen:
    <ul>
      <li>SampleMOAIDConfiguration.xml: Konfiguration von MOA-ID f&uuml;r
        eine Anwendung aus dem &ouml;ffentlichen Bereich. <br>
        Karte: B&uuml;rgerkarte <br>
        Konfiguration ohne Proxykomponente</li>
      <li>SampleMOAIDConfiguration_withTestBKs.xml: Konfiguration von MOA-ID
        f&uuml;r eine Anwendung aus dem &ouml;ffentlichen Bereich. <br>
        Karte: B&uuml;rgerkarte und Testkarte <br>
        Konfiguration ohne Proxykomponente</li>
      <li>SampleMOAWIDConfiguration.xml: Konfiguration von MOA-ID f&uuml;r
        eine Anwendung aus dem privatwirtschaftlichen Bereich (MOA-WID Modus). <br>
        Karte: B&uuml;rgerkarte <br>
        Konfiguration ohne Proxykomponente</li>
      <li>SampleMOAWIDConfiguration_withTestBKs.xml: Konfiguration von MOA-ID f&uuml;r
        eine Anwendung aus dem privatwirtschaftlichen Bereich (MOA-WID Modus). <br>
        Karte: B&uuml;rgerkarte und Testkarte <br>
        Konfiguration ohne Proxykomponente</li>
      <li id="sampleProxyConfig">SampleMOAIDConfigurationProxy.xml: Konfiguration von MOA-ID f&uuml;r
        eine Anwendung aus dem &ouml;ffentlichen Bereich. <br>
        Karte: B&uuml;rgerkarte <br>
        Konfiguration mit <a href="#deployment_pk">Proxykomponente</a>.</li>
      <li>SampleMOAIDConfiguration_withTestBKsProxy.xml: Konfiguration von MOA-ID
        f&uuml;r eine Anwendung aus dem &ouml;ffentlichen Bereich. <br>
        Karte: B&uuml;rgerkarte und Testkarte <br>
        Konfiguration mit <a href="#deployment_pk">Proxykomponente</a></li>
      <li>SampleMOAWIDConfigurationProxy.xml: Konfiguration von MOA-ID f&uuml;r
        eine Anwendung aus dem privatwirtschaftlichen Bereich (MOA-WID Modus). <br>
        Karte: B&uuml;rgerkarte <br>
        Konfiguration mit <a href="#deployment_pk">Proxykomponente</a></li>
      <li>SampleMOAWIDConfiguration_withTestBKsProxy.xml: Konfiguration von MOA-ID f&uuml;r
        eine Anwendung aus dem privatwirtschaftlichen Bereich (MOA-WID Modus). <br>
        Karte: B&uuml;rgerkarte und Testkarte <br>
        Konfiguration mit <a href="#deployment_pk">Proxykomponente</a></li>
    </ul>
  </li>
  <li>Die endorsed Libraries f&uuml;r Tomcat m&uuml;ssen aus dem
    Verzeichnis $MOA_ID_INST_AUTH/endorsed in das Tomcat-Verzeichnis
    $CATALINA_HOME/common/endorsed kopieren werden. F&uuml;r Tomcat 6 m&uuml;ssen die Dateien in das Verzeichnis $CATALINA_HOME/endorsed kopiert werden (das Verzeichnis endorsed ist dabei im Allgemein erst anzulegen). Folgende Libraries
    sind f&uuml;r das Deployment im endorsed Verzeichnis vorgesehen:
    <ul>
      <li>xalan.jar</li>
      <li>serializer.jar (f&uuml;r Xalan ben&ouml;tigt)</li>
      <li>xml-apis.jar</li>
      <li id="klein2">xercesImpl.jar</li>
    </ul>
    Eventuell vorhandene Dateien mit dem gleichen Namen m&uuml;ssen
    ersetzt werden. Die ggf. in diesem Verzeichnis vorhandene Datei <code>xmlParserAPIs.jar</code> muss gel&ouml;scht werden.</li>
  <li>Folgende Java System Properties sind zu setzen: <br />
    <ul id="klein2">
      <li id="klein2">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.</li>
      <li id="klein2">log4j.configuration=URL der Log4j Konfigurationsdatei.
        Eine beispielhafte Log4j-Konfiguration ist in $MOA_ID_INST_AUTH/conf/moa-id/log4j.properties
        enthalten. </li>
      <li id="klein2">javax.net.ssl.trustStore=Name des Truststores
        f&uuml;r vertrauensw&uuml;rdige SSL Client-Zertifikate (optional;
        nur, wenn SSL Client-Authentisierung durchgef&uuml;hrt werden
        soll). <br>
      </li>
    </ul>
    Diese Java System-Properties werden Tomcat &uuml;ber die Umgebungsvariable
    CATALINA_OPTS mitgeteilt (Beispiel-Skripte zum Setzen dieser
    Properties f&uuml;r <b>Windows</b> und f&uuml;r <b>Unix bzw.
      Linux</b> finden sie unter $MOA_ID_INST_AUTH/tomcat/win32 bzw.
    $MOA_ID_INST_AUTH/tomcat/unix). Diese Skripte k&ouml;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.
</ul>
<h1><a name="deployment_pk" id="deployment_pk"></a>4 Deployment von MOA-ID-PROXY in Tomcat</h1>
Um MOA-ID-PROXY in Tomcat f&uuml;r den Ablauf vorzubereiten, sind folgende Schritte notwendig: <br />
<ul>
  <li> <b>F&uuml;r Tomcat 4.1.31:</b>
    <ul>
      <li>Die Datei $MOA_ID_INST_PROXY/moa-id-proxy.war wird in ein
        beliebiges Verzeichnis (bspw. $CATALINA_HOME/webappsProxy) kopiert. <b>HINWEIS:
          Das Verzeichnis darf sich NICHT unterhalb $CATALINA_HOME/webapps befinden!</b><br/>
      </li>
      <li>Anschlie&szlig;end muss in der Datei <tt>$CATALINA_HOME/conf/server.xml</tt> der
        Tomcat-Root-Context auf diese Datei gesetzt werden: wenn
        das war-file sich in $CATALINA_HOME/webappsProxy befindet, geschieht dies
        mit dem Einf&uuml;gen von folgendem Element innerhalb von <tt>&lt;Server&gt;...&lt;Service&gt;...&lt;Engine&gt;...&lt;Host&gt;</tt>:
        <pre>&lt;Context path=""
    docBase="../webappsProxy/moa-id-proxy.war"
    debug="0"/&gt;</pre>
        Anmerkung: Der Root-Context von Tomcat ist normalerweise auskommentiert. </li>
    </ul>
  </li>
  <li> <b>F&uuml;r Tomcat 5.0.28:</b>
    <ul>
      <li>Die Datei $MOA_ID_INST_PROXY/moa-id-proxy.war ist in ein
        beliebiges Verzeichnis (bspw. $CATALINA_HOME/webappsProxy) <b>zu entpacken</b> (diese Datei ist mittels ZIP Algorithmus komprimiert und kann mit jedem Tool,
        das mit .ZIP-Dateien umgehen kann, ge&ouml;ffnet werden). <b>HINWEIS:
          Das Verzeichnis darf sich NICHT unterhalb $CATALINA_HOME/webapps befinden!</b><br/>
      </li>
      <li>Anschlie&szlig;end muss in der Datei <tt>$CATALINA_HOME/conf/server.xml</tt> 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&uuml;gen
        von folgendem Element innerhalb von <tt>&lt;Server&gt;...&lt;Service&gt;...&lt;Engine&gt;...&lt;Host&gt;</tt>: </li>
      <pre>&lt;Context path="" docBase="../webappsProxy"
    debug="0"/&gt;</pre>
      Alternativ kann statt die Datei server.xml zu &auml;ndern in <tt>$CATALINA_HOME\conf\Catalina\localhost</tt> eine Datei moa-id-proxy.xml mit vorhin angegebenen Inhalt erstellt werden.
    </ul>
  </li>
</ul>
<br />
<b>Tomcat Konfiguration:</b>
<ul>
  <li>Die MOA-ID Konfigurationsdatei und die zugeh&ouml;rigen
    Verzeichnisse "certs" und "oa" werden in ein beliebiges Verzeichnis
    im Filesystem kopiert (z.B. $CATALINA_HOME/ conf/moa-id). <br />
    Im Verzeichnis $MOA_ID_INST_PROXY/conf/moa-id befinden sich
    vier verschiedene <a href="#sampleProxyConfig">Beispielkonfigurationen</a>,
    die als Ausgangspunkte f&uuml;r die Konfiguration von MOA-ID-PROXY
    dienen k&ouml;nnen. </li>
  <li>Die endorsed Libraries f&uuml;r Tomcat m&uuml;ssen aus dem
    Verzeichnis $MOA_ID_INST_PROXY/endorsed in das Tomcat-Verzeichnis
    $CATALINA_HOME/common/endorsed kopiert werden. Folgende Libraries
    sind f&uuml;r das Deployment im endorsed Verzeichnis vorgesehen:
    <ul>
      <li id="klein3">Xerces-J-2.4.0 (bestehend aus xercesImpl.jar
        und xmlParserAPIs.jar)</li>
    </ul>
    Eventuell vorhandene Dateien mit dem gleichen Namen m&uuml;ssen
    ersetzt werden. </li>
  <li>Folgende Java System Properties sind zu setzen: <br />
    <ul id="klein3">
      <li id="klein3">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.</li>
      <li id="klein3">log4j.configuration=URL der Log4j Konfigurationsdatei.
        Eine beispielhafte Log4j-Konfiguration ist in $MOA_ID_INST_AUTH/conf/moa-id/log4j.properties
        enthalten. </li>
      <li id="klein3">javax.net.ssl.trustStore=Name des Truststores
        f&uuml;r vertrauensw&uuml;rdige SSL Client-Zertifikate
        (optional; nur, wenn SSL Client-Authentisierung durchgef&uuml;hrt
        werden soll). </li>
    </ul>
  </li>
  Diese Java System-Properties werden Tomcat &uuml;ber die Umgebungsvariable
  CATALINA_OPTS mitgeteilt (siehe Deployment von MOA-ID-AUTH <a href="examples/moa-id-env.sh.txt">moa-id-env.sh.txt</a>). <br>
  <br>
  Beispiel-Skripts zum Setzen von CATALINA_OPTS und zum Starten
  von Tomcat sind in $MOA_ID_INST_AUTH\tomcat\ zu finden - Sie
  k&ouml;nnen diese f&uuml;r Ihre Zwecke adaptieren (JAVA_HOME
  und $CATALINA_HOME setzen) und nach $CATALINA_HOME kopieren.
</ul>
<h1><a name="Tomcat_Start" id="Tomcat_Start"></a>5 Starten und Stoppen von Tomcat</h1>
Nach dem Deployment und der Konfiguration kann
                  Tomcat aus seinem Wurzelverzeichnis ($CATALINA_HOME) mit <br />
<pre>
    startTomcat (unter Windows) oder
    moa-id-env.sh
    bin/catalina.sh start (unter Unix/Linux)
</pre>
gestartet werden. Das Stoppen von Tomcat erfolgt analog mit <br />
<pre>
    bin\catalina stop  (unter Windows) oder
    bin/catalina.sh stop (unter Unix/Linux)
</pre>
Ein erfolgreicher Startvorgang von MOA-ID-AUTH ist an folgender Log-Meldung ersichtlich: <br />
<pre>
    INFO | 08 13:33:38,497 | main |
    	MOA ID Authentisierung wurde
    	erfolgreich gestartet
</pre>
Analog bei MOA-ID-PROXY: <br/>
<pre>
    INFO | 08 13:35:49,876 | main |
    	MOA ID Proxy wurde erfolgreich gestartet
</pre>
Nach dem erfolgreichen Starten von Tomcat steht MOA-ID-AUTH unter der URL
<pre>
http(s)://host:port/moa-id-auth/StartAuthentication
</pre>
zur Verf&uuml;gung. Der WebService ist unter
<pre>
http(s)://host:port/moa-id-auth/services/GetAuthenticationData
</pre>
<p>erreichbar. Die Verf&uuml;gbarkeit der Anwendung kann &uuml;berpr&uuml;ft werden, indem die URLs mit einem Web-Browser aufgerufen werden.</p>
<p><strong>Musterseite (MOA-Template zur B&uuml;rgerkartenauswahl)</strong><br />
Nach dem erfolgreichen Starten von Tomcat steht eine Musterseite unter der URL</p>
<pre>
http(s)://host:port/moa-id-auth/index.html</pre>
<p>zur Verf&uuml;gung. Diese Musterseite bietet eine integrierte Darstellung der B&uuml;rgerkartenauswahl bei MOA-ID. Die Musterseite stellt dabei beispielhaft dar, wie eine B&uuml;rgerkartenauswahl m&ouml;glichst nahtlos in MOA-ID integriert werde kann. Sie umfa&szlig;t dabei vorkonfigurierte Loginm&ouml;glichkeiten mittels Online-BKU, lokaler BKU und Handy-BKU. <em>Anmerkung</em>: Um sich &uuml;ber die Musterseite einloggen zu k&ouml;nnen, m&uuml;ssen noch die Parameter f&uuml;r den MOA-ID Aufruf angegeben werden - siehe Dokumentation der Musterseite, die &uuml;ber die Musterseite verlinkt ist bzw. &uuml;ber folgende URL abgerufen werden kann</p>
<pre>
http(s)://host:port/moa-id-auth/BKAuswahl-MOA-Template-Howto.pdf </pre>
<p><b>Dynamische Konfigurations-Updates</b><br />
  Dynamische Konfigurations-Updates k&ouml;nnen f&uuml;r MOA-ID-AUTH durch den Aufruf der URL http://hostname:port/moa-id-auth/ConfigurationUpdate (z.B. durch Eingabe in einem Browser) durchgef&uuml;hrt werden. Analog wird die Konfiguration von MOA-ID-PROXY mittels http://hostname:port/ConfigurationUpdate aktualisiert.<br />
  <br />
  <b>Hinweis: </b>Konfigurations&auml;nderungen f&uuml;r die Online-Applikationen betreffen grunds&auml;tzlich sowohl die Auth- als auch die Proxy-Komponente.
  Wenn bspw. das <tt>publicURLPrefix</tt> der OA ge&auml;ndert wird, muss sowohl f&uuml;r die Auth- als auch f&uuml;r die Proxy-Komponente ein ConfigurationUpdate durchgef&uuml;hrt werden. <br />
  <br />
  Konnte MOA-ID-AUTH bzw. MOA-ID-PROXY nicht ordnungsgem&auml;&szlig; konfiguriert und gestartet werden, geht das aus der Log-Meldung hervor: <br />
</p>
<pre>
FATAL | 03 13:19:06,924 | main | Fehler
	beim Starten des Service MOA ID Authentisierung
</pre>
bzw.
<pre>
FATAL | 03 13:19:06,924 | main | Fehler
	beim Starten des Service MOA ID Proxy
</pre>
In diesem Fall geben die WARN bzw. ERROR Log-Meldungen unmittelbar davor Aufschluss &uuml;ber den genaueren Grund.
<h1><a name="Logging" id="Logging"></a>6 Logging</h1>
Die MOA ID Webapplikation verwendet Jakarta Log4j f&uuml;r die Ausgabe von Log-Meldungen am Bildschirm bzw. in Log-Dateien. Log4j bietet zahlreiche Konfigurationsm&ouml;glichkeiten, die ausf&uuml;hrlich im <a href="http://jakarta.apache.org/log4j/docs/manual.html" target="_new">Log4j Handbuch</a> beschrieben sind. Unter anderem gibt es die M&ouml;glichkeit, folgende Einstellungen vorzunehmen: <br />
  <ul>
    <li id="klein4">Das verwendete Log-Level (DEBUG, INFO, WARN, ERROR, FATAL).</li>
    <li id="klein4">Name und maximale Gr&ouml;&szlig;e der Log-Datei(en).</li>
    <li id="klein4">Das Aussehen der Log-Eintr&auml;ge.</li>
  </ul>
  Es werden folgende Log-Hierarchien verwendet: 
<ul>
  <li>moa.id.auth f&uuml;r alle Log-Meldungen aus dem MOA-ID-AUTH Modul </li>
  <li>moa.id.proxy f&uuml;r alle Log-Meldungen aus dem MOA-ID-PROXY Modul </li>
  <li>moa.spss.server f&uuml;r alle Log-Meldungen aus dem MOA-SPSS Modul </li>
  <li>iaik.server f&uuml;r alle Log-Meldungen aus den IAIK Kryptographie-Modulen </li>
</ul>
Als Ausgangspunkt f&uuml;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 <tt>$CATALINA_HOME/logs/moa-id.log</tt> geschrieben. <br />
  <br />
  <b>Format der Log-Meldungen</b><br />
  Anhand einer konkreten Log-Meldung wird das Format der MOA ID Log-Meldungen erl&auml;utert:
  <pre>
    INFO | 09 08:23:59,385 | Thread-8 |
    	Anmeldedaten zu MOASession -5468974113772848113
    	angelegt, SAML Artifakt
    	AAF/BrdRfnMaQVGIbP/Gf9OwDUwwsXChb7nuT+VXQzOoHbV
</pre>
  Der Wert <tt>INFO</tt> besagt, dass die Log-Meldung im Log-Level <tt>INFO</tt> entstanden ist. Folgende Log-Levels existieren:<br />
  <ul>
    <li id="klein4"><tt>DEBUG:</tt> Log-Meldungen im Log-Level <tt>DEBUG</tt> geben Auskunft &uuml;ber die innere Arbeitsweise des Systems. Sie sind haupts&auml;chlich f&uuml;r Entwickler interessant.</li>
    <li id="klein4"><tt>INFO:</tt> Diese Log-Meldungen geben informative Status-Informationen &uuml;ber den Ablauf der Webapplikation, wie z.B., dass eine neue Anfrage eingelangt ist.</li>
    <li id="klein4"><tt>WARN:</tt> Bei der Ausf&uuml;hrung einer Operation sind leichte Fehler aufgetreten. Der Ablauf der Webapplikation ist nicht weiter beeintr&auml;chtigt.</li>
    <li id="klein4"><tt>ERROR:</tt> Die Ausf&uuml;hrung einer Operation musste abgebrochen werden. Die Webapplikation ist davon nicht beeintr&auml;chtigt. </li>
    <li id="klein4"><tt>FATAL:</tt> Es ist ein Fehler aufgetreten, der den weiteren Betrieb der Webapplikation nicht mehr sinnvoll macht.</li>
  </ul>
  Der n&auml;chste Wert <tt>09 08:23:59,385</tt>, gibt den Zeitpunkt an, an dem die Log-Meldung generiert wurde (in diesem Fall den 9. Tag im aktuellen Monat, sowie die genaue Uhrzeit). <br />
  Der Rest der Zeile einer Log-Meldung ist der eigentliche Text, mit dem das System bestimmte Informationen anzeigt. Im Fehlerfall ist h&auml;ufig ein Java Stack-Trace angef&uuml;gt, der eine genauere Ursachen-Forschung erm&ouml;glicht. <br />
  <br />
  <b>Wichtige Log-Meldungen</b><br />
  Neben den im Abschnitt "Starten und Stoppen von Tomcat" beschriebenen Log-Meldungen, die anzeigen, ob die Webapplikation
  ordnungsgem&auml;&szlig; gestartet wurde, geben nachfolgenden Log-Meldungen Aufschluss &uuml;ber die Abarbeitung von Anfragen.
  Die Annahme einer Anfrage wird beispielsweise angezeigt durch: 
<pre>
    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

</pre>
Die 1. Log-Meldung besagt, dass sich ein Benutzer an MOA-ID-AUTH angemeldet und eine eindeutige SessionID zugewiesen bekommen hat. <br />
  Die 2. Log-Meldung informiert dar&uuml;ber, dass die Anmeldedaten des Benutzers unter dem angezeigten SAML Artifakt abgeholt werden k&ouml;nnen.<br />
Wenn nun versucht wird, eine Transaktion mit einer ung&uumlltigen SessionID fortzusetzen erh&auml;lt man folgende Log-Meldung:<br />
<pre>
    ERROR | 09 09:34:27,105 | Thread-8 |
	at.gv.egovernment.moa.id.AuthenticationException:
	MOASessionID ist unbekannt
	(MOASessionID=-8650403497547200032)
</pre>
  <p>In diesem Fall gibt der mitgeloggte Stacktrace Auskunft
    &uuml;ber die Art des Fehlers. Der Aufrufer der MOA ID
    Webapplikation bekommt einen Fehlercode sowie eine kurze
    Beschreibung des Fehlers als Antwort zur&uuml;ck. <br />
    <br />
    Die Tats&auml;chlich &uuml;bertragenen Anfragen bzw. Antworten
    werden aus Effizienzgr&uuml;nden nur im Log-Level DEBUG
    angezeigt.</p>

</body>
</html>