From 59dbdaf4808d3663303b9417e05861428f798ec0 Mon Sep 17 00:00:00 2001 From: ulrich Date: Fri, 29 Jan 2021 12:15:32 +0000 Subject: [PATCH] Readme angepasst --- readme.md | 172 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 files changed, 171 insertions(+), 1 deletions(-) diff --git a/readme.md b/readme.md index 8264a64..1a572df 100644 --- a/readme.md +++ b/readme.md @@ -2,4 +2,174 @@ Eine Webanwendung zur Verwaltung von Benutzern eines Tomcat Web- und Applikationsservers in einer Derby-Datenbank. -Weitere Beschreibungen folgen später hier. +## 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 +- Eigenes Kennwort ändern + +Die responsive Bedienoberfläche passt sich an verschiedene Geräteausstattungen an. Weitere Informationen auf der [Produktseite](https://uhilger.de/data/pg/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 +``` +Diese sind an folgenden Orten frei erhältlich: + +- [Apache Tomcat](http://tomcat.apache.org) +- [XStream](https://github.com/codehaus/xstream) +- [Jettison](https://github.com/codehaus/jettison) +- [BaseLink](https://uhilger.de/gitblit/docs/BaseLink.git) +- [Transit](https://uhilger.de/gitblit/docs/Transit.git) + +Ferner erfordert die Nutzerverwaltung die folgenden Javascript-Bibliotheken und Schriftarten: + +``` +$JSLIB/mustache (>=2.3.0) +$FONTS/Roboto_Condensed/RobotoCondensed-Regular.ttf +``` + +Nachfolgend die Quellen, von denen Mustache und der Font bezogen werden können: + +- [Mustache](https://github.com/janl/mustache.js) +- [Roboto Condensed](https://fonts.google.com/specimen/Roboto+Condensed) + +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 Bibliotheken und Schriftarten lokal an Orten abgelegt sind, deren Pfade mit den Platzhaltern `$JLIB`, `$JSLIB` und `$FONTS` 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): + +``` +cd $UM +mkdir dist build +cp -r web/* build +cd build/WEB-INF +mkdir classes lib +cd .. +mkdir fonts +mkdir jslib +cd .. +cp $JLIB/* build/WEB-INF/lib +cp -r $JSLIB/* build/jslib +cp -r $FONTS/* build/fonts + +$JDK/bin/javac -classpath $JLIB/jettison-1.3.3.jar:$JLIB/BaseLink.jar:$JLIB/Transit.jar:$JLIB/xstream-1.4.7.jar:$CATALINA_HOME/lib/servlet-api.jar -d ./build/WEB-INF/classes src/java/de/uhilger/um/*.java src/java/de/uhilger/um/api/*.java src/java/de/uhilger/um/web/*.java src/java/de/uhilger/um/daten/*.java + +$JDK/bin/jar -cf dist/um.war -C build . +rm -r build +``` + +Das Webarchiv der Nutzerverwaltung liegt anschließend als `$UM/dist/um.war` fertig zum Deployment bereit. + +### Distributionsalternative + +Das Kommando `cp $JLIB/* build/WEB-INF/lib` kann auch weggelassen werden, dann sind die Klassenbibliotheken nicht Teil des Webarchivs der Nutzerverwaltung. In diesem Fall muss stattdessen der Inhalt von `$JLIB` nach `$CATALINA_BASE/lib` kopiert werden. + +### 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://localhost:1527` konfiguriert. Damit wird auf einen Derby-Server auf Port 1527 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. + +## Nutzerverwaltung auf Tomcat einschalten + +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`, Kennwort `admin`, mit dem neue Benutzer und Rollen angelegt werden können. + +Damit Tomcat die von der Nutzerverwaltung verwaltete Nutzerdatenbank verwendet, müssen in der Datei `$CATALINA_BASE/conf/server.xml` Änderungen gemacht werden, die weiter unten beispielhaft beschrieben sind. Wichtig ist, für die Umstellung auf eine Nutzerdatenbank die folgende Reihenfolge einzuhalten. + +1. Datenbankserver starten +1. Tomcat mit alten Benutzereinstellungen starten +1. Die Nutzerverwaltung auf Tomcat installieren (Deploy) +1. DataSource hinzufügen (s.u.) +1. Realm umstellen (s.u.) + +Danach muss Tomcat neu gestartet werden. + +### DataSource hinzufügen + +Zu Beginn der Datei `$CATALINA_BASE/conf/server.xml` wird die DataSource angegeben, die den Ablageort der Benutzerdatenbank angibt: + +``` + <!-- Global JNDI resources + Documentation at /docs/jndi-resources-howto.html + --> + <GlobalNamingResources> + <!-- Editable user database that can also be used by + UserDatabaseRealm to authenticate users + --> + <Resource name="UserDatabase" auth="Container" + type="org.apache.catalina.UserDatabase" + description="User database that can be updated and saved" + factory="org.apache.catalina.users.MemoryUserDatabaseFactory" + pathname="conf/tomcat-users.xml" /> + + <Resource name="jdbc/NewUserDB" + auth="Container" + type="javax.sql.DataSource" + driverClassName="org.apache.derby.jdbc.ClientDriver" + url="jdbc:derby://localhost:1527/udb;create=true" + maxActive="60" + maxIdle="30" + maxWait="5000" + /> + </GlobalNamingResources> +``` + +### Realm umstellen + +Weiter unten in der Datei `$CATALINA_BASE/conf/server.xml` ist der Realm angegeben, der die Benutzerdaten für Authentifizierung und Autorisierung an Tomcat übergibt. + +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.DataSourceRealm" + dataSourceName="jdbc/NewUserDB" + userTable="users" userNameCol="user_name" userCredCol="user_pass" + userRoleTable="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 Realm mit dem oben aufgeführten CredentialHandler vermittelt werden. + +## Verschlüsselung von Kennworten + +Die Nutzerverwaltung legt Kennworte verschlüsselt in der Datenbank ab. Laut Dokumentation von Tomcat wird dafür die Klasse `RealmBase` 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 setzte dort bislang die zuvor erwähnte Klasse `RealmBase` von Tomcat ein. + +Mit Tomcat 9 wurde die Methode [Digest()](https://tomcat.apache.org/tomcat-8.5-doc/api/org/apache/catalina/realm/RealmBase.html#Digest\(java.lang.String,%20java.lang.String,%20java.lang.String\)) der Klasse RealmBase ohne Angabe von Gründen entfernt, obwohl diese Methode von der [Tomcat-Dokumentation](https://tomcat.apache.org/tomcat-9.0-doc/realm-howto.html#Digested_Passwords) auch in Verison 9 und 10 von Tomcat als diejenige zur dynamischen Erzeugung von verschlüsslten Kennworten beschrieben wird. In der Klasse `TomcatDigester` ist daher auf die Verwendung der Klasse `MessageDigestCredentialHandler` umgestellt worden. + +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. -- Gitblit v1.9.3