Installation

Diese Seite beschreibt die Neuinstallation von smart.finder SDI. Wenn Sie eine bestehende Installation aktualisieren möchten, fahren Sie mit Migration von smart.finder SDI 1.x zu smart.finder SDI 2.x fort.

Installation von smart.finder SDI

Basiskomponenten

Die Installation von smart.finder SDI umfasst folgende Komponenten, welche im Tomcat deployed werden müssen:

smart.finder SDI Server Komponente

Die .war-Datei befindet sich unter [RELEASE-ORDNER]\ct-finder-iso-webapp-[VERSION].war.

smartEditor

Die .war-Datei befindet sich unter [RELEASE-ORDNER]\ct-smarteditor-webapp-[VERSION].war.

CSW Proxy

Die .war-Datei befindet sich unter [RELEASE-ORDNER]\ct-smartfinder-csw-[VERSION].war.

Um die Komponenten im Tomcat zu deployen, gehen Sie wie folgt vor:

  • Kopieren Sie die .war-Datei in den Ordner [TOMCAT-HOME]\webapps. Falls der Tomcat-Dienst bereits gestartet, wird sie automatisch entpackt. Andernfalls kann der Tomcat-Dienst jetzt gestartet werden.

  • Alternativ können Sie auch den Tomcat Manager verwenden, um die .war-Datei zu installieren.

Die Komponenten sind jetzt über die folgende Adressen erreichbar sein:

Falls Sie die .war-Dateien umbenannt haben, ändert sich die Adresse entsprechend.

Client

Zudem muss die Client Komponente installiert werden. Es gibt zwei Möglichkeiten, die Client-Anwendung zu installieren:

  1. Als Standalone-Client (ohne map.apps Instanz)

  2. Als App in einer existierenden map.apps Instanz

Installation als Standalone-Client

Die .war-Datei des smart-finder-Clients befindet sich unter [RELEASE-ORDNER]\ct-finder-client-webapp-[VERSION].war. Diese muss zusätzlich im Tomcat deployed werden (siehe oben).

Die Anwendung sollte über die folgende Adresse erreichbar sein: https://<yourserver>/ct-smartfinder-sdi-client-webapp-%VERSION%. Falls Sie die .war-Datei umbenannt haben, ändert sich die Adresse entsprechend.

Der Standalone-Client wird mit folgenden Apps ausgeliefert:

Installation in vorhandener map.apps Instanz

Dieser Abschnitt ist für Sie nur relevant, wenn Sie smart.finder SDI Funktionalitäten in einer bereits existierenden map.apps 4-Instanz verwenden wollen.
Die verwendete map.apps Instanz muss in Verbindung mit dem security.manager betrieben werden (security.mode = ONLY_AUTHN).
Installation der Bundles

  1. Melden Sie sich als admin-Benutzer im map.apps Manager an.

  2. Öffnen Sie den Reiter Bundles.

  3. Klicken Sie auf die +-Schaltfläche oberhalb der Liste der installierten Bundles.

  4. Laden Sie die Datei [RELEASE-ORDNER]/ct-smartfinder-sdi-extension-js-[VERSION].jar hoch. Diese enthält alle Bundles für smart.finder SDI.

Sobald das Hochladen beendet ist, werden die smart.finder SDI Bundles in der Liste der installierten Bundles angezeigt.

Installation des Job-Manager

Um den smart.finder SDI Job-Manager innerhalb des map.apps Manager nutzen zu können, gehen Sie folgendermaßen vor:

  1. Öffnen Sie die map.apps Konfigurationsdatei application.properties. Diese liegt üblicherweise im Ordner [USER_HOME]/.mapapps.

  2. Suchen Sie den Eintrag manager.config.viewbundles. Falls er bereits existiert, ergänzen Sie am Ende den Wert sf_jobadmin. Falls er noch nicht existiert, fügen Sie den Eintrag mit dem folgenden Wert ein.

    Beispiel für manager.config.viewbundles
    manager.config.viewbundles=appmanagement,reportmanagement,bundlemanagement,mapapps-github-manager,bundleupdatechecker,sf_jobadmin

    Anschließend erscheint im map.apps Manager der neue Reiter Indexierungs-Jobs.

Anpassen der URL-Konfiguration

Nachdem Installation aller Komponenten muss sichergestellt werden, dass allen Komponenten die URL des Suchdienstes bekannt ist. Die Property dazu heißt finder.service.url. Diese ist in der Regel schon korrekt konfiguriert. In folgenden Fällen muss sie angepasst oder in den application.properties hinzugefügt werden:

  • Installation in eine vorhandene map.apps Instanz

  • Änderung des Names des Server-Endpoints

Bei einer Installation in einer vorhanden map.apps Instanz, muss in der Datei application.properties von map.apps der folgende Eintrag hinzugefügt werden:

finder.service.url=https://<yourserver>/ct-finder-iso-webapp-[VERSION]

Passen Sie dabei die Domäne und den Namen (ct-finder-iso-webapp-[VERSION]) in der URL an ihre Umgebung an.

Die URL für finder.service.url muss absolut angegeben werden.

map.apps App-Konfiguration

Zum grundlegenden Ausführen der mitgelieferten Apps ist nun alles konfiguriert. Diese Apps bieten Ihnen einen Ausgangszustand für eigene Anpassungen.

Die full-page-sdi App erfordert noch zusätzliche Anpassungen, damit einige Funktionen wie Kacheln und Themenbaum korrekt funktionieren.

Weitere Informationen zur Konfiguration finden Sie im Abschnitt Konfiguration von Funktionen.

Auslieferungs-Datenbank

smart.finder SDI wird mit einer internen HSQL Datenbank ausgeliefert. Das Schema für das Speichern der Metadatendokumente wird durch den smartEditor automatisch erzeugt. Diese Datenbank sollten Sie nicht im Produktivbetrieb einsetzen, sondern hierfür eines der unterstützten Datenbanksysteme nutzen. Weitere Informationen entnehmen Sie dem Kapitel zur Konfiguration der Datenbank-Verbindung.

Konfigurieren Sie die Datenbank vollständig, bevor Sie die Migration des Metadatenbestandes durchführen.

Indexierung der Datenbank

Um die in der Datenbank gespeicherten Metadatendokumente suchen zu können, müssen diese erst in den Such-Index überführt werden. Hierzu muss ein entsprechender Indexierungs-Job im Job-Manager eingerichtet werden. Weitere Informationen entnehmen Sie dem Kapitel zur Indexierung der Datenbank.

security.manager

Für den Betrieb von smart.finder SDI ist der security.manager zwingend erforderlich. Sie haben folgende Optionen:

  • Nutzen Sie einen bereits vorhandenen security.manager in Ihrer Umgebung.

  • Falls Sie noch keinen security.manger besitzen, können Sie diesen im con terra Developer Network beziehen, gebündelt mit dem smart.finder SDI. Sie erhalten eine Lizenz für den Betrieb des security.managers im Rahmen von smart.finder SDI unter: cs@conterra.de.

  • Falls Sie einen smart.finder SDI 1.x bereits betreiben, können Sie den embedded security.manager benutzen (nicht empfohlen).

Das Download-Portal stellt zwei ZIP-Dateien zum Download bereit. Zum einen den smart.finder SDI Download und zum anderen eine ZIP-Datei mit smart.finder SDI und security.manager. Die ZIP-Datei (smart.finder SDI inkl. security.manager) ist für nur relevant, wenn zuvor der "embedded security.manager" eingesetzt wurde. Für eine Lizenz wenden Sie sich bitte an: cs@conterra.de. Andernfalls können Sie Ihren security.manager weiterverwenden.

Die Einrichtung ist im Installationskapitel des security.managers beschrieben.

Sicherheitsaspekte

Web Application Security

smart.finder SDI besitzt Endpunkte für die Abfrage und den schreibenden Zugriff auf den Index oder sonstige Kernfunktionen. Sämtliche transaktionale Endpunkte sowie das gesamte Index Management werden durch den Sichterheitsmodus ONLY_AUTHN geschützt. Dieser Modus kann nur in Verbindung mit dem security.manager verwendet werden. Er realisiert einen Domain-Cookie-basierten Zugriff und unterstützt somit Single-Sign-On zwischen den Komponenten.

Der Sicherheitsmodus kann mithilfe folgender Properties konfiguriert werden:

#
#### security for smart.finder SDI server web application
#

security.mode=ONLY_AUTHN

# Password encoding
# plain|MD5|SHA-1
security.user.pwenc=plain
# must be true if 'plain' is not used in property security.user.pwenc
security.user.use_mapped_pass=false
# enable the login audit logging (works if security.mode != NONE)
security.user.login.log=true

# Additionally, the following properties are required for "ONLY_AUTHN"
security.administration.url=${security.administration.base.url}
security.was.service.url=${security.administration.url}/WAS
security.pdp.service.url=${security.administration.url}/PDP
security.sso.service.url=${security.administration.url}/resources/ssosessions
security.sso.token.service.url=${security.administration.url}/token/ssosession
security.login.service.url=/account/login

security.sso.cookie.name=${security.sso.cookie.name}
security.sso.cookie.domain=${security.sso.cookie.domain}
security.sso.cookie.bindToIP=false
security.sso.self.endpoint=${security.administration.url}/account/self

# Key Store Properties
security.keystore.location=${security.keystore.location}
security.keystore.passwd=${security.keystore.passwd}
security.keystore.key.alias=${security.keystore.key.alias}
security.keystore.key.passwd=${security.keystore.key.passwd}

Die folgenden Werte der Properties müssen entsprechend ihrer Umgebung gesetzt werden:

security.administration.base.url

URL zur /administration Web Applikation des security.managers.

security.keystore.location

Pfad zur Keystore-Datei, die das Schlüsselpaar zur Validierung und Erzeugung von digitalen Signaturen enthält.

security.keystore.passwd

Passwort für den Zugriff auf den Keystore.

security.keystore.key.alias

Alias des Zertifikates oder privaten Schlüssels.

security.keystore.key.passwd

Passwort für den Zugriff auf den privaten Schlüssel.

security.sso.cookie.name

Name des Cookies, das für das domänenweite Single-Sign-On verwendet wird.

security.sso.cookie.domain

Name der Domäne, in der das Single-Sign-On-Cookie gültig ist. Es muss mit einem Punkt beginnen und den Regeln in RFC 2109 entsprechen.

TLS/SSL Server Trust

Beim Aufbau von Verbindungen zu HTTPS-Endpunkten durch serverseitige Java-Komponenten muss sichergestellt werden, dass das TLS/SSL-Server-Zertifikat des angefragten Hosts von der Java Virtual Machine (JVM) akzeptiert und als vertrauenswürdig erachtet wird. Andernfalls wird keine HTTPS-Verbindung zum Server aufgebaut und die Applikation reagiert fehlerhaft.

Die ist relevant, wenn Sie im Manager mittels Job-Konfiguration Quellen indexieren, auf die über einen HTTPS-Endpunkt zugegriffen wird (z.B. OGC CSW-Katalog)

Mit der Konfigurationsoption security.ssl.trustAny wird gesteuert, unter welchen Bedingungen ein TLS-Server-Zertifikat akzeptiert wird:

security.ssl.trustAny=true

Es werden alle Zertifikate akzeptiert. Einzige Bedingung ist, dass das Zertifikat zeitlich gültig ist. Das Zertifikat muss weder für den angefragten Host, noch von einer vertrauenswürdigen Stelle ausgestellt worden sein. Diese Einstellung sollte nur in Entwicklungsumgebungen aktiv sein.

security.ssl.trustAny=false

(Auslieferungszustand)
Es werden nur Zertifikate akzeptiert, die von der JVM als vertrauenswürdig erachtet werden. Es wird dringend empfohlen, diese Einstellung beizubehalten. Dies gilt insbesondere für produktive Umgebungen. Sie müssen sicherstellen, dass Server-Zertifikate von HTTPS-Endpunkten, zu denen Verbindungen hergestellt werden, vertrauenswürdig sind. Andernfalls kommt es beim Aufbau einer Verbindung zu einem Fehler.

Vertrauenswürdigkeit von Serverzertifikaten

Damit ein Serverzertifikat von der JVM als vertrauenswürdig erachtet wird, muss entweder das konkrete Serverzertifikat oder dessen Stammzertifikat im Java Runtime Environment (JRE) installiert sein. Vertrauenswürdige Zertifikate bzw. Stammzertifikate werden im JRE standardmäßig in einem Java-Keystore unter [JRE_HOME]/lib/security/cacerts gespeichert. Je nach Betriebssystem oder Konfiguration der JVM ist es jedoch möglich, dass andere Quellen für vertrauenswürdige Zertifikate genutzt werden.

Im Folgenden wird beschrieben, welche Typen von Serverzertifikaten von HTTPS-Endpunkten üblicherweise verwendet werden und was bezüglich der Vertrauenswürdigkeit zu beachten ist.

Zertifikate mit Stammzertifikat, das in der JRE installiert ist

Produktive Web Sites, die Dienste per HTTPS zur Verfügung stellen, besitzen üblicherweise Serverzertifikate, deren Stammzertifikat von einer vertrauenswürdigen Certificate Authority (CA) ausgestellt wurde. Diese Stammzertifikate sind in der JRE bereits vorinstalliert und werden damit automatisch als vertrauenswürdig eingestuft.

Um die Verbindung mit einem Endpunkt zu erlauben, dessen Serverzertifikat ein bereits in der JRE installiertes Stammzertifikat besitzt, sind keine weiteren Schritte notwendig.

Zertifikate mit Stammzertifikat, das nicht im JRE installiert ist

Gelegentlich werden in Organisationen Serverzertifikate verwendet, die von einer eigenen, organisationsinternen CA ausgestellt wurden. Das zugehörige Stammzertifikat ist folglich nicht Teil der im JRE vorinstallierten Zertifikate. Verbindungen zu HTTPS-Endpunkten mit solchen Serverzertifikaten schlagen dann fehl, es sei denn, das Stammzertifikat wird durch unternehmensinterne Prozesse automatisch allen JRE-Installationen hinzugefügt.

Um sicher zu stellen, dass allen von dieser organisationsinternen CA ausgestellten Serverzertifikaten vertraut wird, muss das Stammzertifikat der CA dem Keystore [JRE_HOME]/lib/security/cacerts hinzugefügt werden.

Selbstsignierte Zertifikate

Selbstsignierte Serverzertifikate, also Zertifikate, die sich selbst als Herausgeber referenzieren, werden häufig zu Testzwecken verwendet und sollten in Produktivsystemen nicht genutzt werden. Da ein selbstsigniertes Serverzertifikat nicht Teil der in der JRE bereits installierten Zertifikate ist, ist es nicht vertrauenswürdig.

Um HTTPS-Verbindungen mit einem Host zu erlauben, der ein selbstsigniertes Serverzertifikat verwendet, muss dieses Zertifikat dem Keystore [JRE_HOME]/lib/security/cacerts hinzugefügt werden.

Typische Fehlermeldungen

Beim Aufbau serverseitiger HTTPS-Verbindungen kann es zu verschiedenen Fehlersituationen im Zusammenhang mit der Validierung von Serverzertifikaten kommen. In den folgenden Abschnitten werden typische Fehlermeldungen aufgeführt, die in der Log-Datei der serverseitigen Anwendung oder in den Browser-Oberflächen der Applikationen erscheinen können. Zusätzlich werden ihre möglichen Ursachen beschrieben und Lösungen vorgeschlagen. Abhängig von der konkreten Infrastruktur, in der die betroffene Applikation betrieben wird, sind ggf. auch andere Ursachen und Lösungen in Betracht zu ziehen.

1. "PKIX path building failed"

Vollständige Fehlermeldung
sun.security.validator.ValidatorException:
PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target

Diese Fehlermeldung ist ein Hinweis darauf, dass das vom Server präsentierte Zertifikat für die HTTPS-Verbindung von der JVM nicht als vertrauenswürdig eingestuft wird. Ggf. handelt es sich um ein selbst-signiertes Zertifikat oder das Stammzertifikat ist nicht im JRE installiert.

Mögliche Lösungen:

  • Installieren des Stammzertifikats im JRE

  • Installieren des Serverzertifikats im JRE

  • Wenn der angefragte Server unter eigener Kontrolle ist: Bereitstellung eines neuen Serverzertifikats auf dem angefragten Server, das von einer vertrauenswürdigen CA ausgestellt wurde.

2. "No name matching [requested.host.name] found"

Vollständige Fehlermeldung
javax.net.ssl.SSLHandshakeException:
java.security.cert.CertificateException: No name matching maps.example.com found

Diese Fehlermeldung zeigt an, dass der in der HTTPS-Anfrage genutzte Host-Name nicht zu dem Host-Namen passt, der im Serverzertifikat angegeben ist. Der Client (Browser, Java-Applikation) vergleicht dabei den in der Anfrage-URL verwendeten Host-Namen mit dem "CN"-Namen des "Subject"-Feldes im X509-Zertifikat des Servers, z.B.

https://maps.example.com/

mit

CN = www.example.com, O = Example LLC, L = Mountain Dew, ST = California, C = US.

Stimmen beide Namen nicht überein (Groß-/Kleinschreibung ist nicht relevant), wird der Verbindungsaufbau mit der oben genannten Fehlermeldung abgebrochen. Dabei ist es unerheblich, ob das Zertifikat als vertrauenswürdig eingestuft würde. Die Prüfung der Vertrauenswürdigkeit findet erst statt, wenn sichergestellt ist, dass die Host-Namen übereinstimmen.

Häufig kommt es zu diesem Problem, wenn Clients denselben Server mit unterschiedlichen Namen ansprechen können, weil mehrere DNS-Einträge vorhanden sind. Insbesondere wenn der Client sich in derselben Domäne wie der Server befindet, führt oft die uneinheitliche Nutzung von nicht-qualifizierten und vollqualifizierter Host-Namen in Anfrage-URLs bzw. Serverzertifikaten zu diesem Problem. Auch die Verwendung des speziellen Host-Namens "localhost" oder von IP-Adressen in URLs führt zu diesem Problem, wenn das Serverzertifikat auf den qualifizierten Rechnernamen ausgestellt wurde.

Mögliche Lösungen:

  • Verwendung des Host-Namen in Anfrage-URLs in der Form, wie er im Serverzertifikat angegeben wird.

  • Erstellen und Hinterlegen eines neuen Serverzertifikats für den vom Client gewünschten Host-Namen, wenn sich zum Beispiel herausstellt, dass die Verwendung eines nicht-vollqualifizierten Host-Namens (oder localhost oder IP-Adresse) nicht sinnvoll ist.

  • Erstellen und Hinterlegen eines neuen Serverzertifikats mit alternativen Host-Namen ("Subject Alternative DNS Names"), wenn sich zum Beispiel herausstellt, dass der Server unausweichlich unter unterschiedlichen Host-Namen erreichbar sein muss.

3. "No subject alternative DNS name [requested.host.name] found"

Vollständige Fehlermeldung
javax.net.ssl.SSLHandshakeException:
java.security.cert.CertificateException: No subject alternative DNS name matching maps.example.com found

Diese Fehlermeldung ist ein Sonderfall der Fehlermeldung No name matching [requested.host.name found]. Einziger Unterschied ist, dass das Serverzertifikat ein zusätzliches Feld mit alternativen Host-Namen besitzt. Jedoch entspricht der vom Client verwendete Host-Name weder dem "Subject-CN" des Serverzertifikats noch in dessen Liste alternativer Host-Namen ("Subject Alternative DNS Names") angegeben ist.

Mögliche Lösungen sind unter dem Fehler No name matching [requested.host.name found] beschrieben.