| 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 | |
| 14673a | 15 | - Eigenes Kennwort ändern |
| ecd3bb | 16 | |
| 14673a | 17 | Die responsive Bedienoberfläche passt sich an verschiedene Geräteausstattungen an. Weitere Informationen auf der [Produktseite](https://uhilger.de/data/pg/Nutzerverwaltung/). |
| ecd3bb | 18 | |
| 667ccf | 19 | ## Webanwendung herstellen |
| U | 20 | |
| 21 | 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 | |
| 22 | ||
| 23 | ``` | |
| 3cd7fe | 24 | Bibliothek Datei(en) Ablageort lokal |
| U | 25 | ---------- --------- --------------- |
| 26 | Tomcat .... lib/servlet-api.jar .. $CATALINA_HOME | |
| 27 | XStream ... xstream-1.4.7.jar .... $JLIB | |
| 28 | Jettison .. jettison-1.3.3.jar ... $JLIB | |
| 29 | BaseLink .. BaseLink.jar ......... $JLIB | |
| 30 | Transit ... Transit.jar .......... $JLIB | |
| 667ccf | 31 | ``` |
| U | 32 | Diese sind an folgenden Orten frei erhältlich: |
| 33 | ||
| 34 | - [Apache Tomcat](http://tomcat.apache.org) | |
| 35 | - [XStream](https://github.com/codehaus/xstream) | |
| 36 | - [Jettison](https://github.com/codehaus/jettison) | |
| 1d0223 | 37 | - [BaseLink](https://uhilger.de/gitblit/docs/BaseLink.git) |
| U | 38 | - [Transit](https://uhilger.de/gitblit/docs/Transit.git) |
| 667ccf | 39 | |
| 59dbda | 40 | Ferner erfordert die Nutzerverwaltung die folgenden Javascript-Bibliotheken und Schriftarten: |
| U | 41 | |
| 42 | ``` | |
| 43 | $JSLIB/mustache (>=2.3.0) | |
| 44 | $FONTS/Roboto_Condensed/RobotoCondensed-Regular.ttf | |
| 45 | ``` | |
| 46 | ||
| 47 | Nachfolgend die Quellen, von denen Mustache und der Font bezogen werden können: | |
| 48 | ||
| 49 | - [Mustache](https://github.com/janl/mustache.js) | |
| 50 | - [Roboto Condensed](https://fonts.google.com/specimen/Roboto+Condensed) | |
| 51 | ||
| 52 | 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. | |
| 667ccf | 53 | |
| U | 54 | Zur Herstellung der Nutzerverwaltung werden die folgenden Kommandos ausgeführt (Beispiel für Linux): |
| 55 | ||
| 56 | ``` | |
| 57 | cd $UM | |
| 58 | mkdir dist build | |
| 59 | cp -r web/* build | |
| 60 | cd build/WEB-INF | |
| 61 | mkdir classes lib | |
| 59dbda | 62 | cd .. |
| U | 63 | mkdir fonts |
| 64 | mkdir jslib | |
| 65 | cd .. | |
| 667ccf | 66 | cp $JLIB/* build/WEB-INF/lib |
| 59dbda | 67 | cp -r $JSLIB/* build/jslib |
| U | 68 | cp -r $FONTS/* build/fonts |
| 667ccf | 69 | |
| U | 70 | $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 |
| 71 | ||
| 72 | $JDK/bin/jar -cf dist/um.war -C build . | |
| 73 | rm -r build | |
| 74 | ``` | |
| 75 | ||
| 76 | Das Webarchiv der Nutzerverwaltung liegt anschließend als `$UM/dist/um.war` fertig zum Deployment bereit. | |
| 77 | ||
| 78 | ### Distributionsalternative | |
| 79 | ||
| 80 | 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. | |
| 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 | |
| 59dbda | 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. |
