Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
55 changes: 43 additions & 12 deletions de/15.7/config/sso-spnego.rst
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
=============================================
============================================================
SSO-Konfiguration mit Windows-integrierter Authentifizierung
=============================================
============================================================

Übersicht
=========
Expand Down Expand Up @@ -83,9 +83,9 @@ Erstellen Sie ``app/WEB-INF/classes/krb5.conf`` mit der Kerberos-Konfiguration.

[libdefaults]
default_realm = EXAMPLE.LOCAL
default_tkt_enctypes = aes128-cts rc4-hmac des3-cbc-sha1 des-cbc-md5 des-cbc-crc
default_tgs_enctypes = aes128-cts rc4-hmac des3-cbc-sha1 des-cbc-md5 des-cbc-crc
permitted_enctypes = aes128-cts rc4-hmac des3-cbc-sha1 des-cbc-md5 des-cbc-crc
default_tkt_enctypes = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 aes256-cts-hmac-sha384-192 aes128-cts-hmac-sha256-128
default_tgs_enctypes = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 aes256-cts-hmac-sha384-192 aes128-cts-hmac-sha256-128
permitted_enctypes = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 aes256-cts-hmac-sha384-192 aes128-cts-hmac-sha256-128

[realms]
EXAMPLE.LOCAL = {
Expand All @@ -100,6 +100,19 @@ Erstellen Sie ``app/WEB-INF/classes/krb5.conf`` mit der Kerberos-Konfiguration.
.. note::
Ersetzen Sie ``EXAMPLE.LOCAL`` durch Ihren AD-Domänennamen (Großbuchstaben) und ``AD-SERVER.EXAMPLE.LOCAL`` durch Ihren AD-Server-Hostnamen.

.. warning::
Ein Service-Ticket mit einem Verschlüsselungstyp, der nicht in ``permitted_enctypes`` aufgeführt ist,
wird von der Kerberos-Gegenstelle mit ``encryption type not in permitted_enctypes list`` abgelehnt.
Active Directory stellt in der Regel AES256-Service-Tickets aus, daher muss AES256 enthalten sein.

.. note::
RC4 (``rc4-hmac``), 3DES und DES sind ab Java 17 standardmäßig deaktiviert; sie aufzuführen hat
keine Wirkung. Das obige Beispiel gibt daher nur AES an.
``aes256-cts-hmac-sha384-192`` und ``aes128-cts-hmac-sha256-128`` sind die von Windows Server 2025
unterstützten AES-SHA2-Typen (RFC 8009).
Ein Dienstkonto, das nur einen RC4-Schlüssel besitzt, kann nicht für die Kerberos-Authentifizierung
verwendet werden. Setzen Sie sein Kennwort zurück, damit AES-Schlüssel erzeugt werden.

Login-Konfigurationsdatei
-------------------------

Expand All @@ -119,7 +132,7 @@ Erstellen Sie ``app/WEB-INF/classes/auth_login.conf`` mit der JAAS-Login-Konfigu

.. note::
Die Standarddateinamen für ``krb5.conf`` und ``auth_login.conf`` werden über ``spnego.krb5.conf`` bzw. ``spnego.login.conf`` festgelegt, die Dateien selbst müssen jedoch zwingend erstellt werden.
Sind diese Dateien nicht im Classpath vorhanden, schlägt die SPNEGO-Initialisierung fehl und |Fess| kann nicht gestartet werden.
SPNEGO wird bei der ersten Anmeldung initialisiert. Fehlen diese Dateien, startet |Fess| zwar, die SSO-Anmeldung schlägt jedoch fehl.

Erforderliche Einstellungen
---------------------------
Expand Down Expand Up @@ -179,9 +192,6 @@ Die folgenden Einstellungen können bei Bedarf hinzugefügt werden.
* - ``spnego.allow.delegation``
- Delegierung erlauben
- ``false``
* - ``spnego.exclude.dirs``
- Von der Authentifizierung ausgeschlossene Verzeichnisse (kommagetrennt)
- (Keine)
* - ``spnego.logger.level``
- Interner Protokollierungsgrad der SPNEGO-Bibliothek (``1`` =FINEST, ``2`` =FINER, ``3`` =FINE, ``4`` =CONFIG, ``6`` =WARNING, ``7`` =SEVERE; alle anderen Werte einschließlich ``0`` und ``5`` werden als INFO behandelt)
- (Automatisch)
Expand Down Expand Up @@ -280,9 +290,9 @@ Das Folgende ist ein minimales Konfigurationsbeispiel für eine Testumgebung.

[libdefaults]
default_realm = EXAMPLE.LOCAL
default_tkt_enctypes = aes128-cts rc4-hmac des3-cbc-sha1 des-cbc-md5 des-cbc-crc
default_tgs_enctypes = aes128-cts rc4-hmac des3-cbc-sha1 des-cbc-md5 des-cbc-crc
permitted_enctypes = aes128-cts rc4-hmac des3-cbc-sha1 des-cbc-md5 des-cbc-crc
default_tkt_enctypes = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 aes256-cts-hmac-sha384-192 aes128-cts-hmac-sha256-128
default_tgs_enctypes = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 aes256-cts-hmac-sha384-192 aes128-cts-hmac-sha256-128
permitted_enctypes = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 aes256-cts-hmac-sha384-192 aes128-cts-hmac-sha256-128

[realms]
EXAMPLE.LOCAL = {
Expand Down Expand Up @@ -363,6 +373,27 @@ Gruppeninformationen können nicht abgerufen werden
- Überprüfen Sie, ob Bind-DN und Passwort korrekt sind
- Überprüfen Sie, ob der Benutzer in AD zu Gruppen gehört

Die Anmeldung liefert HTTP 400
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Bei Benutzern mit vielen Gruppenmitgliedschaften wird das Kerberos-Ticket (PAC) groß, und der
``Authorization``-Header kann Tomcats Standardgrenze von 8 KB überschreiten, was mit 400 beantwortet wird.
Die Anfrage erreicht |Fess| nie, daher wird nichts protokolliert.
Erhöhen Sie das Limit in ``tomcat_config.properties``.

::

tomcat.maxHttpHeaderSize=65536

Nach Änderung des Dienstkonto-Kennworts schlägt die Authentifizierung fehl
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Die Server-Anmeldeinformationen werden einmalig bei der ersten Anmeldung ermittelt und für die
Laufzeit des Prozesses zwischengespeichert.
Starten Sie |Fess| neu, nachdem Sie das Kennwort des Dienstkontos in AD geändert oder die
Keytab-Datei ersetzt haben. Ebenso ist nach einer Änderung von ``spnego.*``-Einstellungen ein
Neustart erforderlich.

Debug-Einstellungen
--------------------

Expand Down
94 changes: 81 additions & 13 deletions de/15.8/config/sso-spnego.rst
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
=============================================
============================================================
SSO-Konfiguration mit Windows-integrierter Authentifizierung
=============================================
============================================================

Übersicht
=========
Expand Down Expand Up @@ -83,9 +83,9 @@ Erstellen Sie ``app/WEB-INF/classes/krb5.conf`` mit der Kerberos-Konfiguration.

[libdefaults]
default_realm = EXAMPLE.LOCAL
default_tkt_enctypes = aes128-cts rc4-hmac des3-cbc-sha1 des-cbc-md5 des-cbc-crc
default_tgs_enctypes = aes128-cts rc4-hmac des3-cbc-sha1 des-cbc-md5 des-cbc-crc
permitted_enctypes = aes128-cts rc4-hmac des3-cbc-sha1 des-cbc-md5 des-cbc-crc
default_tkt_enctypes = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 aes256-cts-hmac-sha384-192 aes128-cts-hmac-sha256-128
default_tgs_enctypes = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 aes256-cts-hmac-sha384-192 aes128-cts-hmac-sha256-128
permitted_enctypes = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 aes256-cts-hmac-sha384-192 aes128-cts-hmac-sha256-128

[realms]
EXAMPLE.LOCAL = {
Expand All @@ -100,6 +100,19 @@ Erstellen Sie ``app/WEB-INF/classes/krb5.conf`` mit der Kerberos-Konfiguration.
.. note::
Ersetzen Sie ``EXAMPLE.LOCAL`` durch Ihren AD-Domänennamen (Großbuchstaben) und ``AD-SERVER.EXAMPLE.LOCAL`` durch Ihren AD-Server-Hostnamen.

.. warning::
Ein Service-Ticket mit einem Verschlüsselungstyp, der nicht in ``permitted_enctypes`` aufgeführt ist,
wird von der Kerberos-Gegenstelle mit ``encryption type not in permitted_enctypes list`` abgelehnt.
Active Directory stellt in der Regel AES256-Service-Tickets aus, daher muss AES256 enthalten sein.

.. note::
RC4 (``rc4-hmac``), 3DES und DES sind ab Java 17 standardmäßig deaktiviert; sie aufzuführen hat
keine Wirkung. Das obige Beispiel gibt daher nur AES an.
``aes256-cts-hmac-sha384-192`` und ``aes128-cts-hmac-sha256-128`` sind die von Windows Server 2025
unterstützten AES-SHA2-Typen (RFC 8009).
Ein Dienstkonto, das nur einen RC4-Schlüssel besitzt, kann nicht für die Kerberos-Authentifizierung
verwendet werden. Setzen Sie sein Kennwort zurück, damit AES-Schlüssel erzeugt werden.

Login-Konfigurationsdatei
-------------------------

Expand All @@ -119,7 +132,7 @@ Erstellen Sie ``app/WEB-INF/classes/auth_login.conf`` mit der JAAS-Login-Konfigu

.. note::
Die Standarddateinamen für ``krb5.conf`` und ``auth_login.conf`` werden über ``spnego.krb5.conf`` bzw. ``spnego.login.conf`` festgelegt, die Dateien selbst müssen jedoch zwingend erstellt werden.
Sind diese Dateien nicht im Classpath vorhanden, schlägt die SPNEGO-Initialisierung fehl und |Fess| kann nicht gestartet werden.
SPNEGO wird bei der ersten Anmeldung initialisiert. Fehlen diese Dateien, startet |Fess| zwar, die SSO-Anmeldung schlägt jedoch fehl.

Erforderliche Einstellungen
---------------------------
Expand All @@ -146,6 +159,24 @@ Fügen Sie die folgenden Einstellungen zu ``app/WEB-INF/conf/system.properties``
- Pfad zur Login-Konfigurationsdatei
- ``auth_login.conf``

.. note::
Bleiben ``spnego.preauth.username`` und ``spnego.preauth.password`` beide leer, verwendet das
Server-Login-Modul eine Keytab-Datei.
Wenn Sie das Kennwort des AD-Dienstkontos nicht in einer |Fess|-Konfigurationsdatei speichern
möchten, erstellen Sie eine Keytab-Datei und konfigurieren Sie ``spnego-server`` in
``auth_login.conf`` wie folgt.

::

spnego-server {
com.sun.security.auth.module.Krb5LoginModule required
useKeyTab=true
keyTab="/var/lib/fess/fess.keytab"
principal="HTTP/fess-server.example.local@EXAMPLE.LOCAL"
storeKey=true
isInitiator=false;
};

Optionale Einstellungen
-----------------------

Expand All @@ -169,18 +200,18 @@ Die folgenden Einstellungen können bei Bedarf hinzugefügt werden.
- ``true``
* - ``spnego.allow.unsecure.basic``
- Unsichere Basic-Authentifizierung erlauben
- ``true``
- ``false``
* - ``spnego.prompt.ntlm``
- Bei Empfang eines NTLM-Tokens auf Basic-Authentifizierung zurückfallen
- ``true``
* - ``spnego.allow.localhost``
- Localhost-Zugriff erlauben
- ``true``
- ``false``
* - ``spnego.allow.delegation``
- Delegierung erlauben
- ``false``
* - ``spnego.exclude.dirs``
- Von der Authentifizierung ausgeschlossene Verzeichnisse (kommagetrennt)
* - ``spnego.allowed.realms``
- Zusätzlich zur Server-Realm akzeptierte Kerberos-Realms (kommagetrennt)
- (Keine)
* - ``spnego.logger.level``
- Interner Protokollierungsgrad der SPNEGO-Bibliothek (``1`` =FINEST, ``2`` =FINER, ``3`` =FINE, ``4`` =CONFIG, ``6`` =WARNING, ``7`` =SEVERE; alle anderen Werte einschließlich ``0`` und ``5`` werden als INFO behandelt)
Expand All @@ -190,6 +221,22 @@ Die folgenden Einstellungen können bei Bedarf hinzugefügt werden.
``spnego.allow.unsecure.basic=true`` kann Base64-kodierte Anmeldeinformationen über unverschlüsselte Verbindungen senden.
Für Produktionsumgebungen wird dringend empfohlen, dies auf ``false`` zu setzen und HTTPS zu verwenden.

.. note::
Mit ``spnego.allow.unsecure.basic=false`` (Standard) wird die Basic-Authentifizierung nur für
Anfragen angeboten, bei denen ``HttpServletRequest#isSecure()`` ``true`` zurückgibt.
Wird TLS an einem Reverse-Proxy terminiert und die Anfrage per HTTP an |Fess| weitergeleitet,
ist dieser Wert ``false``. Ein Client, der kein Kerberos-Ticket erhalten kann und auf NTLM
zurückfällt, kann sich dann nicht anmelden. Setzen Sie ``tomcat.secure=true`` in
``tomcat_config.properties``, damit |Fess| die Anfrage als über HTTPS eingegangen behandelt.

.. warning::
In |Fess| 15.8 wird eine Anmeldung standardmäßig abgelehnt, wenn sich die Realm des
Client-Principals von der Realm des Servers unterscheidet. Melden sich Benutzer aus einer
untergeordneten Domäne einer AD-Domänenstruktur oder aus einer vertrauten Gesamtstruktur an,
tragen Sie diese Realms kommagetrennt in ``spnego.allowed.realms`` ein. Andernfalls werden
Benutzer, die sich bis 15.7 anmelden konnten, mit ``Kerberos realm is not allowed``
abgewiesen.

.. note::
Wenn ``spnego.prompt.ntlm=true`` (Standard), muss auch ``spnego.allow.basic`` auf ``true`` gesetzt sein.
Wenn Sie ``spnego.allow.basic=false`` setzen, müssen Sie gleichzeitig ``spnego.prompt.ntlm=false`` setzen.
Expand Down Expand Up @@ -280,9 +327,9 @@ Das Folgende ist ein minimales Konfigurationsbeispiel für eine Testumgebung.

[libdefaults]
default_realm = EXAMPLE.LOCAL
default_tkt_enctypes = aes128-cts rc4-hmac des3-cbc-sha1 des-cbc-md5 des-cbc-crc
default_tgs_enctypes = aes128-cts rc4-hmac des3-cbc-sha1 des-cbc-md5 des-cbc-crc
permitted_enctypes = aes128-cts rc4-hmac des3-cbc-sha1 des-cbc-md5 des-cbc-crc
default_tkt_enctypes = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 aes256-cts-hmac-sha384-192 aes128-cts-hmac-sha256-128
default_tgs_enctypes = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 aes256-cts-hmac-sha384-192 aes128-cts-hmac-sha256-128
permitted_enctypes = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 aes256-cts-hmac-sha384-192 aes128-cts-hmac-sha256-128

[realms]
EXAMPLE.LOCAL = {
Expand Down Expand Up @@ -363,6 +410,27 @@ Gruppeninformationen können nicht abgerufen werden
- Überprüfen Sie, ob Bind-DN und Passwort korrekt sind
- Überprüfen Sie, ob der Benutzer in AD zu Gruppen gehört

Die Anmeldung liefert HTTP 400
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Bei Benutzern mit vielen Gruppenmitgliedschaften wird das Kerberos-Ticket (PAC) groß, und der
``Authorization``-Header kann Tomcats Standardgrenze von 8 KB überschreiten, was mit 400 beantwortet wird.
Die Anfrage erreicht |Fess| nie, daher wird nichts protokolliert.
Erhöhen Sie das Limit in ``tomcat_config.properties``.

::

tomcat.maxHttpHeaderSize=65536

Nach Änderung des Dienstkonto-Kennworts schlägt die Authentifizierung fehl
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Die Server-Anmeldeinformationen werden einmalig bei der ersten Anmeldung ermittelt und für die
Laufzeit des Prozesses zwischengespeichert.
Starten Sie |Fess| neu, nachdem Sie das Kennwort des Dienstkontos in AD geändert oder die
Keytab-Datei ersetzt haben. Ebenso ist nach einer Änderung von ``spnego.*``-Einstellungen ein
Neustart erforderlich.

Debug-Einstellungen
--------------------

Expand Down
49 changes: 39 additions & 10 deletions en/15.7/config/sso-spnego.rst
Original file line number Diff line number Diff line change
Expand Up @@ -83,9 +83,9 @@ Create ``app/WEB-INF/classes/krb5.conf`` with the Kerberos configuration.

[libdefaults]
default_realm = EXAMPLE.LOCAL
default_tkt_enctypes = aes128-cts rc4-hmac des3-cbc-sha1 des-cbc-md5 des-cbc-crc
default_tgs_enctypes = aes128-cts rc4-hmac des3-cbc-sha1 des-cbc-md5 des-cbc-crc
permitted_enctypes = aes128-cts rc4-hmac des3-cbc-sha1 des-cbc-md5 des-cbc-crc
default_tkt_enctypes = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 aes256-cts-hmac-sha384-192 aes128-cts-hmac-sha256-128
default_tgs_enctypes = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 aes256-cts-hmac-sha384-192 aes128-cts-hmac-sha256-128
permitted_enctypes = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 aes256-cts-hmac-sha384-192 aes128-cts-hmac-sha256-128

[realms]
EXAMPLE.LOCAL = {
Expand All @@ -100,6 +100,19 @@ Create ``app/WEB-INF/classes/krb5.conf`` with the Kerberos configuration.
.. note::
Replace ``EXAMPLE.LOCAL`` with your AD domain name (uppercase) and ``AD-SERVER.EXAMPLE.LOCAL`` with your AD server hostname.

.. warning::
A service ticket encrypted with a type that is not listed in ``permitted_enctypes`` is rejected by
the Kerberos acceptor as ``encryption type not in permitted_enctypes list``.
Active Directory normally issues AES256 service tickets, so AES256 must be listed.

.. note::
RC4 (``rc4-hmac``), 3DES and DES are disabled by default in Java 17 and later, so listing them has
no effect; the example above specifies AES only.
``aes256-cts-hmac-sha384-192`` and ``aes128-cts-hmac-sha256-128`` are the AES-SHA2 (RFC 8009) types
supported by Windows Server 2025.
A service account that holds only an RC4 key cannot be used for Kerberos authentication; reset its
password so that AES keys are generated.

Login Configuration File
------------------------

Expand All @@ -119,7 +132,7 @@ Create ``app/WEB-INF/classes/auth_login.conf`` with the JAAS login configuration

.. note::
``krb5.conf`` and ``auth_login.conf`` have their default filenames set via ``spnego.krb5.conf`` / ``spnego.login.conf``, but the files themselves must be created.
If these files do not exist on the classpath, SPNEGO initialization will fail and |Fess| will not start.
SPNEGO is initialized on the first login, so |Fess| itself still starts when these files are missing, but SSO login fails.

Required Settings
-----------------
Expand Down Expand Up @@ -179,9 +192,6 @@ The following settings can be added as needed.
* - ``spnego.allow.delegation``
- Allow delegation
- ``false``
* - ``spnego.exclude.dirs``
- Directories to exclude from authentication (comma-separated)
- (None)
* - ``spnego.logger.level``
- Internal log level of the SPNEGO library (``1`` =FINEST, ``2`` =FINER, ``3`` =FINE, ``4`` =CONFIG, ``6`` =WARNING, ``7`` =SEVERE; any other value including ``0`` and ``5`` is treated as INFO)
- (Auto)
Expand Down Expand Up @@ -280,9 +290,9 @@ The following is a minimal configuration example for a test environment.

[libdefaults]
default_realm = EXAMPLE.LOCAL
default_tkt_enctypes = aes128-cts rc4-hmac des3-cbc-sha1 des-cbc-md5 des-cbc-crc
default_tgs_enctypes = aes128-cts rc4-hmac des3-cbc-sha1 des-cbc-md5 des-cbc-crc
permitted_enctypes = aes128-cts rc4-hmac des3-cbc-sha1 des-cbc-md5 des-cbc-crc
default_tkt_enctypes = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 aes256-cts-hmac-sha384-192 aes128-cts-hmac-sha256-128
default_tgs_enctypes = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 aes256-cts-hmac-sha384-192 aes128-cts-hmac-sha256-128
permitted_enctypes = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 aes256-cts-hmac-sha384-192 aes128-cts-hmac-sha256-128

[realms]
EXAMPLE.LOCAL = {
Expand Down Expand Up @@ -363,6 +373,25 @@ Cannot Retrieve Group Information
- Check that Bind DN and password are correct
- Verify that the user belongs to groups in AD

Login returns HTTP 400
~~~~~~~~~~~~~~~~~~~~~~

For a user who belongs to many groups the Kerberos ticket (PAC) grows large, and the
``Authorization`` header can exceed Tomcat's default limit of 8KB, which is answered with 400.
The request never reaches |Fess|, so nothing is written to the log.
Raise the limit in ``tomcat_config.properties``.

::

tomcat.maxHttpHeaderSize=65536

Authentication fails after the service account password is changed
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The server credential is obtained once on the first login and cached for the lifetime of the process.
Restart |Fess| after changing the service account password in AD or replacing the keytab.
A restart is likewise required after changing any ``spnego.*`` setting.

Debug Settings
--------------

Expand Down
Loading
Loading