update handbook

author: Thomas Lenz <tlenz@iaik.tugraz.at> 2019-06-12 13:47:10 +0200
committer: Thomas Lenz <tlenz@iaik.tugraz.at> 2019-06-12 13:47:10 +0200
commit: b232b84093993571da6efa97c25e1724370d6a6d (patch)
tree: 6a9aa50957d867413659b2f079f7fa84f3add1d9 /id/server/doc/handbook_v4/moduledevinfo/moduledevinfo.html
parent: d7b6e57eeb37ef02ceadfe51ca730bccbed939c6 (diff)
download: moa-id-spss-b232b84093993571da6efa97c25e1724370d6a6d.tar.gz
moa-id-spss-b232b84093993571da6efa97c25e1724370d6a6d.tar.bz2
moa-id-spss-b232b84093993571da6efa97c25e1724370d6a6d.zip
1 files changed, 388 insertions, 0 deletions
diff --git a/id/server/doc/handbook_v4/moduledevinfo/moduledevinfo.html b/id/server/doc/handbook_v4/moduledevinfo/moduledevinfo.html
new file mode 100644
index 000000000..28e4f1bb4
--- /dev/null
+++ b/id/server/doc/handbook_v4/moduledevinfo/moduledevinfo.html
@@ -0,0 +1,388 @@
+<!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 - Informationen f&uuml;r Modul-Entwickler</title>
+	<link rel="stylesheet" href="../common/MOA.css" type="text/css">
+	<style type="text/css">
+	span {
+		font-family: 'Courier New';
+		font-size: 10pt;
+		color: #000000;
+	}
+	.sc0 {
+		font-weight: bold;
+	}
+	.sc1, .sc12, .sc13 {
+		color: #0000FF;
+	}
+	.sc3 {
+		color: #FF0000;
+	}
+	.sc6 {
+		font-weight: bold;
+		color: #8000FF;
+	}
+	.sc8 {
+	}
+	.sc9 {
+		color: #008000;
+	}
+	.sc11 {
+		color: #0000FF;
+	}
+	table {
+		border-collapse: collapse;
+	}
+	table, th, td {
+		border: thin solid gray;
+	}
+	</style>
+</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">Informationen f&uuml;r Modul-Entwickler</p>
+	<hr />
+
+
+	<h1>Inhalt</h1>
+	<ol>
+		<li>
+			<p>
+				<a href="#uebersicht">&Uuml;bersicht</a>
+			</p>
+		</li>
+		<li>
+			<p>
+				<a href="#prozesse">Prozesse</a>
+			</p>
+			<ol>
+				<li><a href="#tasks">Aufgaben (Tasks)</a></li>
+				<li><a href="#transitions">Transitions</a></li>
+			</ol>
+		</li>
+		<li>
+			<p>
+				<a href="#module">Module</a>
+			</p>
+			<ol>
+				<li><a href="#processselection">Metadaten und Prozessauswahl</a></li>
+				<li>
+					<p>
+						<a href="#discovery">Discovery</a>
+					</p>
+					<ol>
+						<li><a href="#serviceloader">Service Loader Mechanismus</a></li>
+						<li><a href="#springbean">Spring Bean Discovery</a></li>
+					</ol>
+				</li>
+			</ol>
+		</li>
+		<li>
+			<p>
+				<a href="#hinweise">Hinweise</a>
+			</p>
+		</li>
+	</ol>
+	<hr />
+
+
+	<h1>
+		<a name="uebersicht" id="uebersicht">1 &Uuml;bersicht</a>
+	</h1>
+	<p>
+		MOA-ID ab Version 2.2 erm&ouml;glicht die dynamische Erweiterung um zus&auml;tzliche Funktionalit&auml;t durch die Nutzung der
+		integrierten Modularchitektur.<br/>
+		Entwickler k&ouml;nnen nun eigene Prozesse, um die MOA-ID erweitert werden soll, definieren (z.B. Unterst&uuml;tzung
+		eines speziellen Authentifizierungsworkflows, Erweiterung um Vollmachten oder ausl&auml;ndische Identit&auml;ten etc).
+		MOA-ID bietet eine Ablaufsteuerung (&quot;ProcessEngine&quot;), die einzelne Aufgaben (Tasks) entsprechend einer vorgegebenen Prozessdefinition
+		abarbeiten kann.
+	</p>
+	<p>
+		Mehrere Prozesse k&ouml;nnen zu einzelnen Modulen zusammengefasst werden. Ein Modul, typischerweise repr&auml;sentiert durch eine separate JAR-Datei, wird	automatisch erkannt, sobald sich
+		dieses im Classpath der Anwendung befindet. Damit stehen die in diesem Modul definierten Prozesse MOA-ID
+		automatisch zu Verf&uuml;gung.
+	</p>
+	<p>
+		Beim Starten eines Authentifizierungsvorgangs speichert MOA-ID die zu diesem Zeitpunkt zu Verf&uuml;gung stehenden
+		Informationen (Ergebnis der BKU-Auswahl, Auswahl des Herkunftslandes, Wunsch nach Vollmachten-Nutzung etc.) in
+		eine Datenstruktur (&quot;ExecutionContext&quot;). Module	entscheiden dann auf Basis dieser Informationen, ob sie entsprechende Prozesse f&uuml;r den gegebenen Kontext anbieten k&ouml;nnen. Sobald ein
+		passender Prozess gefunden wurde, beginnt die MOA-ID ProcessEngine mit der Ausf&uuml;hrung der darin definierten
+		Aufgaben.
+	</p>
+	<p>
+		Bei diesen Aufgaben handelt es sich typischerweise um einzelne synchrone oder asynchrone Schritte eines kompletten
+		Authentifizierungsvorgangs wie z.B. das Erstellen eines HTML-Formulars zum Auslesen der Personenbindung (synchron),
+		das Empfangen und Verarbeiten einer	Personenbindung (asynchron), das Aushandeln einer Session mit dem Vollmachtenportal (synchron) etc.
+		Jeder Task erh&auml;lt bei Ausf&uuml;hrung automatisch Zugriff auf den ExecutionContext, der von Task zu Task weitergereicht, zum Austausch bzw. Akkumulieren von Daten dient und schlie&szlig;lich auch persistiert wird.
+		Dar&uuml;ber hinaus steht jeweils HttpServletRequest und HttpServletResponse zu Verf&uuml;gung.
+	</p>
+
+	<h1>
+		<a name="prozesse" id="prozesse">2 Prozesse</a>
+	</h1>
+	<p>
+		Ein Prozess definiert sich prim&auml;r &uuml;ber seine Tasks, die es in einer bestimmten Abfolge abzuarbeiten gilt. Um welche Tasks es sich handelt und wie die Abfolge unter welchen Bedingungen aussieht wird in einer
+		ProzessDefinition in Form eines XML-Dokuments festgelegt. 
+	</p>
+	<p>Siehe <a href="ProcessDefinition.xsd">ProcessDefinition.xsd</a>.<br/>&nbsp;</p>
+	
+	<p>
+		Die folgende Prozessdefinition zeigt als Beispiel den internen Standard-Authentifizierungsprozess von MOA-ID. Dieser unterst&uuml;tzt Vollmachten uns ausl&auml;ndische Identit&auml;ten:<br/>&nbsp;
+	</p>
+	<div style="float: left; white-space: pre; line-height: 1; background: #FFFFFF; "><span class="sc1">&lt;?xml</span><span class="sc8"> </span><span class="sc3">version</span><span class="sc8">=</span><span class="sc6">"1.0"</span><span class="sc8"> </span><span class="sc3">encoding</span><span class="sc8">=</span><span class="sc6">"UTF-8"?&gt;</span><span class="sc0">
+</span><span class="sc1">&lt;pd:ProcessDefinition</span><span class="sc8"> </span><span class="sc3">id</span><span class="sc8">=</span><span class="sc6">"DefaultAuthentication"</span><span class="sc8"> </span><span class="sc3">xmlns:pd</span><span class="sc8">=</span><span class="sc6">"http://reference.e-government.gv.at/namespace/moa/process/definition/v1"</span><span class="sc1">&gt;</span><span class="sc0">
+
+    </span><span class="sc1">&lt;pd:Task</span><span class="sc8"> </span><span class="sc3">id</span><span class="sc8">=</span><span class="sc6">"createIdentityLinkForm"</span><span class="sc8">    </span><span class="sc3">class</span><span class="sc8">=</span><span class="sc6">"at.gv.egovernment.moa.id.auth.modules.internal.tasks.CreateIdentityLinkFormTask"</span><span class="sc8"> </span><span class="sc11">/&gt;</span><span class="sc0">
+    </span><span class="sc1">&lt;pd:Task</span><span class="sc8"> </span><span class="sc3">id</span><span class="sc8">=</span><span class="sc6">"verifyIdentityLink"</span><span class="sc8">        </span><span class="sc3">class</span><span class="sc8">=</span><span class="sc6">"at.gv.egovernment.moa.id.auth.modules.internal.tasks.VerifyIdentityLinkTask"</span><span class="sc8">        </span><span class="sc3">async</span><span class="sc8">=</span><span class="sc6">"true"</span><span class="sc8"> </span><span class="sc11">/&gt;</span><span class="sc0">
+    </span><span class="sc1">&lt;pd:Task</span><span class="sc8"> </span><span class="sc3">id</span><span class="sc8">=</span><span class="sc6">"verifyAuthBlock"</span><span class="sc8">           </span><span class="sc3">class</span><span class="sc8">=</span><span class="sc6">"at.gv.egovernment.moa.id.auth.modules.internal.tasks.VerifyAuthenticationBlockTask"</span><span class="sc8"> </span><span class="sc3">async</span><span class="sc8">=</span><span class="sc6">"true"</span><span class="sc8"> </span><span class="sc11">/&gt;</span><span class="sc0">
+    </span><span class="sc1">&lt;pd:Task</span><span class="sc8"> </span><span class="sc3">id</span><span class="sc8">=</span><span class="sc6">"verifyCertificate"</span><span class="sc8">         </span><span class="sc3">class</span><span class="sc8">=</span><span class="sc6">"at.gv.egovernment.moa.id.auth.modules.internal.tasks.VerifyCertificateTask"</span><span class="sc8">         </span><span class="sc3">async</span><span class="sc8">=</span><span class="sc6">"true"</span><span class="sc8"> </span><span class="sc11">/&gt;</span><span class="sc0">
+    </span><span class="sc1">&lt;pd:Task</span><span class="sc8"> </span><span class="sc3">id</span><span class="sc8">=</span><span class="sc6">"getMISSessionID"</span><span class="sc8">           </span><span class="sc3">class</span><span class="sc8">=</span><span class="sc6">"at.gv.egovernment.moa.id.auth.modules.internal.tasks.GetMISSessionIDTask"</span><span class="sc8">           </span><span class="sc3">async</span><span class="sc8">=</span><span class="sc6">"true"</span><span class="sc8"> </span><span class="sc11">/&gt;</span><span class="sc0">
+    </span><span class="sc1">&lt;pd:Task</span><span class="sc8"> </span><span class="sc3">id</span><span class="sc8">=</span><span class="sc6">"certificateReadRequest"</span><span class="sc8">    </span><span class="sc3">class</span><span class="sc8">=</span><span class="sc6">"at.gv.egovernment.moa.id.auth.modules.internal.tasks.CertificateReadRequestTask"</span><span class="sc8"> </span><span class="sc11">/&gt;</span><span class="sc0">
+    </span><span class="sc1">&lt;pd:Task</span><span class="sc8"> </span><span class="sc3">id</span><span class="sc8">=</span><span class="sc6">"prepareAuthBlockSignature"</span><span class="sc8"> </span><span class="sc3">class</span><span class="sc8">=</span><span class="sc6">"at.gv.egovernment.moa.id.auth.modules.internal.tasks.PrepareAuthBlockSignatureTask"</span><span class="sc8"> </span><span class="sc11">/&gt;</span><span class="sc0">
+    </span><span class="sc1">&lt;pd:Task</span><span class="sc8"> </span><span class="sc3">id</span><span class="sc8">=</span><span class="sc6">"getForeignID"</span><span class="sc8">              </span><span class="sc3">class</span><span class="sc8">=</span><span class="sc6">"at.gv.egovernment.moa.id.auth.modules.internal.tasks.GetForeignIDTask"</span><span class="sc8">              </span><span class="sc3">async</span><span class="sc8">=</span><span class="sc6">"true"</span><span class="sc8"> </span><span class="sc11">/&gt;</span><span class="sc0">
+
+    </span><span class="sc1">&lt;pd:StartEvent</span><span class="sc8"> </span><span class="sc3">id</span><span class="sc8">=</span><span class="sc6">"start"</span><span class="sc8"> </span><span class="sc11">/&gt;</span><span class="sc0">
+    
+    </span><span class="sc1">&lt;pd:Transition</span><span class="sc8"> </span><span class="sc3">from</span><span class="sc8">=</span><span class="sc6">"start"</span><span class="sc8">                     </span><span class="sc3">to</span><span class="sc8">=</span><span class="sc6">"createIdentityLinkForm"</span><span class="sc8"> </span><span class="sc11">/&gt;</span><span class="sc0">
+    
+    </span><span class="sc1">&lt;pd:Transition</span><span class="sc8"> </span><span class="sc3">from</span><span class="sc8">=</span><span class="sc6">"createIdentityLinkForm"</span><span class="sc8">    </span><span class="sc3">to</span><span class="sc8">=</span><span class="sc6">"verifyIdentityLink"</span><span class="sc8"> </span><span class="sc11">/&gt;</span><span class="sc0">
+    
+    </span><span class="sc1">&lt;pd:Transition</span><span class="sc8"> </span><span class="sc3">from</span><span class="sc8">=</span><span class="sc6">"verifyIdentityLink"</span><span class="sc8">        </span><span class="sc3">to</span><span class="sc8">=</span><span class="sc6">"certificateReadRequest"</span><span class="sc8"> </span><span class="sc3">conditionExpression</span><span class="sc8">=</span><span class="sc6">"!ctx['identityLinkAvailable'] || ctx['useMandate']"</span><span class="sc8"> </span><span class="sc11">/&gt;</span><span class="sc0">
+    </span><span class="sc1">&lt;pd:Transition</span><span class="sc8"> </span><span class="sc3">from</span><span class="sc8">=</span><span class="sc6">"verifyIdentityLink"</span><span class="sc8">        </span><span class="sc3">to</span><span class="sc8">=</span><span class="sc6">"prepareAuthBlockSignature"</span><span class="sc8"> </span><span class="sc11">/&gt;</span><span class="sc0">
+    
+    </span><span class="sc1">&lt;pd:Transition</span><span class="sc8"> </span><span class="sc3">from</span><span class="sc8">=</span><span class="sc6">"prepareAuthBlockSignature"</span><span class="sc8"> </span><span class="sc3">to</span><span class="sc8">=</span><span class="sc6">"verifyAuthBlock"</span><span class="sc8"> </span><span class="sc11">/&gt;</span><span class="sc0">
+    
+    </span><span class="sc1">&lt;pd:Transition</span><span class="sc8"> </span><span class="sc3">from</span><span class="sc8">=</span><span class="sc6">"certificateReadRequest"</span><span class="sc8">    </span><span class="sc3">to</span><span class="sc8">=</span><span class="sc6">"verifyCertificate"</span><span class="sc8"> </span><span class="sc11">/&gt;</span><span class="sc0">
+    
+    </span><span class="sc1">&lt;pd:Transition</span><span class="sc8"> </span><span class="sc3">from</span><span class="sc8">=</span><span class="sc6">"verifyCertificate"</span><span class="sc8">         </span><span class="sc3">to</span><span class="sc8">=</span><span class="sc6">"verifyAuthBlock"</span><span class="sc8"> </span><span class="sc3">conditionExpression</span><span class="sc8">=</span><span class="sc6">"ctx['useMandate']"</span><span class="sc8"> </span><span class="sc11">/&gt;</span><span class="sc0">
+    </span><span class="sc1">&lt;pd:Transition</span><span class="sc8"> </span><span class="sc3">from</span><span class="sc8">=</span><span class="sc6">"verifyCertificate"</span><span class="sc8">         </span><span class="sc3">to</span><span class="sc8">=</span><span class="sc6">"getForeignID"</span><span class="sc8"> </span><span class="sc11">/&gt;</span><span class="sc0">
+    
+    </span><span class="sc1">&lt;pd:Transition</span><span class="sc8"> </span><span class="sc3">from</span><span class="sc8">=</span><span class="sc6">"verifyAuthBlock"</span><span class="sc8">           </span><span class="sc3">to</span><span class="sc8">=</span><span class="sc6">"getMISSessionID"</span><span class="sc8"> </span><span class="sc3">conditionExpression</span><span class="sc8">=</span><span class="sc6">"ctx['useMandate']"</span><span class="sc8"> </span><span class="sc11">/&gt;</span><span class="sc0">
+    </span><span class="sc1">&lt;pd:Transition</span><span class="sc8"> </span><span class="sc3">from</span><span class="sc8">=</span><span class="sc6">"verifyAuthBlock"</span><span class="sc8">           </span><span class="sc3">to</span><span class="sc8">=</span><span class="sc6">"end"</span><span class="sc8"> </span><span class="sc11">/&gt;</span><span class="sc0">
+    
+    </span><span class="sc1">&lt;pd:Transition</span><span class="sc8"> </span><span class="sc3">from</span><span class="sc8">=</span><span class="sc6">"getMISSessionID"</span><span class="sc8">           </span><span class="sc3">to</span><span class="sc8">=</span><span class="sc6">"end"</span><span class="sc8"> </span><span class="sc11">/&gt;</span><span class="sc0">
+    </span><span class="sc1">&lt;pd:Transition</span><span class="sc8"> </span><span class="sc3">from</span><span class="sc8">=</span><span class="sc6">"getForeignID"</span><span class="sc8">              </span><span class="sc3">to</span><span class="sc8">=</span><span class="sc6">"end"</span><span class="sc8"> </span><span class="sc11">/&gt;</span><span class="sc0">
+    
+    </span><span class="sc1">&lt;pd:EndEvent</span><span class="sc8"> </span><span class="sc3">id</span><span class="sc8">=</span><span class="sc6">"end"</span><span class="sc8"> </span><span class="sc11">/&gt;</span><span class="sc0">
+
+</span><span class="sc1">&lt;/pd:ProcessDefinition&gt;</span><span class="sc0">
+</span></div>
+<p style="clear:left;">&nbsp;</p>
+	
+	<p>
+		Jede Prozessbeschreibung muss zwingend ein <code>StartEvent</code> und ein <code>EndEvent</code> enthalten.
+		Einzelne Aufgaben sind durch <code>Task</code>-Elemente gekennzeichnet, wobei via Attribut <code>async</code>
+		festgelegt wird ob es sich dabei um einen synchronen (Standardeinstellung) oder um einen asynchronen Task handelt (siehe auch <a href="#tasks">Abschnitt 2.1</a>).
+	</p>
+
+	<h2>
+		<a name="tasks" id="tasks">2.1 Aufgaben (Tasks)</a>
+	</h2>
+	<p>
+		Aus technischer Sicht sind Aufgaben einfache Klassen, die die abstrakte Klasse <code>at.gv.egovernment.moa.id.process.springweb.MoaIdTask</code> (<code>moa-id-lib-xy.jar</code>)
+		implementieren. Diese definiert lediglich eine <code>execute</code>-Methode, die aufgerufen wird, sobald der Task
+		von der ProcessEngine gestartet wird. &Uuml;ber diese Methode erh&auml;lt der Task Zugriff auf den ExecutionContext sowie
+		auf HttpServletRequest und HttpServletResponse. Der HttpServletRequest und der ExecutionContext k&ouml;nnen nun ausgewertet, bzw. falls notwendig der ExecutionContext und die HttpServletResponse auch manipuliert werden.
+	</p>
+	<p>
+		Synchrone Tasks werden hintereinander ausgef&uuml;hrt. Trifft die Process Engine auf einen asynchronen Task wird dieser
+		nicht gleich ausgef&uuml;hrt, sondern der Prozess wird zun&auml;chst angehalten. Bei asynchronen Tasks handelt es sich meist um Tasks,
+		die zuvor eine Benutzerinteraktion erfordern (z.B. Signatur mit B&uuml;rgerkartenumgebung).<br/>
+		Als Beispiel eines asynchronen Tasks w&auml;re ein <code>VerifyIdentityLinkTask</code> zu nennen, der nach Eintreffen
+		der Antwort der	B&uuml;rgerkartenumgebung auf der DataURL aufgeweckt wird, um eine <code>InfoBoxReadResponse</code> mit
+		der Personenbindung entgegen zu nehmen, diese zu parsen und zu validieren.
+	</p>
+	<p>
+		Die Aufgabe eines (DataURL-)Servlets, das den jeweiligen Prozess aufweckt, um die Ausf&uuml;hrung eines nachfolgenden asynchronen
+		Tasks zu bewirken, &uuml;bernimmt das interne Servlet <code>at.gv.egovernment.moa.id.auth.servlet.ProcessEngineSignalServlet</code>,
+		das auf die URL <code>/signalProcess</code> gemappt wurde.
+	</p>
+	<p>
+		<strong>Hinweis</strong>: Das interne <code>ProcessEngineSignalServlet</code> bzw. dessen Methode <code>getMoaSessionId(HttpServletRequest request)</code>
+		k&ouml;nnen bei Bedarf durch eine Modulspezifische Implementierung &uuml;berschrieben werden, um ggf. speziellen
+		Anforderungen in Bezug auf die Ermittlung der jeweiligen MOA Session Id Rechnung zu tragen (STORK PEPS
+		unterst&uuml;tzen keine Parameter wie <code>MOASessionID</code> in der assertion consumer url).<br/>
+		Als Beispiel dazu kann das Servlet <code>at.gv.egovernment.moa.id.auth.modules.stork.STORKProcessEngineSignalServlet</code>
+		des STORK-Moduls dienen. 
+	</p>
+	<p>
+		&nbsp;<br/>
+		Als Beispiele typischer Tasks k&ouml;nnen die Klassen im package <code>at.gv.egovernment.moa.id.auth.modules.internal.tasks</code> herangezogen werden.<br/>
+	</p>
+
+	<h2>
+		<a name="transitions" id="transitions">2.2 Transitions</a>
+	</h2>
+	<p>
+		Die Abfolge der einzelnen Task wird in der Prozessbeschreibung durch die <code>Transition</code>-Elemente
+		bestimmt. Diese weisen die zwei verpflichtenden Attribute <code>from</code> und <code>to</code> auf, die jeweils einen Task (oder StartEvent) referenzieren <strong>von</strong> (<code>from</code>) dem die ProzessEngine <strong>zu</strong> (<code>to</code>) weiteren Task (oder EndEvent) traversiert. Betrachtet man einen
+		Prozess als Graphen, dann sind die Tasks als Knoten und die Transitions als Kanten anzusehen.
+	</p>
+	<p>
+		Jede Prozessausf&uuml;hrung beginnt mit dem <code>StartEvent</code>. Von diesem ausgehend werden alle m&ouml;glichen
+		Transitions zu anderen Tasks untersucht. Die erste Transition, die eine g&uuml;ltige Verbindung zu einem anderen Task
+		aufweist wird f&uuml;r die weitere Prozessausf&uuml;hrung herangezogen. Transitions k&ouml;nnen &uuml;ber das Attribut
+		<code>conditionExpression</code> mit einer Art Policy ausgestattet werden, die festlegt, ob eine Transition verwendet
+		werden kann oder nicht. Dies erm&ouml;glicht eine bedingte Ausf&uuml;hrung von Tasks.
+	</p>
+	<p>
+		Expressions m&uuml;ssen sich in eine booleschen Wert aufl&ouml;sen lassen: <code>true</code> (genauso
+		wie ein nicht gesetztes <code>conditionExpression</code>-Attribut) bedeutet, dass die Transition verwendet werden kann,
+		<code>false</code> bedeutet, dass die Transition nicht verwendet wird.
+		Bei den Expressions handelt es sich um <a href="http://docs.spring.io/spring-framework/docs/current/spring-framework-reference/html/expressions.html">Spring EL Expressions</a>,
+		die einen leichten Zugriff auf den ExecutionContext, HttpServletRequestParameter sowie beliebige Spring-Beans erm&ouml;glichen:
+	</p>	
+	<table cellspacing="0" cellpadding="5">
+		<tr>
+			<th>Bezeichner</th>
+			<th>Beispiel</th>
+			<th>Bedeutung</th>
+		</tr>
+		<tr>
+			<td><code>ctx</code></td>
+			<td><code>!ctx['identityLinkAvailable']</code></td>
+			<td>Erlaubt das Auswerten einzelner Variablen aus dem ExecutionContext, in diesem Fall einer booleschen Variable <code>identityLinkAvailable</code></td>
+		</tr>
+		<tr>
+			<td><code>requestParameter</code></td>
+			<td><code>requestParameter['myParam'] != null</code></td>
+			<td>Greift auf RequestParameter aus dem HttpServletRequest zur&uuml;ck und erm&ouml;glicht so eine Requestparameter abh&auml;ngige Abfolge von Tasks.</td>
+		</tr>
+		<tr>
+			<td><code>@</code></td>
+			<td><code>@mySpringBean.isFoo()</code></td>
+			<td>Greift auf ein Bean (in diesem Fall mit dem Namen <code>mySpringBean</code>) aus dem Spring ApplicationContext zur&uuml;ck.</td>
+		</tr>
+	</table>
+
+	<h1>
+		<a name="module" id="module">3 Module</a>
+	</h1>
+	<p>
+		Bei einem Modul handelt es sich grunds&auml;tzlich lediglich um eine logische Gruppierung von Prozessen.
+		Module sind bedingt durch ihr automatisches Discovery als eine Art Plug-in zu betrachten, weshalb sie typischerweise
+		auch in eigene JAR-Dateien ausgelagert vorliegen.
+	</p>
+	<p>Als Beispiel eines solchen Moduls kann das STORK-Modul (<code>moa-id-module-stork-xy.jar</code>) gesehen werden.
+
+	<h2>
+		<a name="processselection" id="processselection">3.1 Metadaten und Prozessauswahl</a>
+	</h2>
+	<p>
+		Jedes Modul muss das Interface <code>at.gv.egovernment.moa.id.auth.modules.AuthModule</code> implementieren, &uuml;ber
+		das der ProcessEngine zum einen Metadaten zu Verf&uuml;gung gestellt werden, diese zum anderen aber auch die Prozessauswahl
+		(siehe <a href="#uebersicht">Abschnitt&nbsp;1</a>) abgewickelt wird.
+	</p>
+	<p>
+		<dl>
+			<dt><code>int getPriority()</code></dt>
+			<dd>&Uuml;ber diese Methode gibt das Modul seine Priorit&auml;t bekannt. Dies beeinflusst die Reihenfolge des Moduls
+			bei der Abfrage nach passenden Prozessen beim Starten eines Authentifizierungsprozesses.<br/>
+			Standardpriorit&auml;t ist <code>0</code>. Module die vorgereiht werden sollen, m&uuml;ssen eine h&ouml;here Priorit&auml;t aufweisen.</dd>
+		</dl>
+		<dl>
+			<dt><code>String[] getProcessDefinitions()</code></dt>
+			<dd>Hier&uuml;ber gibt das Modul die Prozessdefinitionen (bzw. ResourceUris zu den entsprechenden XML-Dateien) bekannt.
+			Diese werden automatisch von MOA-ID geparst und registriert.
+			</dd>
+		</dl>
+		<dl>
+			<dt><code>String selectProcess(ExecutionContext context)</code></dt>
+			<dd>Diese Methode wird von MOA-ID beim Starten eines Authentifizierungsprozesses aufgerufen. Der ExecutionContext
+			wird mit den in oben in <a href="#uebersicht">Abschnitt&nbsp;1</a> erw&auml;hnten Informationen bef&uuml;llt und dieser
+			dann der <code>selectProcess</code>-Methode &uuml;bergeben. Diese entscheidet, ob ein passender Prozess zu Verf&uuml;gung
+			steht oder nicht. Eine eventuelle modulinterne Priorisierung muss das Modul selbst vornehmen.</dd>
+		</dl>
+	</p>
+	<p>
+		Als Beispiel kann die Implementierung des STORK-Moduls herangezogen werden: <code>at.gv.egovernment.moa.id.auth.modules.stork.STORKAuthModuleImpl</code><br/>
+		N&auml;here Informationen sind der Javadoc Dokumentation des AuthModule Interfaces zu entnehmen.
+	</p>
+	
+	<h2>
+		<a name="discovery" id="discovery">3.2 Discovery</a>
+	</h2>
+	<p>
+		Das bereits erw&auml;hnte automatische Discovery von Modulen beschr&auml;nkt sich nun auf das automatische Auffinden der
+		jeweiligen <code>AuthModule</code>-Implementierung. MOA-ID sieht zwei Varianten vor, derartige Implementierung
+		aufzufinden. Welche der beiden zur Anwendung kommt (es k&ouml;nnen notfalls auch beide kombiniert werden), bleibt dem Modulentwickler &uuml;berlassen.
+	</p>
+
+	<h3>
+		<a name="serviceloader" id="serviceloader">3.2.1 Service Loader Mechanismus</a>
+	</h3>
+	<p>
+		Diese Variante sieht vor, dass jedes Modul (d.h. jede JAR-Datei) eine Datei <code>META-INF/services/at.gv.egovernment.moa.id.auth.modules.AuthModule</code>
+		enh&auml;lt, das die vorhandenen AuthModule-Implementierungen auflistet:
+	</p>
+	<pre>at.gv.egovernment.moa.id.auth.modules.internal.DefaultAuthModuleImpl
+at.gv.egovernment.moa.id.auth.modules.mymodule.MyAuthModuleImpl</pre>
+	<p>
+		N&auml;here Informationen zu diesem Mechanismus k&ouml;nnen hier entnommen werden:
+		<a href="http://docs.oracle.com/javase/6/docs/api/java/util/ServiceLoader.html">Javadoc ServiceLoader</a> bzw. <a href="http://docs.oracle.com/javase/tutorial/ext/basics/spi.html">Java Tutorials: Creating Extensible Applications</a>
+	</p>
+	
+	<h3>
+		<a name="springbean" id="springbean">3.2.2 Spring Bean Discovery</a>
+	</h3>
+	<p>
+		F&uuml;r den Fall, dass Module auf Basis des Spring Frameworks entwickelt werden, kann die AuthModule-Implementierung auch als Spring Bean erfolgen.
+	</p>
+	<p>
+		MOA-ID sucht beim Starten im Classpath nach Bean-Definitionen, die der Dateinamenskonvention <code>*.authmodule.beans.xml</code>
+		entsprechen und importiert diese. &Uuml;ber diesen Mechanismus k&ouml;nnen modulspezifische Spring Beans geladen bzw. initialisiert werden, u.a. auch AuthModule-Beans.<br/>&nbsp;
+	</p>
+	<p>Beispiel: <code>STORK.authmodule.beans.xml</code><br/>&nbsp;</p>
+	
+	<div style="float: left; white-space: pre; line-height: 1; background: #FFFFFF; "><span class="sc12">&lt;?</span><span class="sc1">xml</span><span class="sc8"> </span><span class="sc3">version</span><span class="sc8">=</span><span class="sc6">"1.0"</span><span class="sc8"> </span><span class="sc3">encoding</span><span class="sc8">=</span><span class="sc6">"UTF-8"</span><span class="sc13">?&gt;</span><span class="sc0">
+</span><span class="sc1">&lt;beans</span><span class="sc8"> </span><span class="sc3">xmlns</span><span class="sc8">=</span><span class="sc6">"http://www.springframework.org/schema/beans"</span><span class="sc8">
+    </span><span class="sc3">xmlns:xsi</span><span class="sc8">=</span><span class="sc6">"http://www.w3.org/2001/XMLSchema-instance"</span><span class="sc8">
+    </span><span class="sc3">xmlns:context</span><span class="sc8">=</span><span class="sc6">"http://www.springframework.org/schema/context"</span><span class="sc8">
+    </span><span class="sc3">xsi:schemaLocation</span><span class="sc8">=</span><span class="sc6">"http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
+        http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context.xsd"</span><span class="sc1">&gt;</span><span class="sc0">
+
+    </span><span class="sc1">&lt;context:annotation-config</span><span class="sc8"> </span><span class="sc11">/&gt;</span><span class="sc0">
+
+    </span><span class="sc1">&lt;bean</span><span class="sc8"> </span><span class="sc3">id</span><span class="sc8">=</span><span class="sc6">"storkAuthModule"</span><span class="sc8"> </span><span class="sc3">class</span><span class="sc8">=</span><span class="sc6">"at.gv.egovernment.moa.id.auth.modules.stork.STORKAuthModuleImpl"</span><span class="sc1">&gt;</span><span class="sc0">
+        </span><span class="sc1">&lt;property</span><span class="sc8"> </span><span class="sc3">name</span><span class="sc8">=</span><span class="sc6">"priority"</span><span class="sc8"> </span><span class="sc3">value</span><span class="sc8">=</span><span class="sc6">"0"</span><span class="sc8"> </span><span class="sc11">/&gt;</span><span class="sc0">
+    </span><span class="sc1">&lt;/bean&gt;</span><span class="sc0">
+
+</span><span class="sc1">&lt;/beans&gt;</span><span class="sc0">
+</span></div>
+	<p style="clear:left;">&nbsp;</p>	
+	
+	<h1>
+		<a name="hinweise" id="hinweise">4 Hinweise</a>
+	</h1>
+	<p>
+		Um einzelne Funktionen als Plug-In umzusetzen, muss nicht unbedingt ein ganzer Prozess definiert werden. MOA-ID ab
+		Version 2.2 unterst&uuml;tzt die Servlet 3.0 API, was u.a. den Einsatz von <code>@WebServlet</code>-Annotations erm&ouml;glicht.
+		Damit entf&auml;llt eine statische Registrierung von Servlets im <code>web.xml</code>.
+	</p>
+	<p>Am Beispiel des MonitoringServlets (<code>at.gv.egovernment.moa.id.auth.servlet.MonitoringServlet</code>), das als
+	separates JAR (<code>moa-id-module-monitoring-xy.jar</code>) ausgef&uuml;hrt wurde, kann dies anschaulich beobachtet werden. 
+
+	<p>&nbsp;</p>
+	<p>&nbsp;</p>
+</body>
+</html>
author	Thomas Lenz <tlenz@iaik.tugraz.at>	2019-06-12 13:47:10 +0200
committer	Thomas Lenz <tlenz@iaik.tugraz.at>	2019-06-12 13:47:10 +0200
commit	b232b84093993571da6efa97c25e1724370d6a6d (patch)
tree	6a9aa50957d867413659b2f079f7fa84f3add1d9 /id/server/doc/handbook_v4/moduledevinfo/moduledevinfo.html
parent	d7b6e57eeb37ef02ceadfe51ca730bccbed939c6 (diff)
download	moa-id-spss-b232b84093993571da6efa97c25e1724370d6a6d.tar.gz moa-id-spss-b232b84093993571da6efa97c25e1724370d6a6d.tar.bz2 moa-id-spss-b232b84093993571da6efa97c25e1724370d6a6d.zip