In diesem Beispiel wird gezeigt, wie Termine aus dem persönlichen Kalender
über einen OData-Service für externe Zugriffe bereitgestellt werden können. Auf die Termindaten des Kalenders kann von einem anderen Portal aus ein Zugriff mit dem
Connector für OData oder mit jedem beliebigen OData-Client erfolgen. Ein neuer OData-Dienst kann im Modul Integration
über das Hauptmenü OData / Neuer Dienst konfiguriert werden.
In diesem Dialog
werden die folgenden Einstellungen gesetzt:
Name: Appointments
Namespace: PersonalCalendar
Dienst ist aktiv
Im nächsten Dialog
werden die Datengruppen für den Service ausgewählt.
Datengruppe hinzufügen
Öffnet einen Dialog,
in dem eine Datengruppe ausgewählt werden kann.
Setzen Sie in diesem Dialog
die folgenden Einstellungen:
Typname: Appointment
Setname: Appointment
Zugelassene Aktionen: Alle zulassen
In diesem Dialog
werden die Datenfelder ausgewählt, auf die der OData-Service zugreifen wird:
ID
BenutzerID
Datum Von
Datum Bis
Überschrift
Beschreibung
Im nächsten Dialog
werden alle Einstellungen beibehalten. Nach dem Fertigstellen wird der neue Service angezeigt.
2. OData-Server Konfiguration
Bevor der Service verwendet werden kann, muss noch der OData-Anbieter
über das Hauptmenü OData / Einstellungen
aktiviert werden.
OData-Services werden von Intrexx an eine festgelegte TCP/IP-Adresse und Port gebunden
und bereitgestellt. Bevor auf einen OData-Service zugegriffen werden kann, muss der
OData-Server entsprechend konfiguriert und aktiviert werden.
In diesem Dialog
werden die folgenden Einstellungen gesetzt:
Bindungsadresse: Unter dieser Adresse soll der Dienst erreichbar sein
Port: Ein freier Port, der nicht von einem anderen Dienst verwendet und nicht von einer Firewall blockiert wird.
Anbieter ist aktiv
Der OData-Server wird nach dem Fertigstellen automatisch gestartet und der Dienst aktiviert.
Zum Testen des Diensts können Sie nun in einem Browser die Adresse
http://servername:port/Appointments.svc aufrufen.
Ersetzen Sie "servername" und "port" mit dem Hostnamen des Computers, auf dem der Intrexx Portalserver läuft. Das OData-XML-Dokument, das nun
angezeigt wird, zeigt die Datengruppe "Appointment".
Im nächsten Schritt kann der OData-Dienst konsumiert werden.
3. Beziehungen
Beziehungen und Referenzen zwischen Intrexx-Datengruppen werden in OData als Associations und Navigation-Properties abgebildet.
Dabei können 1:1 und 1:n Beziehungen definiert werden. Beziehungen mit m:n Kardinalität
lassen sich über eine m:n Datengruppe abbilden. Associations definieren in OData die Beziehungen und deren
Kardinalität zwischen Entity-Types. Navigation-Properties wiederum fügen den Entity-Types Properties hinzu,
mit denen von einem Datensatz zu einem referenzierten Datensatz navigiert werden kann, ohne dass dem
Entity-Type explizit die Foreign-Key- bzw. Referenzdatenfelder hinzugefügt werden müssen. Über den Dialog
Beziehungen
werden die dafür notwendigen Einstellungen getroffen.
4. Dateien
Um über einen OData-Service auf Dateien aus Dateifeldern
in Datengruppen zugreifen zu können, muss dem Service das entsprechende Dateifeld hinzugefügt werden.
Da Intrexx für Dateifelder zusätzliche Metadaten-Felder vorhält, werden dem Entity-Type pro Dateifeld automatisch
ein Feld mit dem komplexen Datentyp IxFile hinzugefügt. Dieser beinhaltet neben der Datei
auch Metadaten, wie z.B. Dateiname, Typ und Größe. Außerdem stehen drei Funktionen für den Zugriff und die Verwaltung von Dateien
zur Verfügung. Für den Zugriff auf Dateien gibt es zwei Möglichkeiten, die im Folgenden erläutert werden.
Einbetten von Dateien in OData-Feeds
Die erste Möglichkeit ist die direkte Einbettung eines Dateiinhalts als Base64-kodierter binärer String in
einen OData-Feed bzw. -Entry. Dies stellt die einfachste Methode für den Zugriff auf eine Datei dar, indem
diese direkt mit dem Ergebnis einer OData-Abfrage mitgeliefert wird. Der Connector für OData kann den Dateiinhalt
extrahieren und lokal als Datei speichern bzw. in ein anderes Dateifeld einer Zieldateigruppe übertragen und die
Datei im Browser über das Dateiauswahl-Element
anzeigen. Auch das Speichern und Aktualisieren von einzelnen
Dateien über die Dateiauswahl ist möglich.
Der Nachteil dieses Ansatzes ist, dass pro Dateifeld nur eine Datei geliefert werden kann. Im Fall von
Mehrfachdateifeldern ist dies immer die erste Datei, wobei beim Speichern
immer eine neue Datei hinzugefügt wird. Außerdem wird die Performance des Services wesentlich beeinträchtigt,
da die Datei zunächst komplett in den Hauptspeicher geladen werden muss, um dort kodiert bzw. dekodiert zu werden.
Daher sollte diese Methode nur für kleinere Dateien verwendet werden.
OData-Funktionen für Dateien
Eine wesentlich flexiblere und ressourcenschonendere Möglichkeit für den Zugriff auf Dateien über OData
bieten die upFile-Funktionen, die in jedem Intrexx OData-Service automatisch
zur Verfügung stehen. Über diese Funktionen können Dateien gespeichert und abgefragt werden. Außerdem wird volle
Unterstützung für Mehrfachdateifelder in Intrexx geboten. Der einzige Nachteil dabei ist, dass die Dateikontrollen
in Intrexx diesen Ansatz nicht unterstützen, weshalb in Intrexx-Webapplikationen der Download bzw. Upload von
Dateien via JavaScript oder Groovy projektspezifisch realisiert werden muss. Folgende Funktionen bietet ein
Intrexx OData-Service zur Verwaltung von Dateien.
upFileList Die Funktion upFileList liefert
eine Liste mit allen Dateien eines Dateifeldes. Als Parameter werden erwartet:
recId: Der Primärschlüssel des Datensatzes mit dem Dateifeld.
upFileResource – upload Ermöglicht einen Stream-basierten Upload einer Datei.
Dies ist die schnellste und ressourcenschonendste Methode um Dateien an den Service zu übertragen. Als Parameter
werden für die Methode uploadFile erwartet:
recId: Der Primärschlüssel des Datensatzes mit dem Dateifeld.
upFileResource - download Ermöglicht einen Stream-basierten Download einer Datei.
Dies ist die schnellste und ressourcenschonendste Methode um auf Dateien zuzugreifen. Als Parameter werden für die
Methode downloadFile erwartet:
recId: Der Primärschlüssel des Datensatzes mit dem Dateifeld.
disposition (optional): Der Content-Disposition Header Typ (entweder inline oder attachment).
5. SSL-Konfiguration
Wenn in den OData-Provider-Einstellungen
die Verwendung von SSL aktiviert ist, ist ein Zugriff auf die OData-Dienste nur über das HTTPS-Protokoll
möglich. Damit SSL verwendet werden kann, benötigt der Server ein X.509-Zertifikat, das zusammen mit dem Zertifikat der
Certificate Authority in einem Keystore gespeichert wird. Zum Testen von SSL ist es möglich, ein sogenanntes
selbstsigniertes Zertifikat zu erstellen. Für den Produktiveinsatz sollte ein Zertifikat von einer öffentlichen
Zertifizierungsstelle verwendet werden, da ansonsten Warnungen im Browser angezeigt werden bzw. OData-Clients eine
SSL-Verbindung ablehnen. Im Folgenden wird beschrieben, wie ein selbstsigniertes Zertifikat zum Testen erzeugt und in einem Keystore
gespeichert werden kann. Weitere Informationen, insbesondere zum Importieren von vertrauenswürdigen Zertifikaten finden Sie
hier.
Erstellen eines Keystores mit SSL-Zertifikat
Öffnen Sie die Eingabeaufforderung unter Windows bzw. eine Shell unter Linux und wechseln Sie in das
bin-Verzeichnis Ihrer Java-JDK-Installation (z.B. /jre/windows/amd64/bin). Führen Sie dann folgenden Befehl aus:
$ keytool -keystore /path/to/keystore.ks -alias odata -genkey -keyalg RSA
Enter keystore password: password
What is your first and last name?
[Unknown]: odata.intrexx.com
What is the name of your organizational unit?
[Unknown]: OData
What is the name of your organization?
[Unknown]: United Planet GmbH
What is the name of your City or Locality?
[Unknown]:
What is the name of your State or Province?
[Unknown]:
What is the two-letter country code for this unit?
[Unknown]:
Is CN=odata.intrexx.com, OU=OData, O=United Planet GmbH,
L=Unknown, ST=Unknown, C=Unknown correct?
[no]: yes
Enter key password for <odata>
Das Programm fragt nun ein Passwort für den Keystore und Angaben zum Server-Zertifikat ab. Bei der Frage nach dem Vor- und Nachnamen
geben Sie den Hostnamen des OData-Servers an, wie er in der Service Endpoint-URL definiert wurde.
6. Authentifizierungsmethoden
Authentifizierung und Berechtigungen
Um einen sicheren Zugriff auf die Daten des Portals über OData-Services zu gewährleisten, erfolgt die Benutzer-Authentifizierung
über Login-Methoden des Portalservers. Im Folgenden wird beschrieben, welche Arten von Authentifizierungsmethoden unterstützt werden und wie
diese konfiguriert werden. Es kann dabei eine globale Methode für alle Services oder pro Service eine spezifische Methode definiert werden.
Die Datengruppenberechtigungen eines Benutzers werden bei OData-Anfragen wie
im Portal durch den Intrexx Portalserver geprüft. Besitzt ein Benutzer nicht ausreichende Berechtigung zum
Lesen oder Ändern von Datensätzen,
so antwortet der OData-Service entweder mit einer leeren Ergebnismenge oder einem Berechtigungsfehler.
Intrexx-Authentifizierung
Bei der Intrexx-Authentifizierung
erfolgt die Anmeldung mit Benutzername und Passwort, wobei das Passwort mit einem vom Server
bereitgestelltem Challenge-Key verschlüsselt übertragen wird. Dies ist die empfohlene Methode, um von einem Intrexx-Portal auf einen
OData-Service in einem anderen Intrexx-Portal zuzugreifen.
Plain-Text-Authentifizierung
Die Plain-Text-Authentifizierung entspricht der
HTTP-Basic-Authentifizierungsmethode.
Damit kann eine Anmeldung am Service direkt im Browser erfolgen. Allerdings wird dabei das Passwort unverschlüsselt übertragen,
weshalb diese Methode nur bei gleichzeitig aktivierter SSL-Verschlüsselung eingesetzt werden sollte.
Kombinierte Intrexx und Plain Text Authentifizierung
In der Regel wird für OData-Services eine Kombination aus Intrexx- und Plain-Text-Authentifizierung verwendet.
Zunächst wird versucht, den Client via Intrexx-Authentifizierung anzumelden. Schlägt dies fehl, wird eine Plain-Text-Authentifizierung
durchgeführt. Sollte auch diese zu einem Fehler führen, wird die Anfrage des Clients verweigert.
Windows-Integrierte-Authentifizierung
Bei der Windows-Integrierten-Authentifizierung
werden die Benutzer über das Active Directory/LDAP ermittelt und über das Kerberos-Protokoll angemeldet. Dadurch lässt sich ein
Single-Sign-On in Windows-Umgebungen realisieren. Diese Methode steht nur mit Microsoft Windows Server und einer
Domänenumgebung zur Verfügung. Sobald für ein Portal die Windows-Integrierte-Authentifizierung aktiviert wird, müssen sich OData-Benutzer mit Ihrem
Windows-Benutzernamen (Domäne/User) und Kennwort an einem OData-Service anmelden. Um auch OData-Anfragen direkt mit dem angemeldeten Windows-Benutzer
und damit ohne zusätzliche Anmeldung zu authentifizieren, sind weitere Schritte notwendig.
Zum einen ist eine Drittanbieter-Bibliothek erforderlich, die dem Installationsverzeichnis /lib
hinzugefügt werden muss. Kopieren Sie dazu die Datei waffle-jna-1.6-with-dependencies.jar aus dem
Installationsverzeichnis /adapter/odata/kerberos/ in das /lib-Verzeichnis.
Anschließend führen Sie einen Neustart des Portalserver-Dienstes durch. Außerdem muss die Login-Methode
für den OData-Server auf Windows-Integrierte-Authentifzierung umgestellt werden. Öffnen Sie dazu mit einem Texteditor die Datei om.cfg
im Portalverzeichnis /internal/cfg.
Suchen Sie darin nach der Zeile, die mit
Wiederholen Sie den Schritt für alle weiteren OData-Service-Einträge, für die die Kerberos-Authentifizierung aktiviert werden soll. Nach dem
Speichern der Datei muss der Portaldienst neu gestartet werden.
Trusted Authentifizierung
Bei der Trusted-Authentifizierung kann ein Benutzer allein über die Benutzer-GUID angemeldet werden.
Dabei wird erwartet, dass im HTTP-Request die Benutzer-GUID als Benutzername gesendet wird. Dies ist
die unsicherste Methode und sollte ausschließlich in vertrauenswürdigen Umgebungen eingesetzt werden.
Konfiguration der Authentifizierungsmethode
Die globale oder service-spezifische Authentifizierungsmethode wird in der Datei om.cfg definiert.
Als Default definiert Intrexx für alle OData-Dienste die Methode IntrexxAuth. Um eine
andere Methode zu verwenden oder die Methode für einen spezifischen Service zu überschreiben, öffnen Sie die Datei
im Portalverzeichnis /internal/cfg mit einem Texteditor.
Der Eintrag scope=odataservice definiert die globale Methode für alle OData-Services. Im auth-type-Attribut
wird die Authentifzierungsmethode hinterlegt. Zur Auswahl stehen:
ODataAuth
IntrexxAuth
PlainTextAuth
IntegratedAuth
IntegratedAuthClient
TrustedAuth
Um für einen Service die globale Methode zu überschreiben, kopieren Sie den Eintrag und ändern Sie das scope-Attribut wie folgt:
Nach dem Doppelpunkt ist der Name des OData-Services aus der Service-Konfiguration anzugeben. Nach dem Speichern der
Konfigurationsdatei und einem Neustart des Portaldienstes
wird die Service-spezifische Konfiguration verwendet.