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 | 59 +++++++++++++++++++++++++++++++++++++++++++++++++----------
1 files changed, 49 insertions(+), 10 deletions(-)
diff --git a/readme.md b/readme.md
index 1cfd6e3..9d095c3 100644
--- a/readme.md
+++ b/readme.md
@@ -89,8 +89,46 @@
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, muss in der Datei `$CATALINA_BASE/conf/server.xml` folgende Änderung gemacht und Tomcat neu gestartet werden.
+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
@@ -112,22 +150,23 @@
<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" >
+ <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>
</Realm>
<!-- 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