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 (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 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 mittels 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 (VP/GDA) gegenüber ELGA erfolgen. Hierfür ist die Angabe der ELGA-Rolle des GDA, sowie die Angabe des ausführenden GDA-Mitarbeiters bzw. des Prozesses notwendig. Im eCS wird die Eingabe dieser Daten zum Zeitpunkt des Dialogaufbaus verlangt. D.h. die Daten werden einmal für den Dialog eingegeben (im Zuge der Funktion setdialogAddress()) 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-Portal 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 optional. D.h. sofern der GDA keinerlei Funktionalität aus ELGA über das eCS nutzt, ist die Angabe von ELGA Daten an dieser Stelle nicht notwendig.
Werden Daten eingegeben, muss immer verpflichtend eine ELGA-Rolle des GDA, sowie wahlweise des 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 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 Sozialversicherungsnummern-Abfrage-Service (SAS) 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 System 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 (PROD-Instanz) bzw. GET https://services-a.ecard-test.sozialversicherung.at/<service-name>/<versionsnummer>/status (VPSWH-Instanz)

Ist der Server erreichbar, wird die 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 dem selben 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 parallelen Requests) führen. Vor dem Senden eines neuen Requests mit einer bestimmten dialogId sollte daher immer auf die Response des zuvor abgesetzten Requests mit identer dialogId 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? Ist ein Dialog noch gültig (Inaktivitäts-Timeout, siehe Bild)?).
Dialog-Timeouts 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 wird der HTTP Header des Requests im eCS auf folgende Parameterangaben überprüft:
  • X-SVC-CLIENT-IP
  • X-SVC-CLIENT-TXID

X-SVC-CLIENT-IP:

Dieser Parameter dient der Identifikation des Vertragspartner-Anschlusses.

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

Findet die Übermittlung des Requests 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

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. Wird eine Hersteller-ID angegeben, muss dies eine im eCS bekannte und gültige ID sein.

Alle Parameter sind verpflichtend anzugeben.

Verwaltung der Kartenleser (CRS - Card Reader 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).

Zugriff auf den Kartenleser (REST-Service Kartenleser)

Die Kommunikation mit dem GINO Kartenleser erfolgt per REST-Service.

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

Übertragung von Attachments (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 Service 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 Attachments 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 VP-Siganturtoken (Admin-Karte) (unter Verwendung der Funktion authenticateDialog()) vorgesehen. Für Vertragspartner aus dem Krankenanstaltenbereich ist die Wahl des Dialogaufbaus anhand der Ausstattung in der Krankenanstalt zu treffen.

Der Dialogaufbau besteht aus zwei Teilschritten:
  1. Dialogerzeugung- und authentifizierung
  2. Setzen der Ordination und des Tätigkeitsbereichs (sowie ggf. von ELGA Daten)

Für den Dialogaufbau muss ein o-card VP-Siganturtoken (Admin-Karte) 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 Kartenleser.
Aufruf der Funktionen zum Dialogaufbau:
  • authenticateDialog() - Autorisierung des Vertragspartners
Szenario 4  -  Dialogaufbau (o-card VP-Siganturtoken (Admin-Karte)):
AUTH Szenario - Dialog aufbauen

Dialogschließung

Die Schließung des Dialogs kann durch ein 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