Skip navigation links

Package at.chipkarte.client.auth.soap

Interface und Klassen des Authentifizierungsservice (AUTH).

See: Description

Package at.chipkarte.client.auth.soap Description

Interface und Klassen des Authentifizierungsservice (AUTH). Enthält den SOAP Endpoint IAuthService sowie die dazu notwendigen Klassen.

Inhalt der AUTH package-Beschreibung:


Allgemein

Vertragspartner

Vertragspartner im e-card-System (eCS) besitzen eine Vertragspartnernummer (spezifiziert über die VPNR), eine oder mehrere Ordinationen/Standorte (der Parameter OrdinationId im Objekt "Ordination" dient als Referenz der jeweiligen Ordinationsadresse in anderen Funktionen) sowie in diesen Ordinationen einen oder mehrere Tätigkeitsbereiche (der Parameter Id im Objekt "TaetigkeitsBereich" dient als Referenz des jeweiligen Tätigkeitsbereichs in anderen Funktionen).
Die Kombination aus der Ordination und des (in der Ordination gültigen) Tätigkeitsbereichs legt die gültigen Verträge und Servicerechte des Vertragspartners fest.

Im Zuge des Dialogaufbaus wird das Objekt VertragspartnerV2 zurückgeliefert. Dieses enthält die Informationen zum Vertragspartner, zu den einzelnen Ordinationen des Vertragspartners sowie die darin zulässigen Tätigkeitsbereiche.

Man unterscheidet verschiedene Tätigkeitsbereiche wie z.B. Arzt, öffentliche Krankenanstalt, Apotheke, Transportunternehmen, usw.

Ein Tätigkeitsbereich ist spezifiziert mittels eines Codes, eines Textes und einer ID. Zur weiteren Verwendung bei anderen Funktionen ist immer die TaetigkeitsbereichId (spezifisch für den Vertragspartner) zu verwenden. Äquivalent zur OrdinationId sollte auch die TaetigkeitsbereichId nicht in der Vertragspartnersoftware gespeichert werden. D.h. es sollte immer mit den aktuell zurückgelieferten IDs gearbeitet werden.
Zur Anzeige des Tätigkeitsbereichs für den Vertragspartner ist der mitgelieferte Text zu verwenden.

ELGA Nutzung über das e-card System (eCS)

Das eCS bietet als Service den ELGA-Adapter (ELGAAD) an. Dieser bildet definierte Funktionalitäten aus ELGA auf der SS12 ab. Dabei werden die geforderten bzw. verwendeten Strukturen aus ELGA (IHE, CDA, ...) auf einfacher zu verarbeitende Strukturen gemappt. Um diese Funktionalitäten im vollen Umfang nutzen zu können, muss unter anderem eine Authentifizierung des Vertragspartners/Gesundheitsdiensteanbieters gegenüber ELGA erfolgen. Hierfür ist die Angabe der ELGA-Rolle des GDAs, sowie die Angabe des ausführenden GDA-Mitarbeiters bzw. des Prozesses notwendig. Im eCS werden die Eingabe dieser Daten zum Zeitpunkt des Dialogaufbaus verlangt. D.h. die Daten werden einmal für den Dialog eingegeben (im Zuge der Funktion setdialogAdress() und sind in diesem Dialog nicht mehr änderbar.

Hinweise:
  • Angegebene ELGA Daten werden im Dialog gespeichert und im Bedarfsfall für die Authentifizierung gegenüber ELGA verwendet. Da die Daten erst im Bedarfsfall verwendet werden, wird erst dann über mögliche Fehlerzustände informiert die nur in den Backendsystemen von ELGA bekannt sind, wie z.B.: Der Vertragspartner hat nicht die angegebene Rolle.
  • Die angegebenen GDA-Mitarbeiterdaten sind (nach Zugriffsprotokollierung) für den ELGA Teilnehmer, sowie die ELGA Ombudsstelle am ELGA Bürgerportal sichtbar!
Wichtig: Dialoge mit denen ELGA-Zugriffe durchgeführt werden, gelten als personalisiert. Es ist darauf zu achten, dass für diese Dialoge keine Nutzung durch unterschiedliche Nutzer erfolgt (z.B. durch zwei Ärzte innerhalb einer Ordination). In diesem Fall muss jeder Arzt einen eigenen Dialog besitzen (bei dem der jeweilige Arzt als GDA-Mitarbeiter angegeben wird).

Die Angabe von ELGA Daten für den Dialog ist generell optional. D.h. sofern der GDA keinerlei Funktionalität aus ELGA über das e-card-System nutzt, ist die Angabe von ELGA Daten an dieser Stelle nicht notwendig.
Werden Daten eingegeben, muss immer verpflichtend eine ELGA-Rolle des GDAs, sowie wahlweise der GDA-Mitarbeiter oder eine Prozess-Kennzeichnung angegeben werden. Durch die Angabe der Daten beim Dialogaufbau, erhält der GDA bei den betroffenen Services ein entsprechendes Recht (siehe hierzu auch das Kapitel Rechte bzw die Konstanten für die Berechtigungen im eCS). Die Zuteilung der Rechte zu den jeweiligen Funktionen ist wie immer der entsprechenden Servicebeschreibung in der Javadoc zu entnehmen.

Rechte

Vertragspartner können bestimmte Services nur dann nutzen, wenn sie dazu berechtigt sind. Mittels der Funktion getBerechtigungen() ist es möglich die jeweiligen Berechtigungen des Vertragspartners abzufragen. Es werden dabei jene Rechte abgefragt, die der Vertragspartner mit dem aufgebauten Dialog (spezifiziert über die DialogId) besitzt. Die Ermittlung erfolgt hierbei mittels der beim Dialogaufbau angegebenen OrdinationId und TaetigkeitsBereichId.

Jedes Service benötigt dabei bestimmte Rechte z.B. benötigt das SAS-Service das Recht SAS.CORE.

Die Information, welches Recht bzw. welche Rechte ein Service benötigt ist bei der jeweiligen Servicebeschreibung bzw. den jeweiligen Funktionsbeschreibungen (Vorbedingungen) in der Javadoc zu finden.

Die Vertragspartnersoftware bzw. der Vertragspartnersoftware-Hersteller ist dazu angehalten dem Vertragspartner nur dann Zugriff zu den jeweiligen Services zu gewähren, wenn die dazu benötigten Rechte vorhanden sind.

Online-/Offline-Status

Ob eine Verbindung für ein bestimmtes Service zum e-card-Serversystem besteht, sollte im Normalbetrieb NICHT abgefragt werden! Die Abfrage sollte nur dann durchgeführt werden um festzustellen, ab wann das Service wieder online ist, wenn zuvor Verbindungsprobleme aufgetreten sind.

Die empfohlene Frequenz für die Abfragen liegt in diesem Fall bei > 1 Minute.

Die Abfrage ist über eine REST Schnittstelle durchzuführen:
GET https://services.ecard.sozialversicherung.at/<service-name>/<versionsnummer>/status (Produktions-Instanz) bzw. GET https://services-a.ecard-test.sozialversicherung.at/<service-name>/<versionsnummer>/status (VPSWH-Instanz)

Ist der Server erreichbar, wird der Response HTTP 200 retourniert. Im Offline-Fall wird keine Response retourniert.

Dialogverwaltung

Mit einem aufgebauten Dialog (spezifiziert über die DialogId) kann immer nur gleichzeitig ein Request verarbeitet werden. Werden zwei Requests mit demselben Dialog geschickt, muss der zweite Request warten bis der erste Request beantwortet wurde. Dies kann zu ungewollt langen Laufzeiten bzw. zu Request-Timeouts (bei vielen Requests "gleichzeitig") führen. Vor dem Senden eines neuen Requests sollte daher immer auf die Response des zuvor abgesetzten Requests gewartet werden. Bezüglich der Request-Timeouts siehe auch den Punkt "Request-Timeouts" im Kapitel "Voraussetzungen für die Vertragspartnersoftware" in Overview).

Die Vertragspartnersoftware ist dazu angehalten die erzeugten Dialoge zu verwalten und immer den aktuellen Stand zu jedem Dialog zu kennen (welche Dialoge gibt es, wer verwendet gerade welchen Dialog).
Dialoge die unter Angabe von ELGA-Daten (GDA-Mitarbeiter) aufgebaut wurden, sind personalisiert und dürfen daher nur von dem angegebenen GDA-Mitarbeiter verwendet werden!


HTTP Header-Informationen

Im Zuge der Request-Verarbeitung im e-card Server wird der HTTP Header des Requests auf folgende Parameterangaben überprüft:
  • X-SVC-CLIENT-IP
  • X-SVC-CLIENT-TXID
Hinweis: Diese Parameter sind für R23a nur in der VPSWH-Testumgebung freigeschaltet.

X-SVC-CLIENT-IP:

Dieser Parameter dient der Identifikation des Vertragspartner-Anschlusses.

Werden die Requests direkt über den Anschluss des Vertragspartners ans eCS-System gesendet, ist dieser Parameter nicht anzugeben. In diesem Fall wird im Zuge des Requests automatisch die richtige IP des Vertragspartners übermittelt und für die weitere Verarbeitung verwendet.

Findet die Übermittlung der Request jedoch über einen Server der VPSW statt (z.B. bei einer Cloud-Lösung), wird als IP die IP-Adresse des VPSW-Servers ermittelt (Remote-IP) und nicht mehr die des Vertragspartners (Client-IP/Anschluss-IP). In diesem Fall (Remote-IP ungleich der Client-IP/Anschluss-IP) muss die IP Adresse des Vertragspartners (Anschluss-IP, vergeben von SVC) explizit im HTTP-Header-Parameter X-SVC-CLIENT-IP angegeben werden.

Die Angabe ist in diesem Fall bei jedem Request zwingend notwendig. Erfolgt hier keine explizite Angabe der X-SVC-CLIENT-IP, können die Requests keinem Anschluss zugeordnet werden. Ein Dialogaufbau würde z.B. ebenfalls aufgrund der fehlenden Informationen und der unterschiedlichen Informationen innerhalb des anzugebenden Cardtokens fehlschlagen.

X-SVC-CLIENT-TXID:

Dieser Parameter dient der Zusammenführung der einzelnen Requests zwischen der VPSW und dem e-card System anhand eindeutiger Identifier.

Für jeden Request ist hierzu eine eindeutige ID per X-SVC-CLIENT-TXID im HTTP-Header anzugeben.
Hinweis: Im Gegensatz zur im nächsten Kapitel erklärten Transaction-Id ist die X-SVC-CLIENT-TXID auch bei Request-Wiederholungen stets eindeutig zu vergeben!

Mittels dieses Parameters sollen Requests über die Systemgrenzen der einzelnen Systeme VPSW/eCS hinweg zusammengeführt werden können um Fehleranalysen usw. zu vereinfachen.

Die Verwendung der X-SVC-CLIENT-TXID ist aktuell optional. Es wird jedoch bereits jetzt empfohlen die X-SVC-CLIENT-TXID bei jedem Aufruf zu versorgen.

Die X-SVC-CLIENT-TXID ist von der Vertragspartnersoftware zu generieren und hat folgende Anforderungen:
  • Für jeden neuen Request muss eine eigene X-SVC-CLIENT-TXID erzeugt werden
  • Darf weder mit null noch mit einem Leerstring versorgt werden
  • Darf nicht länger als 100 Zeichen sein
  • Muss für jeden Request (auch Request-Wiederholungen) eindeutig sein (Unique-Identifier)

Request Wiederholung

Verschoben, siehe Abschnitt "Request Wiederholung (Replay)" in Overview.

Produkt- Info

Im Zuge des Dialogaufbaus muss eine Produktinfo angegeben werden.
Diese beinhaltet folgende 3 Parameter:
  • Produkt-ID
    Produkt-Id des Softwareprodukts, das diese Schnittstelle implementiert. Die Id wird vom Dachverband der österreichischen Sozialversicherungsträger vergeben.
  • Produkt-Version
    Versionsinformation des Softwareprodukts, das diese Schnittstelle implementiert.
  • Hersteller-ID
    Hersteller-ID des Softwareherstellers. Die ID wird vom SVC-Partnersupport vergeben.
Die Produkt-ID und die Produkt-Version sind verpflichtend anzugeben.
Die Hersteller-ID ist ab einen gewissen Stichtag verpflichtend anzugeben. Informationen hinsichtlich des Stichtags sind beim Partnersupport zu erfragen.

Wird eine Hersteller-ID angegeben, muss dies eine im eCS bekannte und gültige ID sein.

Wichtig: Die Vergabe der Hersteller-IDs erfolgt durch den eCS Partnersupport.

Verwaltung der Kartenleser (CRS - Cardreader Service)

Per REST Service ist es möglich die verfügbaren Kartenleser abzufragen. Es werden dabei die zur IP Adresse registrierten Kartenleser ermittelt. Sofern Kartenleser-Gruppen definiert wurden, können auch diese abgefragt werden und zur Einschränkung der Suchergebnisse der Kartenleserabfrage verwendet werden. Die Konfiguration der Gruppen ist direkt über den GINO Kartenleser zu tätigen.

Die Dokumentation des REST-Services zur Verwaltung der Kartenleser ist zu finden unter: Swagger Doku Card Reader Service (CRS).

Server- und Kartenleserverfügbarkeit prüfen (CCS - Connectivity Check Service)

Um die Verfügbarkeit eines Kartenlesers zu prüfen, ist dieser mittels http Aufruf anzusprechen und die erhaltene Response zu verarbeiten. Die Verfügbarkeit des Servers kann per REST Service Call geprüft werden.

Die Dokumentation des REST-Services zur Prüfung der Server- und Kartenleserverfügbarkeit inkl. der Beschreibung zur Prüfung des Kartenlesers per HTTP-Call ist zu finden unter: Swagger Doku Connectivity Check Service (CCS).

Zugriff auf den Kartenleser (LANCCR Service)

Die Kommunikation mit dem LANCCR hat per REST Service zu erfolgen. Die Kommunikation per REST erfolgt aktuell über die GINA. Mit einer späteren Release wird dies umgestellt, sodass die Kommunikation direkt mit dem Kartenleser erfolgt (neue Kartenlesergeneration - GINO).
Hinweis: Durch die spätere Umstellung der Kommunikation direkt mit dem Kartenleser ändert sich nur die Aufruf-URL (Host).

Die Dokumentation des REST-Services zur Kommunikation mit dem Kartenleser ist zu finden unter: Swagger Doku LANCCR.

Übertragung von Attchments (ATS - Attachment Transfer Service)

Zur Übermittlung von Attachments an das eCS wird ein REST Service angeboten. Die fachlichen Informationen zu den Attachments sind jeweils im fachlichen Services bei den entsprechenden Funktionscalls anzugeben. Dabei wird eine Sicherheitskennung erzeugt. Mittels des REST Services wird die reine Übermittlung der Anlagen unter Angabe der zuvor retournierten Sicherheitskennung vorgenommen. Bei der Übermittlung wird eine Prüfung zwischen den zuvor übermittelten Anlage-Informationen und den aktuell zu übermittelnden Anlagen vorgenommen.

Hinweis: Das REST Service ATS wird aktuell nur im FUS Service unterstützt.

Die Dokumentation des REST-Services zur Übertragung von Attchments ist zu finden unter: Swagger Doku Attachment Transfer Service (ATS).

Funktionalität des AUTH-Service

Zur Nutzung vertragspartnerspezifischer Funktionen wird eine DialogId benötigt. Diese wird im Zuge des Dialogaufbaus erstellt.

Dialogaufbau

Um die Dienste/Services des e-card-Systems verwenden zu können, muss zuerst ein Dialog aufgebaut werden.

Für Vertragspartner im niedergelassenen Bereich ist ein Dialogaufbau mit einem o-card (Admin-Karte) CardToken (unter Verwendung der Funktion authenticateDialog()) vorgesehen. Für Vertragspartner aus dem Krankenanstalten-Bereich ist die Wahl des Dialogaufbaus anhand der Ausstattung in der Krankenanstalt zu treffen (siehe hierzu das separat an KIS-Hersteller ausgelieferte Dokument "Enterprise_Funktionalitaet.pdf").

Der Dialogaufbau besteht aus zwei Teilschritten:
  1. Dialogerzeugung- und authentifizierung
  2. Setzen der Ordination und des Tätigkeitsbereichs (sowie von ELGA Daten)
Hinweis: Die in den Szenarien bzgl. des Dialogaufbaus angegebenen Fehlermeldungen sind keine vollständige Aufzählung der möglicherweise auftretenden Fehlermeldungen, sondern sollen nur exemplarisch die möglichen Fehlervarianten veranschaulichen.
Für den Dialogaufbau muss ein o-card (Admin-Karte) CardToken unter Angabe der PIN erzeugt werden. Die Erzeugung liegt in der Verantwortung der VPSW. Die Funktionen des Dilaogaufbaus greifen nicht auf einen Kartenleser zu. Informationen hinsichtlich der Erstellung des Tokens finden Sie unter: Swagger Doku LANCCR.
Wichtig: Da im Zuge des Dialogaufbaus kein Kartenleser mehr angegeben werden kann, es aber noch Services gibt bei denen noch keine Umstellung auf den CardToken erfolgt ist, muss für diese Services entweder explizit einmal ein Kartenleser dem Dialog zugeordnet werden (siehe GINA Service) oder es muss bei der jeweiligen Funktion die CardReaderID angegeben werden um den Kartenleser zu setzen! Aufruf der Funktionen zum Dialogaufbau:
  • authenticateDialog() - Autorisierung des Vertragspartners
Szenario 4  -  Dialogaufbau (o-card (Admin-Karte) CardToken):
BASE Szenario - Dialog aufbauen

Dialogabbau

Die Beendigung des Dialogs kann durch explizites Abmelden über die Funktion closeDialog() oder durch Ablauf eines Timeouts erfolgen. Der automatische Wiederaufbau eines Dialogs nach einem Dialog-Timeout ist aus Sicherheitsgründen nicht zulässig. Auch das Durchführen von Funktionen zum Zwecke einer Aufrechterhaltung der Verbindung und damit der Umgehung des Dialog-Timeouts ist nicht zulässig.

Skip navigation links