Anlage 6 - Schnittstelle VIS - VAPI-Java_Konfiguration.pdf

[Seite 1]

VIS VAPI-Java

Konfiguration

Version: 6.5

Stand: 28. März 2024

[Seite 2]

© Copyright by PDV GmbH Haarbergstraße 73 99097 Erfurt

Alle Rechte vorbehalten. Sämtliche Angaben vorbehaltlich technischer Änderungen. Trotz sorgfältiger Prüfung wird für den Inhalt keine Haftung übernommen. Alle aufgeführten Warennamen sind eingetragen und als solche zu behandeln.

Im Interesse der besseren Lesbarkeit des Textes wird auf geschlechterspezifische Formulierungen verzichtet. Die männliche Form wird als generisches Maskulinum und damit ausdrücklich als Sammelbezeichnung für beide Geschlechter verwendet.

Nachdruck und Vervielfältigung – auch auszugsweise – nur mit Genehmigung der PDV GmbH, Erfurt

[Seite 3]

Inhaltsverzeichnis

Inhaltsverzeichnis

1 Einleitung ................................................................................................................ 4 1.1 Begleitende Dokumente ........................................................................................ 4 2 Software Development Kit ..................................................................................... 5 3 Proxy-Einstellung ................................................................................................... 6 4 VAPI-Schnittstelle ................................................................................................... 7 4.1 Stub-Generierung.................................................................................................. 7 4.2 Sicherheit .............................................................................................................. 8 5 Konfigurationsbeispiel ........................................................................................... 9 5.1 VAPI-Client-Instanz erzeugen ............................................................................... 9 5.2 Authentifizierung gegenüber VIS ........................................................................... 9 5.3 Aufruf einer VAPI-Funktion .................................................................................. 12 5.4 Aufbau der VAPI-Samples-Methoden .................................................................. 16

3

[Seite 4]

Einleitung

1 Einleitung

1.1 Begleitende Dokumente

Tabelle 1: Begleitende Dokumente

4

[Seite 5]

Software Development Kit

2 Software Development Kit

Für eine einfache Nutzung des VAPI-Webservice stellt die PDV GmbH clientseitige Software Development Kits (SDK) bereit. Diese stellen eine Sammlung von Programmierwerkzeugen und Programmbibliotheken dar, welche die Arbeit mit VAPI erleichtern.

Für einen VAPI-Java-Client steht Ihnen der vapiclient-cxf--dist.zip zur Verfügung, welcher das WebService-Framework CXF nutzt. Zusätzlich kann projektspezifisch ein Client auf Basis des Glassfish Metro Frameworks mit leicht eingeschränkten Funktionsumfang bereitgestellt werden.

5

[Seite 6]

Proxy-Einstellung

3 Proxy-Einstellung

Um den VAPI-Java-Client mittels eines Proxys zu betreiben, können zwischen gängigen Vorgehensweisen wählen. Beispielsweise können Sie beim Start der Java Virtual Machine die Proxyeinstellungen mit den Parametern http.proxyHost und http.proxyPort vorgenommen werden.

6

[Seite 7]

VAPI-Schnittstelle

Stub-Generierung

4 VAPI-Schnittstelle

Um komfortabel aus Fremdanwendungen über die VAPI-Schnittstelle auf VIS-Funktionalitäten zugreifen zu können, sollten die mitgelieferten Clientbibliotheken verwendet werden. Steht für die gewünschte Umgebung keine geeignete Clientbibliothek zur Verfügung, können Sie mithilfe der mitgelieferten WSDL (Web Service Description Language) selbst ein Stub erzeugen. Das Vorgehen hierfür wird im Folgenden exemplarisch beschrieben.

4.1 Stub-Generierung

Der VAPI-Webservice wird durch die mitgelieferten WSDL vollständig beschrieben. Auf Grundlage dieser Beschreibung ist das automatische Generieren eines sogenannten Stubs oder auch Proxys in nahezu jeder modernen Entwicklungsumgebung möglich.

Unter Zuhilfenahme eines Java Development Kits (JDK) kann in der Windows- Kommandozeile folgender Befehl zum Erzeugen eines Stubs verwendet werden:

wsimport -keep -verbose http://<>:<>/vis/<>/service/VapiWSMTOM?wsdl- extension http://<>:<>/vis/<>/service/VapiWSMTOM?wsdl

7

[Seite 8]

VAPI-Schnittstelle

Sicherheit

4.2 Sicherheit

Das Verschlüsseln und Signieren der Nachricht erfolgt durch die Verwendung von WS- Security nach OASIS Standard 200401:

http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0.pdf

Es werden Kerberos-, x509-Zertifikate und das Basic-Verfahren zur Authentifizierung unterstützt. Zur Erstellung eines Clients kann auf die Bibliothek eines Drittherstellers zurückgegriffen werden.

Empfohlen wird die Verwendung von Apache AXIS + WSS4J. Weiterführende Informationen hierzu entnehmen Sie dem folgenden Link:

http://ws.apache.org/wss4j/

Alternativ eignet sich die Verwendung von Apache xFire verwenden.

8

[Seite 9]

Konfigurationsbeispiel

VAPI-Client-Instanz erzeugen

5 Konfigurationsbeispiel

Im folgenden Kapitel werden die Funktionalitäten der Clientbibliothek anhand von Beispielen aus dem Projekt VAPI-Samples näher erläutert. Einen Einstiegspunkt in die VAPI-Samples bietet die Klasse Main.java. In dieser Klasse kann eine Client-Instanz erzeugt, sowie alle konfigurativen Einstellungen zur Authentifizierung vorgenommen werden. Weiterhin erfolgt in der Klasse Main.java der Aufruf von VAPI-Funktionen.

5.1 VAPI-Client-Instanz erzeugen

Um eine Client-Instanz zu erzeugen, müssen folgende Werte bekannt sein: • VIS-Endpoint • VIS-Mandant

Diese Werte können Sie wie folgt in der Datei Main.java anpassen.

String endpoint = "http://<>:<>/vis/<>/service/VapiWSMTOM";

String mandant = "{<>}";

1. Schritt: VAPI-Objekt erzeugen (z.B. VapiWS)

var client = new VapiWS(mandant, endpoint);

Die Erzeugung einer Client-Instanz können Sie anschließend in der VapiWS-Klasse vornehmen.

5.2 Authentifizierung gegenüber VIS

Damit die Anfragen der Clientanwendung vom VIS-Server akzeptiert werden, muss sich die erzeugte VAPI-Client-Instanz gegenüber VIS authentifizieren. Hierfür bieten sich die folgenden drei Möglichkeiten an:

1 - Authentifizierung über Kerberos

final VapiWS client = new VapiWSKrb(mandant, endPoint);

client.setIntegratedAuthentication();

2 - Ausführung mittels Basic-Authentifizierung

final VapiWS client = new VapiWS(mandant, endPoint);

client.setAuthentication(username, password);

9

[Seite 10]

Konfigurationsbeispiel

Authentifizierung gegenüber VIS

3 - Authentifizierung mit dem OAuth2-Verfahren

Innerhalb der VAPI-Samples werden Methoden bereitgestellt, die jeweils eine der drei zuvor aufgeführten Authentifizierungsmöglichkeiten beinhalten:

// Kerberos-Authentifizierung

final VapiWS client = getClientKerberosAuth(mandant, endPoint);

// Basic-Authentifizierung

final VapiWS client = getClientBasicAuth(mandant, endPoint,

username, password);

//OAuth2-Authentifizierung

final VapiWS client = getClientOAuth (mandant, endPoint);

Die Verwendung des Authentifizierungsverfahrens OAuth2 wird nachfolgend näher erläutert.

Authentifizierung mit OAuth2

Die OAuth-Authentifizierung wird nur für den VAPI-Java-Client auf Basis des CXF-Frameworks bereitgestellt und setzt auf das OAuth2-Verfahren password grant type. Ähnlich wie bei der Basic-Authentifizierung ist das Verfahren im Rahmen von VAPI auf die Authentifizierung eines einzelnen Service-Nutzers ausgerichtet.

Um die OAuth-Authentifizierung zu nutzen, müssen Sie die Klasse VapiWSOauth wie folgt anpassen:

VapiWS vapiClient = new VapiWSOauth(mandantGuid, endpointURL);

Zusätzlich muss gegen den VAPI-Endpoint im OAuth2-Securitykontext gearbeitet werden:

http://server:port/vis/MANDANTGUID/oauth/service/VapiWSMTOM

10

[Seite 11]

Konfigurationsbeispiel

Authentifizierung gegenüber VIS

Die benötigten OAuth2-Authentifizierungs-Daten müssen im Classpath der Konfigurationsdatei oauth2.properties bereitgestellt werden. Im Vapi-Samples-Projekt kann diese Datei in den Ordner resources eingebunden werden.

Beispiel:

accessToken=0a232e3c-410d-4922-8c99-9ffdaa418699

refreshToken=dafa34d2-8855-48c0-b9d8-25bf2f829fd3

tokenEndpoint= http://<>:<>/vis/<>/mvc/oauth/token

clientId=vapi

clientPassw0rd=password123

Mit dem tokenEndpoint ist ein TokenService zur Generierung von accessToken und refreshToken bereitgestellt. Dadurch wird sichergestellt, dass nur berechtigte Client- Anwendungen Token generieren können.

Username und Password eines Nutzers werden nur bei der initialen Token-Generierung (in gesicherter Umgebung, z. B. localhost) im Post-Body übergeben. Bei späteren Aktualisierungen des accessToken wird statt der Nutzerinfos, der refreshToken übergeben. Mittels dieser Authentifizierung durch die Anwendung selbst, lassen sich DoS-Angriffe effektiv vermeiden.

So authentifizieren Sie sich mit OAuth2:

1 - Generieren Sie manuell das accessToken, sowie das refreshToken und übertragen Sie diese in die oauth2.properties-Datei:

curl -v vapi:password123@localhost:PORT/vis/MANDANTGUID/mvc/oauth/token -d grant_type=password -d username=UPN -d password=PWD

2 - Der VAPI-Client nutzt das accessToken für die Authentifizierung. Anschließend können Sie den VAPI-Client nutzen, bis das accessToken seine Gültigkeit verliert.

Hat das accessToken keine Gültigkeit mehr, generiert der VAPI-Client mithilfe des refreshTokens ein neues accessToken und schreibt dieses in die oauth2.properties.

11

[Seite 12]

Konfigurationsbeispiel

Aufruf einer VAPI-Funktion

Die Authentifizierung mit OAuth2 bietet folgende Sicherheitsmerkmale: • die einmalige Nutzung von Benutzername und Passwort in einer gesicherten Umgebung • die Nutzung eines accessTokens mit zeitlich begrenzter Gültigkeit • die seltene Nutzung eines refreshTokens mit zeitlich unbegrenzter Gültigkeit • einen eingeschränkten Bereich, in der die Tokens nutzbar sind, in diesem Fall VAPI

5.3 Aufruf einer VAPI-Funktion

Innerhalb der VAPI-Samples sind alle VAPI-Funktionen in eigenständigen Klassen aufgeteilt. Um von der Main.java eine VAPI-Funktion ausführen zu können, muss zuvor ein Import der jeweiligen Klasse in das Package der Main.java integriert werden:

import static de.pdv.vapisamples.bo.cru.CreateBo.*;

Jede Klasse enthält eine oder mehrere VAPI-Sample-Methoden, wobei jede Methode einen in sich abgeschlossenen Anwendungsfall beinhaltet. Im nachfolgenden Beispiel wird in der Klasse CreateBo die Methode createBoAkte aufgerufen, die zur Erstellung einer Akte in VIS dient:

createBoAkte(client, vapiOptions);

Bei jedem Methodenaufruf wird mindestens das erzeugte VAPI-Client-Objekt (siehe Kapitel 5.1 VAPI-Client-Instanz erzeugen) übergeben. Manche Methoden, wie beispielsweise createBoAkte benötigen zur Ausführung noch weitere Parameter. In diesem Fall handelt es sich um eine ExportImport-Option, die im Parameter vapiOptions übergeben wird.

12

[Seite 13]

Konfigurationsbeispiel

Aufruf einer VAPI-Funktion

Eine Übersicht zu den EExportImport-Optionen entnehmen Sie der technischen VAPI-SDK-Dokumentation. Diese finden Sie im Ordner vapiclient-cxf- des VAPI-SDK. Wählen Sie dort den Unterordner Dokumentation aus und öffnen Sie die Datei index.html mit einem Doppelklick.

Abbildung 1: Aufruf der technischen VAPI-Dokumentation

13

[Seite 14]

Konfigurationsbeispiel

Aufruf einer VAPI-Funktion

Auf der Startseite ist eine Übersicht zu allen im VAPI-Client verfügbaren Klassen, Schnittstellen und Enumerationen ersichtlich. Um eine Auswahl der möglichen Optionen für den Export und Import zu erhalten, wählen Sie den Menüpunkt EExportImport im Abschnitt Class Summary aus.

Abbildung 2: Übersicht der technischen VAPI-Dokumentation mit Abschnitt Class Summary

14

[Seite 15]

Konfigurationsbeispiel

Aufruf einer VAPI-Funktion

Anschließend wird Ihnen im Abschnitt Fields eine Übersicht zu den verfügbaren EExportImport-Optionen angezeigt, aus der Sie die gewünschte Funktion für die createBo-Methode zum Erzeugen einer neuen Akte auswählen können.

Abbildung 3: Ausschnitt der EExportImport-Optionen im Abschnitt Fields

Auch ein bli

15

[Seite 16]

Konfigurationsbeispiel

Aufbau der VAPI-Samples-Methoden

5.4 Aufbau der VAPI-Samples-Methoden

Jede VAPI-Sample-Methode besteht aus zu konfigurierenden Parametern und einer VAPI-Funktion. Die Definition der jeweiligen Funktion und eine Erklärung ihrer Parameter können Sie in der technischen Dokumentation des VAPI-Clients einsehen. Aufbau und Verwendung der VAPI-Samples wird im Folgenden exemplarisch anhand der Methode createBo() erläutert.

So sehen Sie die Definition einer Methode in den VAPI-Samples ein:

1 - Navigieren Sie auf der Übersichtsseite der technischen VAPI-Dokumentation zu dem Menüpunkt VapiWS im Abschnitt Class Summary.

Zwischenergebnis: Eine Übersicht mit den allgemeinen Klassendefinition, Konstruktoren und Methoden der VapiWS-Klasse wird angezeigt.

Abbildung 4: Abschnitt Class Summary mit Menüpunkt VapiWS zur Implementierung der VAPI-Schnittstelle

16

[Seite 17]

Konfigurationsbeispiel

Aufbau der VAPI-Samples-Methoden

2 - Im Abschnitt All Methods wählen Sie anschließend die Methode createBo aus.

Ergebnis: Die Definition der Methode wird angezeigt.

Abbildung 5: Auszug aus der Definition der VapiWS-Klasse mit Methode createBo

17

[Seite 18]

Konfigurationsbeispiel

Aufbau der VAPI-Samples-Methoden

Neben genaueren Informationen zur Definition werden Ihnen hier zusätzlich die zur Ausführung benötigten Parameter angezeigt. Sie können die Parameter der Methode createBo nach Bedarf anpassen.

Abbildung 6: Definition und konfigurierbare Parameter der Funktion createBo in den VAPI-Samples

18

[Seite 19]

Konfigurationsbeispiel

Aufbau der VAPI-Samples-Methoden

Nach Anpassung der Parameter und abschließender Ausführung des Programms, erhalten Sie entsprechend der vorgenommenen Konfigurationen eine VIS-ID des neu erstellten Objekts. Das Ergebnis können Sie anschließend in einer Konsolenausgabe (z. B. der IntelliJ-Konsolenausgabe) überprüfen.

Die nachfolgende Abbildung zeigt das Ergebnis der Erstellung einer neuen Akte mithilfe der VAPI-Funktion createBo in der IntelliJ-Konsolenausgabe.

Abbildung 7: Ergebnis der VAPI-Funktion createBo in der Windows-Eingabeaufforderung

19