From a41422259a3ef208c82e6f47c1f666deaee0af60 Mon Sep 17 00:00:00 2001 From: ulrich@undisclosed Date: Wed, 26 Feb 2020 16:26:38 +0000 Subject: [PATCH] Doku aktualisiert --- readme.md | 103 ++++++++++++++++++++++++++++++++++++--------------- 1 files changed, 72 insertions(+), 31 deletions(-) diff --git a/readme.md b/readme.md index d02d587..9d095c3 100644 --- a/readme.md +++ b/readme.md @@ -22,13 +22,13 @@ 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: @@ -68,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: @@ -87,45 +87,86 @@ ## 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. 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 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. +Damit Tomcat die von der Nutzerverwaltung verwaltete Nutzerdatenbank verwendet, müssen in der Datei `$CATALINA_BASE/conf/server.xml` folgende Änderung gemacht werden wie weiter unten beispielhaft im Detail beschrieben. + +1. DataSource hinzufügen +1. Realm umstellen + +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"> +<Engine name="Catalina" defaultHost="localhost"> - <Realm className="org.apache.catalina.realm.LockOutRealm"> - <Realm className="org.apache.catalina.realm.UserDatabaseRealm" - resourceName="UserDatabase"/> - </Realm> + <Realm className="org.apache.catalina.realm.LockOutRealm"> + <Realm className="org.apache.catalina.realm.UserDatabaseRealm" + resourceName="UserDatabase"/> + </Realm> - <!-- weitere Einträge ... --> + <!-- weitere Einträge ... --> ``` nachher ``` - <Engine name="Catalina" defaultHost="localhost"> +<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> + <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 ... --> -``` + <!-- 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. +**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. 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. +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()](http://tomcat.apache.org/tomcat-9.0-doc/realm-howto.html#Digested_Passwords) 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. \ No newline at end of file -- Gitblit v1.9.3