Authentifizierung

---

Einleitung

Um Clientsysteme von KVen zu authentifizieren, wird der Standard OAuth2 mit dem Client Credentials Flow eingesetzt. Nähere Information dazu sind im RFC 6749 The OAuth 2.0 Authorization Framework in Abschnitt 4.4 Client Credentials Grant zu finden.

Darüber hinaus ist eine VPN-Verbindung zwischen den vertrauenswürdigen Umgebungen der Client- und der Server-Systeme erforderlich.

Authentifizierungsverfahren: OAuth2 – Client Credentials Flow

Jede KV, die die Terminschnittstelle für KVen nutzt, hat dabei die Rolle eines Clients inne. Die kv.digital GmbH stellt einen OAuth 2.0 Authorization Server bereit, um mittels Client ID und Client Secret einen Access Token zu erstellen. Der Access Token berechtigt die KV, die Schnittstelle (API bzw. OAuth 2.0 Resource Server) zu nutzen.

Des Weiteren benötigt die KV eine Hardware-gestützte VPN-Verbindung zur Server-Infrastruktur der kv.digital.

Access Token & Gültigkeit

Mit dem Access Token werden keine einzelnen Personen identifiziert und autorisiert, um die Schnittstelle zu nutzen, sondern nur die KV.

Der Access Token ist 5 Minuten lang gültig. Nach Ablauf dieser 5 Minuten muss die KV einen neuen Access Token Request an den OAuth 2.0 Authorization Server stellen, um einen neuen Access Token zu erhalten.

Sequenzdiagramm

Der Ablauf der Authentifizierung wird in folgendem Sequenzdiagramm veranschaulicht:

Legende

◼ Server der kv.digital

◼ System der KV

→ Schritt zur Authentifizierung

→ Schritt nach der Authentifizierung

Die oben in rosa dargestellten Schritte 4 und 5 sind nicht Teil des Authentifizierungsprozesses. Sie zeigen lediglich, was der Client (hier also die KV) nach erfolgreicher Authentifizierung mit dem dadurch erhaltenen Access Token machen kann.

Beispiel-Request

Beispiel für cURL

Beim folgenden Request muss die Client ID als username und das Client Secret als password angegeben werden.

curl --request POST \
  --url https://auth-server.kvtg.de/oauth2/token \
  --data grant_type=client_credentials \
  --data scope=terminefuerkven

Beispiel für Postman etc.

Sollen Requests mithilfe von entsprechenden Anwendungen (bspw. Postman, Bruno oder Insomnia) gesendet werden, sind die im Folgenden genannten Parameter zu nutzen.

Request Body (Form URL Encoded)

Key	Value
grant_type	client_credentials
scope	terminefuerkven

Basic Auth

Key	Value
username	<YOUR_CLIENT_ID>
password	<YOUR_CLIENT_SECRET>

VPN-Verbindung

Zur Nutzung der Schnittstelle wird eine VPN-Verbindung zwischen den vertrauenswürdigen Umgebungen der Client- und der Server-Systeme aufgebaut, die zur sicheren Speicherung des Schlüsselmaterials Client-seitig in Hardware ausgelegt ist.

Alle weiteren Informationen sind im Partnerportal der kv.digital unter 116117 Terminservice Schnittstellen - Anbindung via VPN zu finden.