ulrich
2020-05-16 70d6da1fb28dffe54a4bbc8b09097485875da4e3
commit | author | age
ecccfc 1 # Nutzerverwaltung
U 2
3 Eine Webanwendung zur Verwaltung von Benutzern eines Tomcat Web- und Applikationsservers in einer Derby-Datenbank.
4
ecd3bb 5 ## Funktionen
U 6
7 Die Nutzerverwaltung stellt die folgenden Funktionen bereit
8
9 - Anlegen neuer Benutzer
10 - Löschen von Benutzern
11 - Anlegen neuer Rollen
12 - Löschen von Rollen
13 - Rollen erteilen
14 - Rollen entziehen
15
e4f4a9 16 Die Bedienoberfläche passt sich an verschiedene Geräteausstattungen an (responsiv). Sie fügt sich neben den o.a. Funktionen in den Rahmen für Verwaltungsfunktionen einer WebBox ein, kann aber ebensogut als einzelne Webanwendung auf Tomcat für die Nutzerverwaltung sorgen.
ecd3bb 17
e4f4a9 18 Weitere Informationen zur Nutzerverwaltung finden sich auf der [Produktseite] (/data/ulrich/prg//Nutzerverwaltung)
ecd3bb 19
667ccf 20 ## Webanwendung herstellen
U 21
22 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
23
24 ```
3cd7fe 25 Bibliothek  Datei(en)              Ablageort lokal
U 26 ----------  ---------              ---------------
27 Tomcat .... lib/servlet-api.jar .. $CATALINA_HOME
28 XStream ... xstream-1.4.7.jar .... $JLIB
29 Jettison .. jettison-1.3.3.jar ... $JLIB
30 BaseLink .. BaseLink.jar ......... $JLIB
31 Transit ... Transit.jar .......... $JLIB
667ccf 32 ```
U 33 Diese sind an folgenden Orten frei erhältlich:
34
35 - [Apache Tomcat](http://tomcat.apache.org)
36 - [XStream](https://github.com/codehaus/xstream)
37 - [Jettison](https://github.com/codehaus/jettison)
38 - [BaseLink](https://uhilger.de/gitblit/summary/BaseLink.git)
39 - [Transit](https://uhilger.de/gitblit/summary/Transit.git)
40
56a185 41 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.
667ccf 42
U 43 Zur Herstellung der Nutzerverwaltung werden die folgenden Kommandos ausgeführt (Beispiel für Linux):
44
45 ```
46 cd $UM
47 mkdir dist build
48 cp -r web/* build
49 cd build/WEB-INF
50 mkdir classes lib
51 cd ../..
52 cp $JLIB/* build/WEB-INF/lib
53
54 $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
55
56 $JDK/bin/jar -cf dist/um.war -C build .
57 rm -r build
58 ```
59
60 Das Webarchiv der Nutzerverwaltung liegt anschließend als `$UM/dist/um.war` fertig zum Deployment bereit.
61
62 ### Distributionsalternative
63
64 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.
65
66 ## Abhängigkeiten
67
68 Die Nutzerverwaltung erfordert die folgenden Bestandteile auf der Instanz von Tomcat, auf der sie ausgeführt werden soll:
69
70 ```
3cd7fe 71 $CATALINA_BASE/webapps/jslib/bootstrap (>=4.0 alpha 6)
U 72 $CATALINA_BASE/webapps/jslib/jquery (>=1.11.1)
73 $CATALINA_BASE/webapps/jslib/mustache (>=2.3.0)
667ccf 74 ```
U 75
76 `$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:
77
78 - [Bootstrap](http://getbootstrap.com)
79 - [jQuery](http://jquery.com)
80 - [Mustache](https://github.com/janl/mustache.js)
81
a3d357 82 ### Datenbank
U 83
e4f4a9 84 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.
a3d357 85
U 86 Für den Zugriff auf den Datenbankserver muss sich der Datenbanktreiber `derbyclient.jar` aus der Distribution von Derby im Verzeichnis `$CATALINA_BASE/lib` befinden.
eda15d 87
U 88 ## Nutzerverwaltung auf Tomcat einschalten
89
e4f4a9 90 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.
d313b3 91
8a1728 92 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.
eda15d 93
d3269d 94 1. Datenbankserver starten
U 95 1. Tomcat mit alten Benutzereinstellungen starten
96 1. Die Nutzerverwaltung auf Tomcat installieren (Deploy)
8a1728 97 1. DataSource hinzufügen (s.u.)
U 98 1. Realm umstellen (s.u.)
a41422 99
U 100 Danach muss Tomcat neu gestartet werden.
101
102 ### DataSource hinzufügen
103
104 Zu Beginn der Datei `$CATALINA_BASE/conf/server.xml` wird die DataSource angegeben, die den Ablageort der Benutzerdatenbank angibt:
105
106 ```
107   <!-- Global JNDI resources
108        Documentation at /docs/jndi-resources-howto.html
109   -->
110   <GlobalNamingResources>
111     <!-- Editable user database that can also be used by
112          UserDatabaseRealm to authenticate users
113     -->
114     <Resource name="UserDatabase" auth="Container"
115               type="org.apache.catalina.UserDatabase"
116               description="User database that can be updated and saved"
117               factory="org.apache.catalina.users.MemoryUserDatabaseFactory"
118               pathname="conf/tomcat-users.xml" />
e4f4a9 119
a41422 120     <Resource name="jdbc/NewUserDB"
U 121           auth="Container"
122           type="javax.sql.DataSource"
123           driverClassName="org.apache.derby.jdbc.ClientDriver"
124           url="jdbc:derby://localhost:1527/udb;create=true"
125           maxActive="60"
126           maxIdle="30"
127           maxWait="5000"
128       />
129   </GlobalNamingResources>
130 ```
131
132 ### Realm umstellen
133
134 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.
eda15d 135
U 136 vorher
137
138 ```
3cd7fe 139 <Engine name="Catalina" defaultHost="localhost">
eda15d 140
3cd7fe 141   <Realm className="org.apache.catalina.realm.LockOutRealm">
U 142     <Realm className="org.apache.catalina.realm.UserDatabaseRealm"
143            resourceName="UserDatabase"/>
144   </Realm>
eda15d 145
3cd7fe 146   <!-- weitere Einträge ... -->
eda15d 147 ```
U 148
149
150 nachher
151
152 ```
3cd7fe 153 <Engine name="Catalina" defaultHost="localhost">
eda15d 154
3cd7fe 155   <Realm className="org.apache.catalina.realm.LockOutRealm">
a41422 156     <Realm className="org.apache.catalina.realm.DataSourceRealm"
U 157         dataSourceName="jdbc/NewUserDB"
158         userTable="users" userNameCol="user_name" userCredCol="user_pass"
159         userRoleTable="user_roles" roleNameCol="role_name">
3cd7fe 160         <CredentialHandler className="org.apache.catalina.realm.MessageDigestCredentialHandler" algorithm="sha-256" />
a41422 161     </Realm>
3cd7fe 162   </Realm>
eda15d 163
3cd7fe 164   <!-- weitere Einträge ... -->
a41422 165 ```
eda15d 166
a41422 167 **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.
eda15d 168
U 169 ## Verschlüsselung von Kennworten
170
a41422 171 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.
U 172
2c4bbb 173 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.
eda15d 174
U 175 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.