Vorbereitung

Installation
Die folgenden Schritte sollten Sie unbedingt vor einer Installation von Intrexx 18.09 oder vor einem Update einer älteren Installation durchführen, um optimale Unterstützung durch das Setup von Intrexx zu erhalten.

1. Webserver-Konfigurationen

Jedes Intrexx-Portal muss über HTTP bzw. jedes Produktivportal verschlüsselt über HTTPS erreichbar sein. Aus diesem Grund läuft in jeder Portalinstanz ein Web-Connector (ein eingebetteter Apache Tomcat), der die HTTP-Schnittstelle zur Verfügung stellt. Es gibt verschiedene Möglichkeiten, wie ein Portal mit HTTP(S) bereitgestellt werden kann. Mehrere Portale können mit demselben Protokoll, Hostname und Port, aber unterschiedlichem Pfad bzw. virtuellen Verzeichnis betrieben werden, wie hier z.B.:

https://host.example.org/portal1/
https://host.example.org/portal2/

Diese Variante ist fehleranfällig und wirft Sicherheitsprobleme auf. Sie ist daher nicht zu empfehlen.

Abhängig vom Betriebssystem und dem Benutzeraccount, mit dem der Portaldienst betrieben wird, kann der Web-Connector des Portals die HTTP-Standardports (443, unverschlüsselt 80) verwenden. Per Voreinstellung werden von Intrexx nicht privilegierte Ports (> 1024) vorgeschlagen.

1.1. Standalone

Standalone bedeutet, dass sich Clients direkt über den Web-Connector des Portals mit dem Portal verbinden. Um mehrere Standalone-Portale auf einem Server zu betreiben, gibt es diverse Konfigurationsmöglichkeiten: Die Konfiguration einer weiteren IP-Adresse erfolgt beim Betriebssystem, die Zuordnung des Hostnamens per DNS (A- oder AAAA-Record).

1.2. Portal mit vorgeschaltetem Reverse-Proxy oder Loadbalancer

Als vorgeschaltete Proxys kommen z.B. Nginx, Microsoft IIS mit ARR, HAProxy, Apache Traffic Server o.ä. in Frage. Mit einem vorgeschalteten Frontend können beliebig viele Portale (mit dem Standardport) virtuell gehostet werden. Der Server benötigt dafür nur eine IP-Adresse, sowie für jeden virtuellen Host einen A-, AAAA- oder CNAME-Record im DNS, wie z.B.

https://portal1.example.org/
https://portal2.example.org/

2. Embedded Tomcat

Tomcat ist ab Intrexx Version 18.09 im Portaldienst enthalten und wird automatisch gestartet, wenn der Portaldienst gestartet wird. In der Regel können Sie Ihr Portal im Browser mit der Basis-URL https://localhost:1337 aufrufen. Jedes Portal verfügt über eine eigene Tomcat-Konfiguration. Ein vorgeschalteter Webserver ist nicht zwingend nötig.

3. Mehrere Portale mit IIS unter einer Adresse / Integrierte Authentifizierung

Sollen auf einem Server mehrere Portale, die Integrierte Windows-Authentifizierung oder die Kerberos-Authentifizierung betrieben werden, muss der Microsoft Internet Information Server als Reverse-Proxy eingesetzt werden. Nur dieser ist in der Lage, die notwendige Authentifizierung vorzunehmen. Die folgende Anleitung zeigt Ihnen, wie Sie mehrere Portale auf einem Server und die integrierte Authentifizierung weiterhin einsetzen können.

3.1. Installation von ASP.Net




Um ASP.Net / ARR zu installieren, aktivieren Sie bitte vor der Portal-Installation unter Windows Features / Internetinformationsdienste / WWW-Dienste / Anwendungsentwicklungsfeatures / ASP.NET 4.5 (oder höher). Übernehmen Sie dabei auch alle zusätzlich vorgeschlagenen Features wie ISAPI Erweiterungen, ISAPI Filter und die .NET Erweiterbarkeit.

3.2. Installation des ARR-Moduls

Laden Sie hier den IIS Web Platform Installer (WebPI 5.0 oder höher) herunter und führen Sie die Installation aus.



Starten Sie nach abgeschlossener Installation den Internet Informationsdienste-Manager. Selektieren Sie Ihren Server und starten Sie den Web Platform Installer, den Sie nun hier in der Verwaltung sehen.



Suchen Sie nach "routing" und installieren Sie das Modul "Application Request Routing 3.0" (oder "Routing von Anwendungsanforderungen 3.0).

Bitte achten Sie darauf, nicht die ältere Version (2.5) zu wählen.


3.3. Reverse-Proxy aktivieren




Wählen Sie im IIS-Manager auf Server-Ebene das Icon "Application Request Routing" aus.



Wählen Sie hier im rechten Bereich "Server Proxy Settings".



Setzen Sie hier die Einstellung "Enable proxy". Außerdem muss die Option "Reverse rewrite host in response headers" deaktiviert werden. Andernfalls funktionieren die OAuth2-SSO-Redirect von Intrexx nicht mehr, da der IIS den externen Host im Location Header automatisch auf den IIS-Hostname umschreibt. Speichern Sie die Änderungen mit Klick auf "Übernehmen" im rechten Bereich.

3.4. Portal mit IIS-Unterstützung installieren

Wenn der interne Tomcat auf Port 1337 eingestellt ist (Default bei einer Neu-Installation), sollte nach der Portalinstallation mit IIS-Unterstützung das Portal wie gewohnt im Browser erreichbar sein. Der Internet Information Server kann auch nachträglich in den Portaleigenschaften als Frontend-Webserver ausgewählt werden.

3.5. Automatische Übertragung bei Update

Bei einem Update wird automatisch die Windows-Authentifizierung aktiviert bzw. übernommen, wenn das Portal bereits mit Windows-Authentifizierung betrieben wurde. In diesem Fall werden auch die Service-PrincipalNames für die Connectoren automatisch übertragen.

3.6. Troubleshooting

Nicht immer kann eine komplett reibungsfreie Installation des Internet Information Server–Connectors automatisch gewährleistet werden. Im Folgenden finden Sie die häufigsten Fehlerursachen und mögliche Hilfe dazu.

3.6.1. Portal nach Installation von Intrexx ohne IIS-Unterstützung auf Windows-Authentifizierung umstellen

Da eine manuelle Integration des IIS-Connectors sehr umfangreich und fehlerträchtig ist, empfehlen wir folgende Vorgehensweise:
  1. Export des bestehenden Portals
  2. Installation ASP.Net und ARR-Modul
  3. Entfernen der bisherigen Intrexx-Installation
  4. Neu-Installation mit IIS-Unterstützung (automatisch vorausgewählt)
  5. Import des Portals
  6. Umstellen der Authentifizierung

3.6.2. Port ist bereits belegt

Prüfen Sie die Port-Belegung. Auf ein Portal kann nur zugegriffen werden, wenn es über den Standardport 443 (bei HTTPS) erreicht werden kann. Bei der Einrichtung des ARR-Modules im IIS wird diese Bindung entsprechend eingestellt. Wenn dieser Port bereits von einem anderen Softwareprodukt oder einer eingerichteten Website belegt ist, ist keine Verbindung zum Portal möglich. Um zu prüfen, ob ein Fremdprodukt den Port belegt hat, gehen Sie wie folgt vor:
  1. Öffnen Sie eine Kommandozeile
  2. Geben Sie den Befehl
    "c:\> netstat –anop tcp
    ein.
  3. Wenn Sie einen Eintrag in der Form
    Lokale Adresse: "0.0.0.0:443"  Status:"abhören"
    erhalten, wissen Sie, dass der Port bereits belegt ist. Um herauszufinden, welches Programm diesen Port belegt, müssen Sie mit einem geeignetem Werkzeug (z.B. Process Explorer von Sysinternals) den Prozess suchen, der als PID in der Ausgabe des Netstat-Befehls angegeben wurde.

3.6.3. Falsch konfigurierter Application-Pool für die virtuelle Website

Prüfen Sie im IIS-Manager den verwendeten Anwendungspool für Ihr Portal. Gehen Sie dazu wie folgt vor:
  1. Öffnen Sie den IIS-Dienstemanager
  2. Öffnen Sie im Baum den Eintrag "Default-Website"
  3. Klicken Sie mit der rechten Maustaste auf den Eintrag für Ihr Portal und wählen Sie "Anwendung verwalten / Erweiterte Einstellungen"



    Merken Sie sich den Namen des eingestellten Anwendungspool (hier z.B. "DefaultAppPool")
  4. Öffnen Sie im Baum den Knoten "Anwendungspools".

  5. Prüfen Sie folgende Einstellungen:
    • .Net CLR-Version: Hier muss mindestens die Version "v4.0" eingestellt sein.
    • Verwalteter Pipelinemode: Hier muss die Option "integriert" eingestellt sein.

3.6.4. Windows-Authentifizierung: Tomcat Filter noch nicht aktiviert

Für die Windows-Authentifizierung im Portal als auch für SingleSignOn der Connectoren muss in der web.xml-Datei, die Sie im Portalverzeichnis external/htmlroot/WEB-INF finden, ein Filter aktiviert sein. In der Regel wird dieser Filter automatisch aktiviert, sobald Sie die Windows-Authentifizierung aktivieren.
  1. Öffnen Sie die Datei mit einem geeignetem Editor (z.B. Notepad++)
  2. Suchen Sie nach dem Begriff "External Authentication Filter".
    <filter-name>External Authentication Filter</filter-name>
            <filter-class>de.uplanet.lucy.server.connector.servlet.ExternalAuthenticationFilter</filter-class>
            <init-param>
                <description>
                    This property is used to enable or disable the filter.
                    IMPORTANT: For compatibility reasons the default value of this property
                    is true for the External Authentication Filter.
                    Values: true (default) or false.
                </description>
                <param-name>enabled</param-name>
                <param-value>false</param-value> 
            </init-param>
    
  3. Ändern Sie hier die Zeile
    <param-value>false</param-value>
    ab in
    <param-value>true</param-value>
  4. Speichern Sie die Datei.
  5. Starten Sie den Portaldienst neu.

3.6.5. Kerberos-Authentifizierung für Connectoren: Tomcat-Filter noch nicht aktiviert

Für den Einsatz von Connectoren mit Kerberos Authentifizierung wird ein weiterer Filter benötigt, der unter Umständen wie im vorausgehenden Schritt ebenfalls manuell in der web.xml-Datei (Tomcat-Konfiguration) manuell gesetzt werden muss:
  1. Öffnen Sie die Datei mit einem geeignetem Editor (z.B. Notepad++)
  2. Suchen Sie nach dem Begriff "connector.portalserver.additionalHeaders"
    <init-param>
    	<param-name>connector.portalserver.additionalHeaders</param-name>
    	<param-value>X-Header-1 X-Header-2</param-value>
    </init-param>
  3. Kopieren Sie den gesamten Eintrag in den anschließenden, nicht auskommentierten Bereich. Ändern Sie den Eintrag wie folgt ab:
    <init-param>
    	<param-name>connector.portalserver.additionalHeaders</param-name>
    	<param-value>X-AccountName X-KrbTicket</param-value>
    </init-param>
  4. Entfernen Sie die Zeichen -- bei </filter-mapping-->
  5. Speichern Sie die Datei.
  6. Starten Sie den Portaldienst neu.

4. Mehrere Portale mit NGINX

Sollen mehrere Intrexx-Portale mit NGINX als Reverse-Proxy betrieben werden, muss pro Portal ein virtueller Host-Name konfiguriert werden. Weitere Informationen zu diesem Thema finden Sie hier.

Über den Intrexx Portal Manager können Konfigurationsdateien für NGINX erzeugt werden. Bei diesen Dateien handelt es sich lediglich um Vorschläge. Ein Administrator kann sich selbst eine geeignete Konfiguration erstellen.

Die erstellte Datei ist den Vorlagen ähnlich, die im Installationsverzeichnis samples/web-tls-configuration/nginx zu finden sind. Zusätzlich sind bereits Werte, die über den Installationsdialog eindeutig bekannt sind, ausgefüllt.

Der Administrator ergänzt diese Vorlage um weitere Einträge, wie z.B. die TLS-Einstellungen. Um dies zu erleichtern gibt es in der Datei entsprechende Kommentare mit Links auf die zugehörige Nginx-Dokumentation.

Ist die Konfiguration abgeschlossen, wird sie vom Administrator in Nginx deployt und getestet.