Daten anbieten - Connector für OData

Modul Integration Daten anbieten

1. Dienst erstellen

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:


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.



In diesem Dialog wird der die Applikation persönlicher Kalender und seine Kalender-Datengruppe ausgewählt.



Setzen Sie in diesem Dialog die folgenden Einstellungen:


In diesem Dialog werden die Datenfelder ausgewählt, auf die der OData-Service zugreifen wird: 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: 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".



Alternativ können Sie über das Hauptmenü OData / Metadaten anzeigen das OData-XML-Dokument anzeigen, das die Service-Metadaten auflistet.



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.

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 
<binding scope="odataservice" auth-type="IntegratedAuthClient"/>
beginnt und ändern Sie den Wert im Attribut auth-type zu IntegratedAuth. 
<binding scope="odataservice" auth-type="IntegratedAuth"/>
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. 
<?xml version="1.0" encoding="UTF-8"?>
<configuration>
	<authentication anonymous="05CE8CE3035924F7D3088895F1D87DADD65CFAE4">
		<binding scope="web" auth-type="IntrexxAuth"/>
		<binding scope="client" auth-type="IntrexxAuth"/>
		...
		<binding scope="odataservice" auth-type="ODataAuth"/>
		...
	</authentication>
/configuration>
Der Eintrag scope=odataservice definiert die globale Methode für alle OData-Services. Im auth-type-Attribut wird die Authentifzierungsmethode hinterlegt. Zur Auswahl stehen: Um für einen Service die globale Methode zu überschreiben, kopieren Sie den Eintrag und ändern Sie das scope-Attribut wie folgt: 
<binding scope="odataservice:MyService" auth-type="PlainTextAuth"/>
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.

7. Weitere Informationen

Allgemeines
Systemvoraussetzungen
OData-Daten konsumieren
Funktionsparameter in Groovy
OData-Daten in Applikationen einbinden
Export / Import
Appendix