<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
  <meta http-equiv="content-type" content="text/html; charset=iso-8859-1">
  <title>MOA-ID - Installation</title>
  <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="../index.html">MOA-ID (Identifikation) </a></p> 
<p class="subtitle">Installation</p> 
  <hr/>
  <h1>Inhalt</h1>
  <ol> 
    <li> 
      <p><a href="#uebersicht">&Uuml;bersicht</a></p> 
    </li> 
    <li> 
      <p><a href="#webservice">MOA-ID-Auth und MOA-ID-Configuration</a></p> 
      <ol> 
        <li><a href="#webservice_basisinstallation">Basisinstallation</a> 
          <ol> 
            <li><a href="#webservice_basisinstallation_einfuehrung">Einf&uuml;hrung</a></li> 
            <li><a href="#webservice_basisinstallation_installation">Installation</a> 
              <ol> 
                <li><a href="#webservice_basisinstallation_installation_vorbereitung">Vorbereitung</a></li> 
                <li><a href="#webservice_basisinstallation_installation_tomcatconfig">Konfiguration von Apache Tomcat</a> 
                  <ol> 
                    <li><a href="#webservice_basisinstallation_installation_tomcatconfig_httpconn">Konfiguration des HTTP Connectors</a></li> 
                    <li><a href="#webservice_basisinstallation_installation_tomcatconfig_httpsconn">Konfiguration des HTTPS Connectors</a></li> 
                  </ol> 
                </li> 
                <li><a href="#webservice_basisinstallation_installation_spssdeploy">Einsatz des Moduls MOA-ID-Auth in Tomcat</a></li>
                <li><a href="#moa_id_configuration_deploy">Einsatz des Moduls MOA-ID-Configuration in Tomcat</a></li> 
                <li><a href="#webservice_basisinstallation_installation_tomcatstartstop">Starten und Stoppen von Tomcat</a> 
                  <ol> 
                    <li><a href="#webservice_basisinstallation_installation_tomcatstartstop_windows">Unter Windows</a></li> 
                    <li><a href="#webservice_basisinstallation_installation_tomcatstartstop_unix">Unter Unix</a></li> 
                    <li><a href="#webservice_basisinstallation_installation_tomcatstartstop_verify">Pr&uuml;fen des erfolgreichen Starts</a> </li> 
                  </ol> 
                </li> 
                <li><a href="#webservice_basisinstallation_installation_changeonthefly">&Auml;nderung der Konfiguration im laufenden Betrieb</a></li> 
              </ol> 
            </li> 
            <li><a href="#webservice_basisinstallation_logging">Logging</a> 
              <ol> 
                <li><a href="#webservice_basisinstallation_logging_format">Format der Log-Meldungen</a></li> 
                <li><a href="#webservice_basisinstallation_logging_messages">Wichtige Log-Meldungen</a></li> 
              </ol> 
            </li> 
          </ol> 
        </li> 
        <li><a href="#webservice_erweiterungsmoeglichkeiten">Erweiterungsm&ouml;glichkeiten</a>          <ol> 
            <li><a href="#webservice_erweiterungsmoeglichkeiten_webserver">Vorgeschalteter Webserver</a>              <ol> 
                <li><a href="#webservice_erweiterungsmoeglichkeiten_webserver_iis">Microsoft Internet Information Server (MS IIS)</a>                  <ol> 
                    <li><a href="#webservice_erweiterungsmoeglichkeiten_webserver_iis_jk">Konfiguration von <span class="term"> mod_jk</span> im MS IIS</a></li> 
                    <li><a href="#webservice_erweiterungsmoeglichkeiten_webserver_iis_tomcat">Konfiguration von Tomcat</a></li> 
                    <li><a href="#webservice_erweiterungsmoeglichkeiten_webserver_iis_ssl">Konfiguration von SSL</a></li> 
                  </ol> 
                </li> 
                <li><a href="#webservice_erweiterungsmoeglichkeiten_webserver_apache">Apache</a>                  <ol> 
                    <li><a href="#webservice_erweiterungsmoeglichkeiten_webserver_apache_jk">Konfiguration von <span class="term"> mod_jk</span> im Apache </a></li> 
                    <li><a href="#webservice_erweiterungsmoeglichkeiten_webserver_apache_tomcat">Konfiguration von Tomcat</a></li> 
                    <li><a href="#webservice_erweiterungsmoeglichkeiten_webserver_apache_ssl">Konfiguration von SSL mit <span class="term">mod_SSL</span></a></li> 
                    </ol> 
                </li> 
                </ol>
            </li>
        </ol>
        </li>
    </ol>     
  </ol>
  <ol type="A">	
    <li><a href="#referenzierte_software">Referenzierte Software</a></li>
</ol>
  <hr/>
  <h1><a name="uebersicht" id="uebersicht"></a>1 &Uuml;bersicht</h1>
  <p>Die Module MOA-ID-Auth und MOA-ID-Configuration sind als plattformunabh&auml;ngige Module  ausgelegt. MOA-ID-Auth bietet Webservices &uuml;ber HTTPS zur Identifizierung und Authentifizierung an. Das Modul MOA-ID-Configuration stellt eine Weboberfl&auml;che zur Konfiguration des MOA-ID-Auth Modules zur Verf&uuml;gung.</p>
  <p>Dieses Handbuch beschreibt die Installation der beiden Module.</p>
<h1><a name="webservice"></a>2 MOA-ID-Auth und MOA-ID-Configuration</h1>
  <p>Dieser Abschnitt beschreibt die Installation von der Module MOA-ID-Auth und MOA-ID-Configuration. Im ersten Unterkapitel wird eine minimale Basisinstallation beschrieben. Das zweite Unterkapitel zeigt eine Reihe von optionalen Erweiterungsm&ouml;glichkeiten auf.</p>
  <h2><a name="webservice_basisinstallation" id="webservice_basisinstallation"></a>2.1 Basisinstallation</h2>
  <h3><a name="webservice_basisinstallation_einfuehrung" id="webservice_basisinstallation_einfuehrung"></a>2.1.1 Einf&uuml;hrung </h3>
  <p> Die Basisinstallation der Module MOA-ID-Auth und MOA-ID-Configuration stellt einerseits die minimalen Anforderungen f&uuml;r den Betrieb von MOA-ID dar, andererseits dient sie als Ausgangspunkt f&uuml;r optionale <a href="#webservice_erweiterungsmoeglichkeiten">Erweiterungsm&ouml;glichkeiten</a>.</p>
  <p>Die <strong>Mindestanforderungen</strong> f&uuml;r die Basisinstallation sind: </p>
  <ul>
    <li><a href="#referenziertesoftware">Java SE 5 oder h&ouml;her</a></li>
    <li><a href="#referenziertesoftware">Apache Tomcat 4.1.18 oder h&ouml;her </a></li>
  </ul>
  <p>Wir <strong>empfehlen</strong> jedoch jeweils aktuelle Version zu verwenden:</p>
  <ul>
    <li><a href="#referenziertesoftware">Java SE 6 (neuestes Update) bzw. Java SE Update SE 7 (neuestes Update)</a></li>
    <li><a href="#referenziertesoftware">Apache Tomcat 7.0.50 bzw. Apache Tomcat 8.0.3</a></li>
</ul>
  <p>In diesem Betriebs-Szenario wird das MOA-ID-Auth Webservice und das MOA-ID Konfigurationstool in Tomcat zum Einsatz gebracht. Beide Module k&ouml;nnen sowohl in derselben Tomcat-Instanz, als auch in separaten Tomcat-Instanzen betrieben werden. F&uuml;r den Fall des separaten Betriebs muss die Installation auf beiden Tomcat-Instanzen ausgef&uuml;hrt werden. In beiden F&auml;llen fungiert der Tomcat gleichzeitig als HTTP- und HTTPS-Endpunkt f&uuml;r beide Module. Beide Protokolle werden direkt in Tomcat konfiguriert, wobei MOA-ID-Auth und MOA-ID-Configuration Log4j als Logging Toolkit verwenden.</p>
<h3><a name="webservice_basisinstallation_installation" id="webservice_basisinstallation_installation"></a>2.1.2 Installation</h3>
<h4><a name="webservice_basisinstallation_installation_vorbereitung" id="webservice_basisinstallation_installation_vorbereitung"></a>2.1.2.1 Vorbereitung</h4>
<p>Die folgenden Schritte dienen der Vorbereitung der Installation.</p>
  <dl>
  <dt>Installation von Java SE</dt>
  <dd>Installieren Sie Java SE in ein beliebiges Verzeichnis.  Das Wurzelverzeichnis der Java SE Installation wird im weiteren Verlauf als <code>$JAVA_HOME</code> bezeichnet. </dd>
  <dt>Installation von Apache Tomcat</dt>
  <dd> Installieren Sie Apache Tomcat in ein Verzeichnis, das keine Leerzeichen im Pfadnamen enth&auml;lt. Verwenden Sie bitte die zu Ihrer Java SE passende Distribution von Tomcat. Das Wurzelverzeichnis der Tomcat-Installation wird im weiteren Verlauf als <code>$CATALINA_HOME</code> bezeichnet.</dd>
  <dt>Entpacken der MOA-ID-Auth Webservice Distribution</dt>
  <dd> Entpacken Sie die Datei <code>moa-id-auth-2.0.0.zip</code> in ein beliebiges Verzeichnis. Dieses Verzeichnis wird im weiteren Verlauf als <code>$MOA_ID_AUTH_INST</code> bezeichnet. </dd>
  <dt>Installation der  Kryptographiebibliotheken von SIC/IAIK</dt>
  <dd>
    <p>Kopieren Sie alle Dateien aus dem Verzeichnis <code>$MOA_SPSS_INST/ext</code> in das Verzeichnis <code>$JAVA_HOME/jre/lib/ext</code>. Zus&auml;tzlich m&uuml;ssen Sie die Rechtedateien Ihrer Java SE austauschen. Laden Sie dazu die passenden <span class="term">Unlimited Strength 
	  
	  
    Jurisdiction Policy Files</span> von der <a href="http://java.com/download" target="_blank">Java SE Downloadseite </a>und achten Sie darauf die f&uuml;r ihre verwendete Java SE Installation richtige Version zu nehmen. Anschlie&szlig;end folgen Sie der darin enthaltenen Installationsanweisung. </p>
  </dd>
  <dt>Installation einer Datenbank</dt>
  <dd>F&uuml;r den Betrieb von MOA-ID  2.0 wird eine Datenbank ben&ouml;tigt, wobei mySQL als Datenbank empfohlen wird (wurde  mit mySQL getestet). Der Einsatz eines alternativen Datenbanksystems ist jedoch  ebenfalls m&ouml;glich. F&uuml;r den Betrieb werden mindestens zwei getrennte Datenbank Schema  ben&ouml;tig, da die Konfiguration und die Session Informationen getrennt abgelegt  werden. Erstellen Sie zwei Datenbank Schemas welche von MOA-ID-Auth verwendet werden  sollen. Deren Namen k&ouml;nnen z.B. auf <em>moa-id-session</em> f&uuml;r Sessiondaten und <em>moa-id-config</em> f&uuml;r die Konfiguration lauten. Beliebige andere Namen f&uuml;r die Datenbank Schema sind  jedoch auch m&ouml;glich.
  </dd>
  </dl>
<h4><a name="webservice_basisinstallation_installation_tomcatconfig" id="webservice_basisinstallation_installation_tomcatconfig"></a>2.1.2.2 Konfiguration von Apache Tomcat</h4>
  <p>Die zentrale Konfigurations-Datei von Tomcat ist <code>$CATALINA_HOME/conf/server.xml</code>. Tomcat wird grunds&auml;tzlich mit einer funktionierenden Default-Konfiguration ausgeliefert. </p>
<h5><a name="webservice_basisinstallation_installation_tomcatconfig_httpconn" id="webservice_basisinstallation_installation_tomcatconfig_httpconn"></a>2.1.2.2.1 Konfiguration des HTTP Connectors</h5>
<p>Die Tomcat Default-Konfiguration schaltet ausschlie&szlig;lich den Connector f&uuml;r HTTP auf Port 8080 frei.  Wir empfehlen diese Konfiguration nur f&uuml;r F&auml;lle, in denen das MOA-ID-Configuration Modul in einer abgeschlossenen Netzwerkumgebung betrieben wird. Das Modul MOA-ID-Auth verlangt f&uuml;r Authentifizierunganfragen zwingend HTTPS.</p>
<h5><a name="webservice_basisinstallation_installation_tomcatconfig_httpsconn" id="webservice_basisinstallation_installation_tomcatconfig_httpsconn"></a>2.1.2.2.2 Konfiguration des HTTPS Connectors</h5>
  <p>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-Configuration verwendet werden.</p>
<p>F&uuml;r die dazu notwendige Konfiguration kann die im vorigen Abschnitt besprochene minimale Tomcat-Konfiguration als Ausgangspunkt verwendet werden: Zun&auml;chst ist der HTTP Connector abzuschalten (auskommentieren). Anschlie&szlig;end ist der HTTPS Connector zu konfigurieren. Das Dokument <a href="http://tomcat.apache.org/tomcat-7.0-doc/ssl-howto.html">Tomcat SSL Configuration HOW-TO </a> gibt einen guten &Uuml;berblick dazu. Grob zusammengefasst sind folgende Schritte durchzuf&uuml;hren: </p>
  <ul>
    <li>Erstellung eines <span class="term">Server-Keystores</span>, der den privaten Schl&uuml;ssel sowie das zugeh&ouml;rige Zertifikat des Webservices enth&auml;lt, mit dem es sich bei Aufbau einer SSL-Verbindung gegen&uuml;ber dem Kunden ausweist sowie das dazugeh&ouml;rige Server-Zertifikat enth&auml;lt. Sie k&ouml;nnen diesen Keystore z.B. mit <code>keytool</code> erstellen, einem Programm, das Ihrer Java SE beiliegt.</li>
    <li>Konfiguration des HTTPS Connectors in <code>$CATALINA_HOME/conf/server.xml</code>.</li>
    <li>Falls eine Client-Authentisierung gew&uuml;nscht ist, muss die Konfiguration   des SSL-Connectors in <code>$CATALINA_HOME/conf/server.xml</code> angepasst werden.</li>
  </ul>
<p>Die Konfiguration des HTTPS Connectors kann entfallen, wenn Tomcat ein Webserver vorgeschaltet ist, und dieser die SSL-Kommunikation mit dem Kunden &uuml;bernimmt (siehe <a href="#webservice_erweiterungsmoeglichkeiten_webserver">Abschnitt 2.2.1</a>).</p>
  <h5><a name="webservice_basisinstallation_installation_spssdeploy" id="webservice_basisinstallation_installation_spssdeploy"></a>2.1.2.3 Einsatz des Moduls MOA-ID-Auth in Tomcat</h5>
<p> Um die Module MOA-ID-Auth und MOA-ID-Configuratuion in Tomcat f&uuml;r den Einsatz vorzubereiten, sind folgende Schritte notwendig:</p>
<ul>
  <li>Die Datei <code>$MOA_ID_AUTH_INST/moa-id_auth.war</code> enth&auml;lt das einsatzfertige MOA-ID-Auth Webarchiv und muss ins Verzeichnis  <code>$CATALINA_HOME/webapps</code> kopiert werden. Dort wird sie beim ersten Start von Tomcat automatisch ins Verzeichnis <code>$CATALINA_HOME/webapps/moa-id-auth</code> entpackt. </li>
  <li>Die Konfigurationsdatei mit der Basiskonfiguration f&uuml;r MOA-ID-Auth  und die zugeh&ouml;rigen Verzeichnisse m&uuml;ssen in ein beliebiges Verzeichnis im Dateisystem kopiert werden (z.B. <code>$CATALINA_HOME/conf/moa-id</code>). Eine funktionsf&auml;hige Konfiguration, die als Ausgangspunkt f&uuml;r die Basiskonfiguration des MOA-ID-Auth Modules dienen kann, finden Sie <a href="../../../conf/moa-id/moa-id.properties">hier</a>. <br>
  </li>
  <li>  Die Dateien <code>xalan.jar</code>, <code>xercesImpl.jar, serializer.jar </code> und <code>xml-apis.jar</code> aus dem Verzeichnis <code>$MOA_ID_AUTH_INST/endorsed</code> m&uuml;ssen in das Tomcat-Verzeichnis <code>$CATALINA_HOME/endorsed</code> (bzw.  <code>$CATALINA_HOME/common/endorsed</code> bis Apache Tomcat Version 5.5) kopiert werden. Sind gleichnamige Dateien dort bereits vorhanden, m&uuml;ssen sie &uuml;berschrieben werden. Die ggf. in diesem Verzeichnis vorhandene Datei <code>xmlParserAPIs.jar</code> muss gel&ouml;scht werden. Sollte das Verzeichnis <code>endorsed</code> nicht vorhanden sein, dann muss dieses zuerst erstellt werden.</li>
  <li>Folgende <span class="term">System Properties</span> k&ouml;nnen gesetzt werden (wird beim Starten von Tomcat der <span class="term">Java Virtual Machine</span> in der Umgebungsvariablen <code>CATALINA_OPTS</code> in der Form <code>-D&lt;name&gt;=&lt;wert&gt;</code> &uuml;bergeben):
      <ul>
        <li id="klein"><code>moa.id.configuration</code>: Pfad und Name der Basiskonfigurationsdatei f&uuml;r MOA-ID-Auth. Eine beispielhafte Konfigurationsdatei fnden Sie <a href="../../../conf/moa-id/moa-id.properties">hier</a>. Wird ein relativer Pfad angegeben, wird dieser relativ zum Startverzeichnis der <span class="term">Java Virtual Machine</span> interpretiert.</li>
        <li><code>moa.spss.server.configuration</code>: Pfad und Name der zentralen Konfigurationsdatei f&uuml;r MOA SP/SS. Eine beispielhafte Konfigurationsdatei finden Sie <a href="../../../conf/moa-spss/SampleMOASPSSConfiguration.xml">hier</a>. Wird ein relativer Pfad angegeben, wird dieser relativ zum Startverzeichnis der <span class="term">Java Virtual Machine</span> interpretiert. Ist diese <span class="term">System Property</span> nicht gesetzt, wird automatisch eine im Webarchiv unter <code>WEB-INF/conf</code> enthaltene Default-Konfiguration herangezogen.</li>
        <li><code>eu.stork.samlengine.config.location</code>: Pfad auf den Ordner mit den zentralen Konfigurationsdateien f&uuml;r STORK. Die Beispielkonfiguration f&uuml;r das Modul MOA-ID-Auth enth&auml;lt bereits den<a href="../../../conf/moa-id/stork/"> Ordner f&uuml;r die STORK Konfiguration</a>. </li>
        <li id="klein"><code>log4j.configuration</code>: URL der Log4j Konfigurationsdatei. Eine beispielhafte Log4j-Konfiguration finden Sie <a href="../../../conf/moa-id/log4j.properties">hier</a>. Wird eine relative URL angegeben, wird diese als File-URL relativ zum Startverzeichnis der <span class="term">Java Virtual Machine</span> interpretiert. Ist diese <span class="term">System Property</span> nicht gesetzt, wird automatisch eine im Webarchiv unter <code>WEB-INF/classes</code> enthaltene Default-Konfiguration herangezogen.</li>
        <li id="klein"><code>javax.net.ssl.trustStore</code>: Pfad und Dateiname des <span class="term">Truststores</span> f&uuml;r vertrauensw&uuml;rdige SSL Client-Zertifikate (optional; nur, wenn SSL Client-Authentisierung durchgef&uuml;hrt werden soll). Ein relativer Pfad werden relativ zum Startverzeichnis der <span class="term">Java Virtual Machine</span> interpretiert.</li>
        <li id="klein"><code>javax.net.ssl.trustStorePassword</code>: Passwort f&uuml;r den <span class="term">Truststore</span> (optional; nur, wenn SSL Client-Authentisierung durchgef&uuml;hrt werden soll). </li>
        <li id="klein"><code>javax.net.ssl.trustStoreType</code>: Truststore-Typ (optional; nur, wenn SSL Client-Authentisierung durchgef&uuml;hrt werden soll). Je nach verwendetem Keystore-Typ muss <code>jks</code> (<span class="term">Java Key Store</span>) oder <code>pkcs12</code> (PKCS#12-Datei) angegeben werden.</li>
      </ul>
  </li>
</ul>
<h5><a name="moa_id_configuration_deploy" id="webservice_basisinstallation_installation_spssdeploy2"></a>2.1.2.4 Einsatz des Moduls MOA-ID-Configuration in Tomcat</h5>
<ul>
  <li>Die Datei <code>$MOA_ID_AUTH_INST/moa-id_configuration.war</code> enth&auml;lt das einsatzfertige MOA-ID-Configuration Webarchiv und muss ins Verzeichnis <code>$CATALINA_HOME/webapps</code> kopiert werden. Dort wird sie beim ersten Start von Tomcat automatisch ins Verzeichnis <code>$CATALINA_HOME/webapps/moa-id-configuration</code> entpackt. </li>
  <li>Die Konfigurationsdatei mit der Basiskonfiguration f&uuml;r MOA-ID-Auth  und die zugeh&ouml;rigen Verzeichnisse m&uuml;ssen in ein beliebiges Verzeichnis im Dateisystem kopiert werden (z.B. <code>$CATALINA_HOME/conf/moa-id-configuration</code>). Eine funktionsf&auml;hige Konfiguration, die als Ausgangspunkt f&uuml;r die Basiskonfiguration des MOA-ID-Auth Modules dienen kann, finden Sie <a href="../../../conf/moa-id-configuration/moa-id-configtool.properties">hier</a>. <br>
  </li>
  <li> Die Dateien <code>xalan.jar</code>, <code>xercesImpl.jar, serializer.jar </code> und <code>xml-apis.jar</code> aus dem Verzeichnis <code>$MOA_ID_AUTH_INST/endorsed</code> m&uuml;ssen in das Tomcat-Verzeichnis <code>$CATALINA_HOME/endorsed</code> (bzw. <code>$CATALINA_HOME/common/endorsed</code> bis Apache Tomcat Version 5.5) kopiert werden. Sind gleichnamige Dateien dort bereits vorhanden, m&uuml;ssen sie &uuml;berschrieben werden. Die ggf. in diesem Verzeichnis vorhandene Datei <code>xmlParserAPIs.jar</code> muss gel&ouml;scht werden. Sollte das Verzeichnis <code>endorsed</code> nicht vorhanden sein, dann muss dieses zuerst erstellt werden.</li>
  <li>Folgende <span class="term">System Properties</span> k&ouml;nnen gesetzt werden (wird beim Starten von Tomcat der <span class="term">Java Virtual Machine</span> in der Umgebungsvariablen <code>CATALINA_OPTS</code> in der Form <code>-D&lt;name&gt;=&lt;wert&gt;</code> &uuml;bergeben):
    <ul>
      <li><code>moa.id.webconfig</code>: Pfad und Name der Basiskonfigurationsdatei f&uuml;r MOA-ID-Configuration. Eine beispielhafte Konfigurationsdatei fnden Sie <a href="../../../conf/moa-id-configuration/moa-id-configtool.properties">hier</a>. Wird ein relativer Pfad angegeben, wird dieser relativ zum Startverzeichnis der <span class="term">Java Virtual Machine</span> interpretiert.</li>
      <li><code>log4j.configuration</code>: URL der Log4j Konfigurationsdatei. Eine beispielhafte Log4j-Konfiguration finden Sie <a href="../../../conf/moa-id/log4j.properties">hier</a>. Wird eine relative URL angegeben, wird diese als File-URL relativ zum Startverzeichnis der <span class="term">Java Virtual Machine</span> interpretiert. Ist diese <span class="term">System Property</span> nicht gesetzt, wird automatisch eine im Webarchiv unter <code>WEB-INF/classes</code> enthaltene Default-Konfiguration herangezogen.</li>
      <li><code>javax.net.ssl.trustStore</code>: Pfad und Dateiname des <span class="term">Truststores</span> f&uuml;r vertrauensw&uuml;rdige SSL Client-Zertifikate (optional; nur, wenn SSL Client-Authentisierung durchgef&uuml;hrt werden soll). Ein relativer Pfad werden relativ zum Startverzeichnis der <span class="term">Java Virtual Machine</span> interpretiert.</li>
      <li><code>javax.net.ssl.trustStorePassword</code>: Passwort f&uuml;r den <span class="term">Truststore</span> (optional; nur, wenn SSL Client-Authentisierung durchgef&uuml;hrt werden soll). </li>
      <li><code>javax.net.ssl.trustStoreType</code>: Truststore-Typ (optional; nur, wenn SSL Client-Authentisierung durchgef&uuml;hrt werden soll). Je nach verwendetem Keystore-Typ muss <code>jks</code> (<span class="term">Java Key Store</span>) oder <code>pkcs12</code> (PKCS#12-Datei) angegeben werden.</li>
    </ul>
  </li>
</ul>
<h4><a name="webservice_basisinstallation_installation_tomcatstartstop" id="webservice_basisinstallation_installation_tomcatstartstop"></a>2.1.2.4 Starten und Stoppen von Tomcat</h4>
<h5><a name="webservice_basisinstallation_installation_tomcatstartstop_windows" id="webservice_basisinstallation_installation_tomcatstartstop_windows"></a>2.1.2.4.1 Unter Windows</h5>
<div id="block">
  <p>Das Verzeichnis <code>$MOA_IA_AUTH_INST/tomcat/win32</code> enth&auml;lt Script-Dateien zum Starten und Stoppen von Tomcat. Vor der erstmaligen Verwendung der Scripts m&uuml;ssen in den ersten Zeilen die Umgebungsvariablen <code>JAVA_HOME</code> (Basisverzeichnis der eingesetzten Java SE) und <code>CATALINA_HOME</code> (Basisverzeichnis der eingesetzten Tomcat-Installation) angepasst werden. Evtl. m&uuml;ssen Sie auch noch die in den Script-Dateien gesetzten, in Abschnitt 2.1.2.3 besprochenen <span class="term">System Properties</span> anpassen. </p>
</div>
<h5><a name="webservice_basisinstallation_installation_tomcatstartstop_unix" id="webservice_basisinstallation_installation_tomcatstartstop_unix"></a>2.1.2.4.2 Unter Unix</h5>
<p>Zun&auml;chst m&uuml;ssen die  in Abschnitt 2.1.2.3 besprochenen <span class="term">System Properties</span> mit Hilfe der Umgebungsvariablen <code>CATALINA_OPTS</code> gesetzt sein. Die Datei <code>$MOA_ID_AUTH_INST/tomcat/unix/moa-env.sh</code> enth&auml;lt ein Beispiel daf&uuml;r. Des weiteren m&uuml;ssen noch die Umgebungsvariablen <code>JAVA_HOME</code> (Basisverzeichnis der eingesetzten Java SE) und <code>CATALINA_HOME</code> (Basisverzeichnis der eingesetzten Tomcat-Installation) angepasst werden.</p>
<p>Nun kann Tomcat aus seinem Basisverzeichnis mit </p>
<pre>bin/catalina.sh start</pre>
gestartet werden. Das Stoppen von Tomcat erfolgt analog mit
<pre>bin/catalina.sh stop</pre>
<h5><a name="webservice_basisinstallation_installation_tomcatstartstop_verify" id="webservice_basisinstallation_installation_tomcatstartstop_verify"></a>2.1.2.4.3 Pr&uuml;fen des erfolgreichen Starts </h5>
<div id="block">
  <p>Ein erfolgreicher Start des MOA-ID-Auth Modules ist an folgender Log-Meldung ersichtlich: <br>
  </p>
</div>
<pre>32131 [localhost-startStop-1] INFO moa.id.auth  - MOA ID Authentisierung wurde erfolgreich gestartet 
32131 [localhost-startStop-1] INFO moa.id.auth  - Dispatcher Servlet initialization finished.</pre>
<p>Analog bei MOA-ID-Configuration</p>
<pre>INFO at.gv.egovernment.moa.id.configuration.config.ConfigurationProvider  - MOA-ID-Configuration initialization completed</pre>
<p>Bei leichten Fehlern in der Konfiguration geben <code>WARN</code> Log-Meldungen unmittelbar davor Aufschluss &uuml;ber fehlerhafte Konfigurations-Eintr&auml;ge.
  Nach dem Starten von Tomcat stehen MOA-ID-Auth und MOA-ID-Configuration zur Verf&uuml;gung. Die Einsprungpunkte der unterschiedlichen Authentifizierungsprotokolle von MOA-ID-Auth werden im Abschnitt <a href="../protocol/protocol.html">Protokolle</a> im Detail beschrieben.</p>
<pre>
http://&lt;host&gt;:&lt;port&gt;/moa-id-auth/
http://&lt;host&gt;:&lt;port&gt;/moa-id-configuration/</pre>
<p>bzw.
</p>
<pre>
https://&lt;host&gt;:&lt;port&gt;/moa-id-auth/
https://&lt;host&gt;:&lt;port&gt;/moa-id-configuration/</pre>
<p>Die Verf&uuml;gbarkeit des Services k&ouml;nnen Sie einfach &uuml;berpr&uuml;fen, indem Sie die Endpunkte mit einem Web-Browser aufgerufen; dies sollte nach erfolgreichem Start zur Anzeige einer Informationsseite f&uuml;hren. </p>
<h4><a name="webservice_basisinstallation_logging" id="webservice_basisinstallation_logging"></a>2.1.3 Logging </h4>
<p>Beide Module verwenden <a href="#referenziertesoftware">Log4j</a> 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 Log4j Handbuch  beschrieben sind. Unter anderem gibt es die M&ouml;glichkeit, folgende Einstellungen vorzunehmen:
<ul>
      <li id="klein">
        <p>Das verwendete Log-Level (<code>DEBUG</code>, <code>INFO</code>, <code>WARN</code>, <code>ERROR</code>, <code>FATAL</code>);</p>
      </li>
      <li id="klein">
        <p>Name und maximale Gr&ouml;&szlig;e der Log-Datei(en);</p>
      </li>
      <li id="klein">
        <p>Das Aussehen der Log-Eintr&auml;ge.</p>
      </li>
</ul>
    <p>Hierbei wird folgende Log-Hierarchien verwendet: </p>
<ul>
    <li>
      <p><code>at.gv.egovernment.moa.id.configuration</code> f&uuml;r alle Log-Meldungen aus MOA-ID-Configuration</p>
    </li>
    <li><code>moa.id.auth</code> f&uuml;r alle Log-Meldungen aus MOA-ID-Auth </li>
    <li>
      <p><code>moa.spss.server</code> f&uuml;r alle Log-Meldungen aus dem MOA/SPSS </p>
    </li>
    <li>
      <p><code>iaik.server</code> f&uuml;r alle Log-Meldungen aus den SIC/IAIK Kryptographie-Modulen. </p>
    </li>
</ul>
<p>Eine f&uuml;r beide Module passende Konfigurationsdatei f&uuml;r Log4j finden Sie <a href="../../../conf/moa-spss/log4j.properties">hier</a>. Wird diese Datei als Logging-Konfiguration verwendet, so werden alle Log-Meldungen sowohl in die Konsole, als auch in die Dateien <code>moa-id-auth.log</code> und <code>moa-id-configuration.log</code> geschrieben. </p>
  <h4><a name="webservice_basisinstallation_logging_format" id="webservice_basisinstallation_logging_format"></a>2.1.3.1 Format der Log-Meldungen</h4>
      <p> Anhand einer konkreten Log-Meldung wird das Format der MOA SP/SS Log-Meldungen erl&auml;utert:      </p>
      <pre>
INFO | 01 21:25:26,540 | Thread-3 | TID=1049225059594-100 NID=node1 
  MSG=Starte neue Transaktion: TID=1049225059594-100, Service=SignatureVerification
</pre>
<p>    Der Wert <code>INFO</code> besagt, dass die Log-Meldung im Log-Level <code>INFO</code> entstanden ist. Folgende Log-Levels existieren:</p>
    <ul>
      <li>
        <p><code>DEBUG</code>: Log-Meldungen im Log-Level <code>DEBUG</code> geben Auskunft &uuml;ber die innere Arbeitsweise des Systems. Sie sind haupts&auml;chlich f&uuml;r Entwickler interessant.</p>
      </li>
      <li>
        <p><code>INFO</code>: Diese Log-Meldungen geben Status-Informationen &uuml;ber den Ablauf des Webservices, wie z.B. &uuml;ber das Einlangen einer neuen Anfrage.</p>
      </li>
      <li>
        <p><code>WARN</code>: Bei der Ausf&uuml;hrung einer Anfrage sind leichte Fehler aufgetreten. Der Ablauf des Webservices ist nicht weiter beeintr&auml;chtigt.</p>
      </li>
      <li>
        <p><code>ERROR</code>: Die Ausf&uuml;hrung einer Anfrage musste abgebrochen werden. Das Webservice ist davon nicht beeintr&auml;chtigt. </p>
      </li>
      <li>
        <p><code>FATAL</code>: Es ist ein Fehler aufgetreten, der den weiteren Betrieb des Webservices nicht mehr erlaubt.</p>
      </li>
    </ul>
    <p>Der n&auml;chste Wert <code>01 21:25:26,540</code> gibt den Zeitpunkt an, zu dem die Log-Meldung generiert wurde (in diesem Fall den 1. Tag im aktuellen Monat, sowie die genaue Uhrzeit). </p>
    <p>      Der Wert <code>Thread-3</code> bezeichnet den Thread, von dem die Anfrage bearbeitet wird.</p>
    <p>      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.</p>
<h4>      <a name="webservice_basisinstallation_logging_messages" id="webservice_basisinstallation_logging_messages"></a>2.1.3.2 Wichtige Log-Meldungen</h4>
    <p>      Neben den im Abschnitt <a href="#webservice_basisinstallation_installation_tomcatstartstop_verify">2.1.2.4.3</a> beschriebenen Log-Meldungen, die anzeigen, ob das Service ordnungsgem&auml;&szlig; gestartet wurde, geben nachfolgenden Log-Meldungen Aufschluss &uuml;ber die Abarbeitung von Anfragen. </p>
    <p>Die Entgegennahme einer Anfrage wird angezeigt durch:
      
  </p>
    <pre>125690 [ajp-bio-129.27.142.119-38609-exec-1] INFO moa.id.auth  - REQUEST: /moa-id-auth/dispatcher
125690 [ajp-bio-129.27.142.119-38609-exec-1] INFO moa.id.auth  - QUERY  : mod=id_pvp2x&amp;action=Post&amp;</pre>
<p>Ein Fehler beim Abarbeiten der Anfrage wird angezeigt durch:  
<pre>2435298 [ajp-bio-129.27.142.119-38609-exec-10] ERROR moa.id.auth  - Failed to generate a valid protocol request!</pre>
  <div id="block">
    <p>In diesem Fall gibt der mitgeloggte Stacktrace Auskunft &uuml;ber die Art des Fehlers.</p>
    <p> Die tats&auml;chlich &uuml;bertragenen Anfragen bzw. Antworten werden aus Effizienzgr&uuml;nden nur im Log-Level <code>DEBUG</code> angezeigt. </p>
  </div>
  <h2><a name="webservice_erweiterungsmoeglichkeiten" id="webservice_erweiterungsmoeglichkeiten"></a>2.2 Erweiterungsm&ouml;glichkeiten</h2>
<p>Ausgehend von der <a href="#webservice_basisinstallation">Basisinstallation</a> k&ouml;nnen die optionalen Erweiterungen, die in den nachfolgenden Abschnitten beschrieben werden, unabh&auml;ngig und in beliebiger Kombination aufgesetzt werden.</p>
<h3><a name="webservice_erweiterungsmoeglichkeiten_webserver" id="webservice_erweiterungsmoeglichkeiten_webserver"></a>2.2.1 Vorgeschalteter Webserver</h3>
<h4><a name="webservice_erweiterungsmoeglichkeiten_webserver_iis" id="webservice_erweiterungsmoeglichkeiten_webserver_iis"></a>2.2.1.1 Microsoft Internet Information Server (MS IIS) </h4>
  <p>Den MOA SP/SS Webservices kann optional ein MS IIS vorgeschaltet sein. In diesem Fall &uuml;bernimmt der MS IIS die HTTP- bzw. HTTPS-Kommunikation mit dem Aufrufer des Webservices. Die Kommunikation zwischen MS IIS und dem in Tomcat eingerichteten MOA-ID Modulen wird durch <span class="term">mod_jk</span> durchgef&uuml;hrt. Die angef&uuml;hrten Konfigurationsschritte gehen von einer MS IIS Standard-Installation aus.</p>
  <h5><a name="webservice_erweiterungsmoeglichkeiten_webserver_iis_jk" id="webservice_erweiterungsmoeglichkeiten_webserver_iis_jk"></a>2.2.1.1.1 Konfiguration von <span class="term">mod_jk</span> im MS IIS</h5>
  <p>    F&uuml;r die Kommunikation des MS IIS mit dem im Tomcat eingerichteten MOA SP/SS Webservice wird das <span class="term">ISAPI</span>-Modul von <span class="term">mod_jk</span> im MS IIS installiert und konfiguriert. Eine detaillierte Installations- und Konfigurationsanleitung gibt das <span class="term"><a href="http://tomcat.apache.org/connectors-doc/webserver_howto/iis.html" target="_blank">mod_jk</a></span><a href="http://tomcat.apache.org/connectors-doc/webserver_howto/iis.html" target="_blank"> IIS HowTo</a>. Beispiele f&uuml;r <code>workers.properties</code> und <code>uriworkermap.properties</code> Dateien liegen im Verzeichnis <code>$MOA_ID_AUTH_INST/tomcat</code> bei.</p>
  <h5><a name="webservice_erweiterungsmoeglichkeiten_webserver_iis_tomcat" id="webservice_erweiterungsmoeglichkeiten_webserver_iis_tomcat"></a>2.2.1.1.2 Konfiguration von Tomcat</h5>
  <p>Damit Tomcat die Aufrufe entgegennehmen kann, die von MS IIS mittels <span class="term"> mod_jk</span> weiterleitet werden,  muss in <code>$CATALINA_HOME/conf/server.xml</code> der <span class="term">AJP  Connector</span> aktiviert werden. Im Gegenzug k&ouml;nnen die Konnektoren f&uuml;r HTTP und HTTPS deaktiviert werden. Das geschieht am einfachsten durch Ein- bzw. Auskommentieren der entsprechenden <code>Connector</code> Konfigurations-Elemente in dieser Datei.</p>
<h5><a name="webservice_erweiterungsmoeglichkeiten_webserver_iis_ssl" id="webservice_erweiterungsmoeglichkeiten_webserver_iis_ssl"></a>2.2.1.1.3 Konfiguration von SSL</h5>
  <p>    Die Dokumentation zum Einrichten von SSL auf dem MS IIS steht nach Installation des IIS unter http://localhost/iisHelp/ oder aber auch auf den Webseiten von Mircrosoft zur Verf&uuml;gung. </p>
  <h4><a name="webservice_erweiterungsmoeglichkeiten_webserver_apache" id="webservice_erweiterungsmoeglichkeiten_webserver_apache"></a>2.2.1.2 Apache</h4>
  <p>Den MOA SP/SS Webservices kann ein Apache Webserver vorgeschaltet sein. Das Prinzip funktioniert wie bei MS IIS, auch hier wird <span class="term"> mod_jk</span> f&uuml;r die Kommunikation zwischen Webserver und Tomcat eingesetzt. Die angef&uuml;hrten Konfigurationsschritte gehen von einer Standard-Installation des Apache Webservers aus.</p>
  <h5><a name="webservice_erweiterungsmoeglichkeiten_webserver_apache_jk" id="webservice_erweiterungsmoeglichkeiten_webserver_apache_jk"></a>2.2.1.2.1 Konfiguration von <span class="term"> mod_jk</span> im Apache </h5>
  <p>Um die MOA-ID Module hinter einem Apache Webserver zu betreiben, ist die Konfiguration des Apache-Moduls <span class="term">mod_jk</span> erforderlich. Eine detaillierte Installations- und Konfigurationsanleitung gibt das <span class="term"><a href="http://tomcat.apache.org/connectors-doc/webserver_howto/apache.html" target="_blank">mod_jk</a></span><a href="http://tomcat.apache.org/connectors-doc/webserver_howto/apache.html" target="_blank"> Apache HowTo</a>. Ein Beispiel f&uuml;r eine <code>workers.properties</code> Datei liegt im Verzeichnis <code>$MOA_ID_AUTH_INST/tomcat</code> bei.</p>
  <p>Um die MOA-ID Module dem Apache Webserver bekannt zu machen, sind zumindest folgende Eintr&auml;ge im globalen Kontext der Apache-Konfigurationsdatei notwendig:</p>
<pre>LoadModule jk_module /usr/lib/apache/mod_jk.so<br>AddModule jk_module<br>JkOptions +ForwardKeySize +ForwardURICompat -ForwardDirectories<br>JkWorkersFile conf/workers.properties <br>JkMount /moa-spss/* moaworker </pre>
  <p>Die Pfad- und Dateinamen k&ouml;nnen je nach existierender Apache Installation geringf&uuml;gig variieren.</p>
  <h5><a name="webservice_erweiterungsmoeglichkeiten_webserver_apache_tomcat" id="webservice_erweiterungsmoeglichkeiten_webserver_apache_tomcat"></a>2.2.1.2.2 Konfiguration von Tomcat</h5>
  <p>Die Konfiguration von Tomcat ist analog zu Abschnitt <a href="#webservice_erweiterungsmoeglichkeiten_webserver_iis_tomcat">2.2.1.1.2</a> durchzuf&uuml;hren.</p>
  <h5><a name="webservice_erweiterungsmoeglichkeiten_webserver_apache_ssl" id="webservice_erweiterungsmoeglichkeiten_webserver_apache_ssl"></a>2.2.1.2.2 Konfiguration von SSL mit <span class="term">mod_SSL</span></h5>
  <p>Apache kann in Verbindung mit <span class="term">mod_SSL</span> als SSL-Endpunkt f&uuml;r die MOA-ID Module fungieren. In diesem Fall entf&auml;llt die SSL-Konfiguration in Tomcat, da Apache und Tomcat auch im Fall von SSL Daten via <span class="term">mod_jk</span> austauschen. Eine detaillierte Installations- und Konfigurationsanleitung  enth&auml;lt die <a href="http://www.modssl.org/docs/" target="_blank">Online-Dokumentation</a> von <span class="term">mod_SSL</span>.</p>
<p>Bei der Verwendung von Client-Authentisierung muss darauf geachtet werden, dass <span class="term">mod_ssl</span> die HTTP-Header mit den Informationen &uuml;ber das Client-Zertifikat exportiert. Dies wird durch Angabe der folgenden Option in der Apache-Konfiguration erreicht: </p>
  <pre>SSLOptions +ExportCertData +StdEnvVars</pre>
    <p>Je nach vorhandener SSL-Konfiguration des Apache Webservers kann diese Option im globalen Kontext, im Kontext des Virtual Hosts oder im Kontext eines Verzeichnisses spezifiziert werden.</p>
<h1><a name="referenzierte_software"></a>A Referenzierte Software</h1>
<p>Auf folgende Software-Pakete wird in diesem Handbuch verwiesen:</p>
<table class="fixedWidth"  border="1" cellpadding="2">
  <tr>
    <th scope="col">Name</th>
    <th scope="col">Beschreibung</th>
  </tr>
  <tr>
    <td><a href="http://jakarta.apache.org/tomcat/index.html" target="_blank">Apache Tomcat </a></td>
    <td>Apache Tomcat Servlet-Container</td>
  </tr>
  <tr>
    <td><a href="http://java.com/" target="_blank">Java SE</a></td>
    <td>Java Standard Edition (Software Development Kit bzw. Java Runtime Environment) </td>
  </tr>
  <tr>
    <td><a href="http://logging.apache.org/log4j/1.2/" target="_blank"> Log4J </a></td>
    <td>Logging Framework </td>
  </tr>
</table>

</body>
</html>