From 3cd7fefd7afb5a8a2f70290b9bbeb453c5f9382b Mon Sep 17 00:00:00 2001 From: ulrich Date: Thu, 02 Feb 2017 05:31:34 +0000 Subject: [PATCH] Doku ergaenzt --- readme.md | 92 ++++++++++++++++++++++++++++++++++----------- 1 files changed, 69 insertions(+), 23 deletions(-) diff --git a/readme.md b/readme.md index 54d02d9..1cfd6e3 100644 --- a/readme.md +++ b/readme.md @@ -2,18 +2,33 @@ Eine Webanwendung zur Verwaltung von Benutzern eines Tomcat Web- und Applikationsservers in einer Derby-Datenbank. +## Funktionen + +Die Nutzerverwaltung stellt die folgenden Funktionen bereit + +- Anlegen neuer Benutzer +- Löschen von Benutzern +- Anlegen neuer Rollen +- Löschen von Rollen +- Rollen erteilen +- Rollen entziehen + +Die Bedienoberfläche passt sich an verschiedene Geräteausstattungen an (responsiv) und fügt sich neben den o.a. Funktionen in den Rahmen für Verwaltungsfunktionen einer WebBox ein. + +Weitere Informationen zur Nutzerverwaltung finden sich auf der [Produktseite] (http://uhilger.de/dev/Software/Nutzerverwaltung/Nutzerverwaltung) + ## Webanwendung herstellen Zum Herstellen der Webanwendung wird ein Java Development Kit (JDK) benötigt, wie es z.B. von [Azul](http://azul.com) oder dem [OpenJDK-Projekt](http://openjdk.java.net/) erhältlich ist. In der hier folgenden weiteren Beschreibung wird der lokale Ablageort des Java Development Kits `$JDK` genannt. Desweiteren werden die folgenden Klassenbibliotheken benötigt ``` -Bibliothek Datei(en) Ablageort lokal ----------- --------- --------------- -Tomcat .............. lib/servlet-api.jar ........... $CATALINA_HOME -XStream ............. xstream-1.4.7.jar ............. $JLIB -Jettison ............ jettison-1.3.3.jar ............ $JLIB -BaseLink ............ BaseLink.jar .................. $JLIB -Transit ............. Transit.jar ................... $JLIB +Bibliothek Datei(en) Ablageort lokal +---------- --------- --------------- +Tomcat .... lib/servlet-api.jar .. $CATALINA_HOME +XStream ... xstream-1.4.7.jar .... $JLIB +Jettison .. jettison-1.3.3.jar ... $JLIB +BaseLink .. BaseLink.jar ......... $JLIB +Transit ... Transit.jar .......... $JLIB ``` Diese sind an folgenden Orten frei erhältlich: @@ -23,7 +38,7 @@ - [BaseLink](https://uhilger.de/gitblit/summary/BaseLink.git) - [Transit](https://uhilger.de/gitblit/summary/Transit.git) -Nach Beschaffung des JDK und der oben angegebenen Klassenbibliotheken wird der Quellcode aus diesem Git-Repository an einen frei wählbaren lokalen Ablageort [heruntergeladen](http://uhilger.de/gitblit/zip/?r=um.git&h=master&format=zip) und entpackt. In der hier folgenden weiteren Beschreibung wird das so entstandene Verzeichnis `um` einschließlich des absoluten Pfades dorthin `$UM` genannt. Ferner wird angenommen, dass die oben aufgeführten Klassenbibliotheken lokal an Orten abgelegt sind, deren Pfade mit den Platzhaltern `$JLIB` und `$CATALINA_HOME` gemeint sind. Anstelle der Platzhalter in den folgenden Kommandos muss also der absolute Pfad des lokalen Ablageortes eingesetzt werden. +Nach Beschaffung des JDK und der oben angegebenen Klassenbibliotheken wird der Quellcode aus diesem Git-Repository an einen frei wählbaren lokalen Ablageort [heruntergeladen](http://uhilger.de/gitblit/zip/?r=um.git&h=master&format=zip) und entpackt. In der hier folgenden weiteren Beschreibung wird das so entstandene Verzeichnis `um-master` einschließlich des absoluten Pfades dorthin `$UM` genannt. Ferner wird angenommen, dass die oben aufgeführten Klassenbibliotheken lokal an Orten abgelegt sind, deren Pfade mit den Platzhaltern `$JLIB` und `$CATALINA_HOME` gemeint sind. Anstelle der Platzhalter in den folgenden Kommandos muss also der absolute Pfad des lokalen Ablageortes eingesetzt werden. Zur Herstellung der Nutzerverwaltung werden die folgenden Kommandos ausgeführt (Beispiel für Linux): @@ -53,9 +68,9 @@ Die Nutzerverwaltung erfordert die folgenden Bestandteile auf der Instanz von Tomcat, auf der sie ausgeführt werden soll: ``` -$CATALINA_BASE/webapps/jslib/bootstrap ............ mindestens in Version 4.0 alpha 6 -$CATALINA_BASE/webapps/jslib/jquery ............... mindestens in Version 1.11.1 -$CATALINA_BASE/webapps/jslib/mustache ............. mindestens in Version 2.3.0 +$CATALINA_BASE/webapps/jslib/bootstrap (>=4.0 alpha 6) +$CATALINA_BASE/webapps/jslib/jquery (>=1.11.1) +$CATALINA_BASE/webapps/jslib/mustache (>=2.3.0) ``` `$CATALINA_BASE` meint das in der der Datei [RUNNING.txt](http://tomcat.apache.org/tomcat-8.5-doc/RUNNING.txt) der Tomcat-Dokumentation so bezeichnete Verzeichnis. Nachfolgend die Quellen, von denen die obigen Abhängigkeiten bezogen werden können: @@ -66,22 +81,53 @@ ### Datenbank -Zur Verwaltung von Benutzern in einer Datenbank muss ein [Derby-Datenbankserver](http://db.apache.org/derby) im Zugriff der Nutzerverwaltung sein. Im Auslieferungszustand der Nutzerverwaltung ist dies in der Datei `$UM/web/META-INF/context.xml` als Uniform Resource Locator (URL) `jdbc:derby://127.0.0.1:1528` konfiguriert. Damit wird auf einen Derby-Server auf Port 1528 der lokalen Maschine verwiesen und lässt sich dort an die vorgesehene Laufzeitumgebung anpassen. +Zur Verwaltung von Benutzern in einer Datenbank muss ein [Derby-Datenbankserver](http://db.apache.org/derby) im Zugriff der Nutzerverwaltung sein. Im Auslieferungszustand der Nutzerverwaltung ist dies in der Datei `$UM/web/META-INF/context.xml` als Uniform Resource Locator (URL) `jdbc:derby://127.0.0.1:1528` konfiguriert. Damit wird auf einen Derby-Server auf Port 1528 der lokalen Maschine verwiesen. Dieser Eintrag muss geändert werden, wenn sich der Datenbankserver an einem anderen Ort befindet. Für den Zugriff auf den Datenbankserver muss sich der Datenbanktreiber `derbyclient.jar` aus der Distribution von Derby im Verzeichnis `$CATALINA_BASE/lib` befinden. -## Funktionen +## Nutzerverwaltung auf Tomcat einschalten -Die Nutzerverwaltung stellt die folgenden Funktionen bereit +Die Nutzerverwaltung wird per Deploy auf Tomcat installiert und kann anschließend von Benutzern mit der Rolle `nutzerAdmin` ausgeführt werden. Beim ersten Start wird die Benutzerdatenbank erstellt und darin ein Benutzer `admin`, mit dem neue Benutzer und Rollen angelegt werden können. -- Anlegen neuer Benutzer -- Löschen von Benutzern -- Anlegen neuer Rollen -- Löschen von Rollen -- Rollen erteilen -- Rollen entziehen +Damit Tomcat die von der Nutzerverwaltung verwaltete Nutzerdatenbank verwendet, muss in der Datei `$CATALINA_BASE/conf/server.xml` folgende Änderung gemacht und Tomcat neu gestartet werden. -Die Bedienoberfläche passt sich an verschiedene Geräteausstattungen an (responsiv) und fügt sich neben den o.a. Funktionen in den Rahmen für Verwaltungsfunktionen einer WebBox ein. -Weitere Informationen zur Nutzerverwaltung finden sich auf der [Produktseite] (http://uhilger.de/dev/Software/Nutzerverwaltung/Nutzerverwaltung) -...dort noch nicht auf dem neuesten Stand... +vorher + +``` +<Engine name="Catalina" defaultHost="localhost"> + + <Realm className="org.apache.catalina.realm.LockOutRealm"> + <Realm className="org.apache.catalina.realm.UserDatabaseRealm" + resourceName="UserDatabase"/> + </Realm> + + <!-- weitere Einträge ... --> +``` + + +nachher + +``` +<Engine name="Catalina" defaultHost="localhost"> + + <Realm className="org.apache.catalina.realm.LockOutRealm"> + <Realm className="org.apache.catalina.realm.JDBCRealm" + driverName="org.apache.derby.jdbc.ClientDriver" + connectionURL="jdbc:derby://localhost:1528/udb;user=dbadmin;password=changeit" + userTable="app.users" userNameCol="user_name" userCredCol="user_pass" + userRoleTable="app.user_roles" roleNameCol="role_name" > + <CredentialHandler className="org.apache.catalina.realm.MessageDigestCredentialHandler" algorithm="sha-256" /> + </Realm> + </Realm> + + <!-- weitere Einträge ... --> +``` + +**Bitte beachten**: Ab Version 8.5 von Tomcat wurde die Verschlüsselung auf SHA-256 umgestellt. Dies muss dem JDBCRealm mit dem oben aufgeführten CredentialHandler vermittelt werden. + +## Verschlüsselung von Kennworten + +Die Nutzerverwaltung legt Kennworte verschlüsselt in der Datenbank ab. Standardmäßig wird dafür die Klasse `RealmBase` von Tomcat verwendet. Damit innerhalb der Nutzerverwaltung auch andere Mechanismen verwendet werden können, wird die Schnittstelle `de.uhilger.um.Digester` verwendet. Die Klasse `de.uhilger.um.TomcatDigester` implementiert diese und setzt dort die zuvor erwähnte Klasse `RealmBase` von Tomcat ein. + +Im Deployment Descriptor `$UM/web/WEB-INF/web.xml` ist der Context Parameter `digester` hinterlegt und standardmäßig auf `de.uhilger.um.TomcatDigester` eingestellt. Soll eine andere Form der Verschlüsselung genutzt werden, kann dies mit einer eigenen Implementierung der Schnittstelle `de.uhilger.um.Digester` erreicht und entsprechend im Deployment Descriptor umkonfiguriert werden. \ No newline at end of file -- Gitblit v1.9.3