ulrich
2017-02-01 3ff00acb3cb64ecc7da04f946a6e1c19c63199d2
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
16 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.
17
18 Weitere Informationen zur Nutzerverwaltung finden sich auf der [Produktseite] (http://uhilger.de/dev/Software/Nutzerverwaltung/Nutzerverwaltung) 
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 ```
25 Bibliothek            Datei(en)                       Ablageort lokal
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
32 ```
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 ```
71 $CATALINA_BASE/webapps/jslib/bootstrap ............ mindestens in Version 4.0 alpha 6
72 $CATALINA_BASE/webapps/jslib/jquery ............... mindestens in Version 1.11.1
73 $CATALINA_BASE/webapps/jslib/mustache ............. mindestens in Version 2.3.0
74 ```
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
54bbae 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://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.
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
d313b3 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`, mit dem neue Benutzer und Rollen angelegt werden können. 
U 91
92 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.
eda15d 93
U 94
95 vorher
96
97 ```
98     <Engine name="Catalina" defaultHost="localhost">
99
100       <Realm className="org.apache.catalina.realm.LockOutRealm">
101         <Realm className="org.apache.catalina.realm.UserDatabaseRealm"
102                resourceName="UserDatabase"/>
103       </Realm>
104
105       <!-- weitere Einträge ... -->
106 ```
107
108
109 nachher
110
111 ```
112     <Engine name="Catalina" defaultHost="localhost">
113
114       <Realm className="org.apache.catalina.realm.LockOutRealm">
115         <Realm className="org.apache.catalina.realm.JDBCRealm"
116           driverName="org.apache.derby.jdbc.ClientDriver"
117           connectionURL="jdbc:derby://localhost:1528/udb;user=dbadmin;password=changeit"
118           userTable="app.users" userNameCol="user_name" userCredCol="user_pass"
119           userRoleTable="app.user_roles" roleNameCol="role_name" >
120             <CredentialHandler className="org.apache.catalina.realm.MessageDigestCredentialHandler" algorithm="sha-256" />
121         </Realm>
122       </Realm>
123
124       <!-- weitere Einträge ... -->
125 ``` 
126
127 **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.
128
129 ## Verschlüsselung von Kennworten
130
131 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.  
132
133 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.