Bitte beachten Sie, dass die Einbindung des SSL-Zertifikates nicht über Ihren SAB-Vertrag abgedeckt ist. Diese Anleitung dient lediglich als Beispiel einer möglichen Vorgehensweise! 

Einleitung & Problemstellung

Die FLOWFACT empfiehlt das in der API Installation mitgelieferte selbst signierte SSL Zertifikat, welches lediglich eine Verschlüsselung des Datenverkehrs, nicht aber einer Validitätsprüfung des Servers genügt, gegen ein Zertifikat einer Trusted Authority auszutauschen. Sollte dieser Schritt nicht unternommen werden, kann es zu unten gezeigten Hinweisen in Browsern von Kunden kommen, die die Features S-Expose sowie Einschreiben-Email nutzen:

Dieser Hinweis besagt bildlich gesprochen, dass das ausgestellte Zertifikat nicht auf den Host registriert ist, welcher in der Browserleiste oben angezeigt wird. Dieser Mechanismus ist im Internet weit verbreitet und ist ein wichtiger Bestandteil von Sicherheit im Internet. 

Wie man ein gekauftes Zertifikat in die API Installation integriert, wird an dieser Stelle anhand eines sogenannten Chain-Zertifikats von RapidSSL (Bezogen von DomainFactory, Produktname dort: "GeoTrust RapidSSL") erläutert, welches die günstigste Variante eines sicheren Zertifikats darstellt.

Voraussetzungen zum Kauf eines SSL-Zertifikats

Zur Ausstellung eines Zertifikats benötigen Sie eine Internet Domain (im Folgenden auch: DNS Name) wie zum Beispiel "google.com" und "flowfact.de" welche sind, nur eben mit einem Domainnamen, der noch nicht existiert. Interessant für Sie könnten insbesondere die Endungen ".immobilien" und "*.immo" sein. Bitte kontaktieren Sie Ihren Provider, um den Erwerb einer Domain durchzuführen.

Durch den Kauf bzw. die Miete einer Domain haben Sie darüber hinaus mehrere Vorteile:

• Sollte nachträglich der Provider geändert werden, muss kein neues Zertifikat erworben werden
• Das Auftreten bei Beteiligten des S-Expose oder Einschreiben-Email Features wirkt mit einer sprechenden und gut gewählten Domain wesentlich professioneller

Stellen Sie bitte zudem sicher, dass Sie auf der zu registrierenden Domain eines der folgenden Emailkonten eingerichtet und abrufbar haben:

hostmaster@ihredomain.de
admin@ihredomain.de
administrator@ihredomain.de
webmaster@ihredomain.de
postmaster@ihredomain.de

Kauf des SSL-Zertifikats

Wie bereits erwähnt muss ein Zertifikat bei einem Provider gekauft werden. Viele Provider bieten diesen Service an. Exemplarisch wird hier der Prozess bei DomainFactory durchlaufen, welcher aber analog auch bei anderen Anbietern durchgeführt werden muss.

Nachdem man sich in das Nutzerkonto eingeloggt hat, kann man auf der Linken Seite den Menüpunkt "SSL-Zertifikate" wählen. Danach zeigt sich folgendes Bild:

Mit einem Klick auf "Neues Zertifikat bestellen" gelangen wir in den Prozess der Bestellung.

Man kann nun auswählen zu welchem Produkt das SSL Zertifikat zugeordnet werden soll. Dies ist jedoch nur eine organisatorische Eigenheit von DomainFactory! So ist es zum Beispiel ebenfalls möglich ein Zertifikat für eine Domain zu bestellen, die nicht bei Domainfactory gehostet wird.

Wichtig an dieser Stelle ist lediglich, dass unter "Domainname" der korrekte Domainname ohne "http", "www" und Portnummer eingetragen wird (siehe Grafik oben). 

Auf der nun folgenden Seite kann man eine Zertifikatsart auswählen:

Für welches Zertifikat Sie sich entscheiden, hängt größtenteils von Ihrem Setup und Ihren Vorstellungen ab. Wünschen Sie beispielsweise mehrere Subdomains der gleichen Domain abzusichern (also z.B. mail.immoglueck.de, api.immoglueck.de, etc.), fiele die Wahl auf ein sogenanntes "Wildcard-Zertifikat" für 9,99 € im Monat (Stand August 2014). Wünschen Sie ein "grünes Label" in der Adressleiste wird die monatliche Gebühr entsprechend höher. Für die Frage welches Zertifikat das sinnvollste für Ihr Setup ist, wenden Sie sich bitte an Ihren Provider.

Zum Betrieb der API ohne Meldung im Browser genügt das günstigste Zertifikat, ein sogenanntes Chain-Certificate, dessen Ausstellung nur wenige Minuten dauert und keinen Identitätscheck per PostIdent oder Ähnlichem voraussetzt. Bei DomainFactory heißt dieses Zertifikat "GeoTrust RapidSSL".

Sollten Sie Ihren Webserver nicht bei Domainfactory betreiben, so wählen Sie "bei einem anderen Provider/Server inkl. Übermittlung des Zertifikats per E-Mail":

Bitte stellen Sie zudem sicher, dass

1. bei Webserver-Typ "Tomcat" ausgewählt ist
2. das Feld bei "Certificate Signing Request" leer bleibt. Sollten Sie bereits einen CSR erstellt haben, können Sie diesen hier einfügen. Dieser Weg wird jedoch in dieser Beschreibung nicht näher erläutert.

Klicken sie auf "Weiter" um zur Auswahl der Bestätigungsemailadresse für den Bestellprozess zu gelangen:

Die Domain der auswählbaren Emailadressen lauten auf Ihre Domain. Dieser Sicherheitsmechanismus dient dazu eine gewisse Art von Identitätsprüfung zu gewährleisten und sicherzustellen, dass Sie der Eigentümer der entsprechenden Domain sind. 

Wie auch auf der Seite beschrieben: Wählen sie hier eine der EMailadressen in der Liste aus, die funktionstüchtig ist, d.h. die Emails empfangen kann und dessen Emails Sie lesen dürfen!

Nach einem Klick auf "Weiter" muss das Formular mit den korrekten Daten befüllt werden:

Beachten Sie besonders den Hinweis im blauen Kasten unterhalb. Wenn Sie einverstanden sind, fahren Sie fort mit "Weiter". Sie gelangen auf die Seite "Zusammenfassung":

Haken Sie danach die Checkbox unten an und klicken Sie auf "Zahlungspflichtig bestellen". Innerhalb weniger Minuten wird Ihnen das Zertifikat per Email an die angegebene E-Mail-Adresse zugestellt. Nachdem Sie das Zertifikat erhalten haben, erscheint es auch bei Domainfactory unter "SSL-Zertifikate".

Einrichtung des gekauften Chain-Certificates in der API Installation

Nachdem das SSL-Zertifikat erfolgreich erworben wurde, ist es unter dem Punkt ""SSL-Zertifikate" zu finden. Dort lassen sich nach einem Klick auf "Aktion" in der entsprechenden Zeile auch Details anzeigen:

Dies sind im einzelnen:

Bitte laden Sie die *.p12 Datei herunter und speichern Sie sie in Ihrer API Installation unter "${FLOWFACTAPI_InstallationsPfad}\jdk\bin", wobei ${FLOWFACTAPI_InstallationsPfad} den Basispfad Ihrer API Installation kennzeichnet. Notieren Sie sich darüber hinaus das angezeigte und in der Grafik oben verpixelte Passwort.

Schritt 1: Erstellen des Keystores aus p12-Datei

Öffnen Sie nun eine Kommandozeile (Ausführen... -> cmd) und navigieren Sie in eben jenes Verzeichnis. Dort angelangt ist folgender Befehl nötig um das gekaufte Zertifikat in einen Keystore zu importieren:

Der obige Aufruf und die mehrfache Angabe des korrekten Passworts erstellt die Datei ${FLOWFACTAPI_InstallationsPfad}\jdk\bin\.keystore - diese Datei ist der Keystore, der gleich im Tomcat eingebunden wird.

Schritt 2: Kopieren des erstellten Keystores und aller heruntergeladener Dateien in das Verzeichnis /basefolder/conf

Als letzter Schritt muss die erstellte .keystore-Datei per Copy & Paste in den Ordner ${FLOWFACTAPI_InstallationsPfad}/basefolder/conf kopiert werden.

Schritt 3: Konfigurieren des neu erstellten Keystores in der server.xml

In der /basefolder/conf/server.xml muss der Connector für Port 8443 angepasst werden:

Folgende Werte sind einzutragen / zu ersetzen:

• keystoreFile: bitte setzen Sie hier den Pfad relativ zum Tomcat-Installationsverzeichnis ein. In diesem Falle, wie oben beschrieben: /conf/.keystore
• keystorePass: bitte setzen Sie hier das Passwort ein, welches Sie im vorherigen Prozess genutzt haben um die Zertifikate in den Keystore zu importieren
• keyAlias: die Zeile mit diesem Eintrag, sollte in der Regel nicht notwendig sein und kann normalerweise gelöscht werden.

Schritt 4: Neustart & Test

Bitte starten Sie im Anschluss den kompletten Tomcat-Dienst neu, damit die Einstellungen übernommen werden. Achtung: Nach Neustart des Tomcat-Dienstes braucht dieser je nach Serverleistung noch einige Minuten, bis er vollständig gestartet ist. Sie können dies im Task-Manager nachverfolgen (CPU-Last sollte für diesen Prozess runtergehen).

Surfen Sie anschließend mit einem Browser Ihrer Wahl auf Ihre externe Domain mit Hilfe der folgenden URL:

https://{ihre-domain}:8443/com.flowfact.server/api/rest/public/v1.0/sysinfo

Wenn Sie alle Schritte korrekt ausgeführt haben und es keine Fehlermeldungen beim Hochfahren des Tomcats gab, sehen Sie nun keine Browsermeldung mehr.

Herzlichen Glückwunsch!

Sie haben soeben ein offiziell signiertes Zertifikat installiert.