# Package at.chipkarte.client.sts.soap

Interface und Klassen des Security Token Service (STS)

See: Description

- Interface Summary
  Interface | Description
  --- | ---
  IStsService | Dieses Service stellt die Funktionalitäten des Security Token Service (STS) zur Verfügung.

- Class Summary
  Class | Description
  --- | ---
  RequestSamlAssertionReq | Enthält die Eingangsdaten zum Aufruf der Funktion `requestSamlAssertion`.
  RequestSamlAssertionResp | Enthält die Ausgangsdaten der Funktion `requestSamlAssertion`.

## Package at.chipkarte.client.sts.soap Description

Interface und Klassen des Security Token Service (STS).

## Allgemein

Das Security Token Service (STS) bietet die Möglichkeit für Vertragspartner Security Tokens (Tickets) auszustellen.
Die ausgestellten Tickets können in weiterer Folge (nicht mehr Teil des STS-Services) verwendet werden, um sich bei einem definierten externen Gesundheitsdiensteanbieter zu authentifizieren.

### Rechte

Für die Funktionen des STS Services benötigt der Vertragspartner für die Durchführung das Recht STS.CORE.
Wird eine Funktion, welche dieses Recht benötigt, ohne das entsprechende Recht aufgerufen, erhält man die Exception AccessException.MISSING_STS_CORE.
Mittels der Funktion getBerechtigungen() aus dem BASE Service ist es möglich, die Rechte des Vertragspartners abzufragen.

### Online/Offline Status

Im laufenden Betrieb kann ein Offline-Zustand bzw. das Auftreten eines Verbindungsproblems in Abängigkeit der Kommunikationsart mit dem e-card System wie folgt identifiziert werden:

- die Kommunikation erfolgt direkt über die GINA:
  Die aufrufende Funktion retourniert eine entsprechende SOAP Exception (ServiceException.CONNECTION_ERROR).
- die Kommunikation erfolgt über den Proxy auf der GINA:
  Es wird als Response HTTP 503 retourniert.
- die Kommunikation erfolgt direkt mit dem Serversystem:
  Es erfolgt keine Response.

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: Der Aufruf erfolgt mittels:
GET https://<gina-adresse>/<service-name>/<versionsnummer>/status
Ist der Server erreichbar, wird der Response HTTP 200 retourniert. Ist der Server nicht erreichbar (Offline) und der Request wird über die GINA geschickt (direkt über die GINA bzw. über den GINA Proxy), wird der Response HTTP 503 retourniert.
Hinweis: Erfolgt die Kommunikation mittels GINA Proxy wird im HTTP 503 Response zusätzlich der Text "Die GINA konnte keine Verbindung zum Serversystem herstellen." im Response-Body befüllt.
Erfolgt die Abfrage direkt auf das Serversystem (nach Entfall der GINA) wird im Offline-Fall keine Response mehr retourniert.

### Prinzipielle Erklärungen

Das STS-Service stellt Tickets für Vertragspartner aus. Die Vertragspartner können diese Tickets zur Authentifizierung bei externen Gesundheitsdiensteanbietern verwenden.
Dem externen Gesundheitsdiensteanbieter wird im Ticket mitgeteilt, dass der Vertragspartner ein berechtigter Nutzer des e-card Systems ist und die Berechtigungen zum Dialogaufbau im eCS besitzt. D.h. die Gesundheitsdiensteanbieter können eine Vertragspartner Authentifizierung und/oder Patientenkontaktnachweis vornehmen, ohne ihr System an das e-card System koppeln zu müssen.
Die Tickets werden SAML 2.0 konform ausgestellt.
Die ausgestellten SAML Tickets können folgende Daten enthalten:

- ein Authentification-Statement, welches die Authentifizierung des Vertragspartners im e-card System bestätigt (gültiger Dialog)
- Attribute Statement mit ticketspezifischen

- Daten zum Vertragspartner
- Patientenkontaktnachweis (falls gefordert und vorhanden)

Weitere Informationen zu den aktuell unterstützten Tickets entnehmen Sie bitte den Dokument STS_Ticketinformation. Dieses Dokument wird im Zuge der Verteilung über die JavaDoc mitgeliefert. Bei Neuerungen (weitere unterstützte Tickets) während der Release wird das aktualisierte Dokument auf Anfrage, vom Partnersupport versendet.
Das STS-Service stellt nur das Ticket aus. Die Anbindung an die externen Gesundheitsdiensteanbieter ist NICHT Teil des STS-Service. D.h. die Verbindung und Kommunikation zum, sowie die Nutzung des Gesundheitsdiensteanbieter-Services werden hier nicht erläutert.

### CardToken

Aus der Funktionalität von STS heraus erfolgt kein Zugriff auf den Kartenleser. Wird eine Signatur mit einer Karte (e-card) gewünscht, muss beim Funktionsaufruf der entsprechende CardToken angegeben werden.
Ein Cardtoken kann mittels der REST Schnittstelle vom LANCCR angefordert werden.
Die Dokumentation des REST-Services zur Kommunikation mit dem Kartenleser ist zu finden unter: Swagger Doku LANCCR.
Bei der Anmeldung des Patienten kann, wenn eine e-card vorhanden ist, ein e-card Cardtoken (SV-Signaturtoken mit e-card) ausgestellt werden.
Das ausgestellte Cardtoken kann anschließend in der STS-Funktion anstelle einer (gesteckten) e-card verwendet werden.
Für die Ausstellung eines Authentifizierungstickets ist die Angabe eines Cardtokens nicht zulässig. Die Ausstellung erfolgt automatisch für den Vertragspartner des angemeldeten Dialogs.
Für die Ausstellung eines Patientenkontakt-Tickets ist nur die Nutzung eines e-card Cardtokens zulässig. Die Angabe eines o-card Cardtokens wird nicht unterstützt.
Das Stecken der Karte zum Ausführen der Funktion ist nicht mehr notwendig.
Das Cardtoken kann je nach Service für eine bestimmte Dauer nach Ausstellung genutzt werden. In der Regel ist ein ausgestellter CardToken für 10 Stunden verwendbar.
In STS wird nur das e-card Cardtoken unterstützt und dies nur für die Ausstellung eines Patientenkontakt-Tickets!

## Funktionalität des STS-Service

Es stehen folgende Funktionen zur Verfügung:

- Security Ticket generieren - requestSamlAssertion

### Security Ticket generieren

Das Anfordern eines Tickets wird mittels der Funktion requestSamlAssertion() vorgenommen.
Zu beachten ist:
Aus der Funktion heraus erfolgt kein Zugriff auf den Kartenleser. Wird eine Signatur gewünscht, muss beim Funktionsaufruf der entsprechende CardToken angegeben werden.
Der Request kann, wenn es sich um die Ausstellung eines Patienenkontakt-Tickets handelt, mit einem e-card Cardtoken "signiert" werden. oder unsigniert gesendet werden.
Die Signatur des STS-Requests mit einem e-card Cardtoken kann Auswirkungen auf die Qualität des Tickets haben. Die Einstufungen der Ticketqualitäten der unterstützten Tickets entnehmen Sie bitte dem im Ordner ticketinfo enthaltenen Dokument.
Es wird empfohlen den Request für ein Patientenkontakt-Ticket nach Möglichkeit immer zu signieren.
Für die Anforderung eines Tickets sind folgende Parameter im Objekt RequestSamlAssertionReq anzugeben bzw. angebbar:

- Ticketsubject

- Das Ticketsubject wird in Form einer URI übergeben und beinhaltet:

- e-card Namespace
- den Ticketname
- die Ticketart
- sowie die für das gewählte Ticket (aufgrund Ticketname und Ticketart) benötigten Parameter

- Das Ticketsubjekt ist ein Pflichtfeld und muss daher angegeben werden. Die Eingabe der einzelnen Parameter für das Ticketsubject kann/muss bei Bedarf direkt durch die Vertragspartnersoftware vorgenommen werden.
- Eine genauere Beschreibung der Inhalte des Ticketsubjekts, sowie die Bedingungen für die Angabe der weiteren benötigten Parameter aufgrund des gewählten Tickets entnehmen Sie bitte dem im Ordner ticketinfo enthaltenen Dokument.

- ResponseUrl

- Enthält die Url des Gesundheitsdiensteanbieters (Service-Provider) bei den das Ticket in weiterer Folge verwendet werden soll

- Die ResponseUrl ist ein optionales Feld und muss daher nicht zwingend angegeben werden. Im Falle der Angabe wird geprüft ob die Url zu einem dem e-card System bekannten und registrierten Gesundheitsdiensteanbieter gehört, und nur in diesem Fall das Ticket ausgestellt. Wird die ResponseUrl nicht angegeben, wird das Ticket ohne diese Prüfung ausgestellt.

Hinweis: Ein eventuell im Request-Header angegebenes SW-Zertifikat wird ignoriert!

##### Szenario 5 - Security Ticket generieren: