Produktbeschreibung

Technologischer Ansatz

Alle pIT-Services sind JAVA Applikationen, die auf einen Microservice Ansatz setzen und als Kubernetes-ready Container gestaltet sind. Eigenschaften der/des Services sind:

• Docker Container, deren Artefakte über GitHub dem Betreiber bereitgestellt werden.
• Der Betreiber baut die Container in seiner lokalen Umgebung. Spezifika des Betreibers können, wenn notwendig, in dessen lokaler Umgebung angepasst werden.
• Resourcen sind schonend gestaltet.
• Reduzierte Abhängigkeiten zu Software Libraries - es wird kein Applikation Server verwendet.
• Als HTTP Empfänger dient ein Netty Server.
• Services starten schnell (es kann ein K8s autoscaler verwendet werden).
• Sie liefern strukturierte Logmetadaten (logback) via server log oder console, um ein zentrales Monitoring zu ermöglichen.
• Es wird ein Prometheus /metric Endpunkt bereitgestellt (eigener Port/Server).
• Konfiguration für den Betreiber mittels yaml Files (Konfiguration und Secrets in getrennten yaml Files).
• Datenbankverbindungen mittels Hikari connection pool.

---
title: Technologischer Ansatz
config:
  theme: neutral 
---
%%{init: 
  {
    'themeVariables': {
      'lineColor': 'lightgray'
    }
  } 
}%%
architecture-beta
    group pod(cloud)[EOAS JAVA microservice]
    service netty(internet)[netty http receiver] in pod
    service eoas(server)[OAuth logic] in pod
    service cfg(disk)[yaml cfg] in pod
    service log(disk)[logback logging] in pod
    service jdbc(database)[Hikari JDBC Pool] in pod

cfg:R -- L:netty
netty:B -- T:eoas
eoas:L -- R:log
eoas:R -- L:jdbc

Standards

Standard	Inhalt	Beschreibung
RFC6749	Refreshing an Access Token	Wird verwendet um JWT Access-Tokens zu erneuern.
RFC7009	OAuth 2.0 Token Revocation	Wird verwendet um JWT Tokens zu invalidieren.
RFC7517	JWKS (JSON Web Key Set)	Stellt für Clients ein JWKs (JSON Web Key Set) zur Verfügung. Beinhaltet ein Set an cryptographic key Informationen um die Signatur von Tokens prüfen zu können.
RFC7519	JSON Web Token (JWT)	Definiert den Aufbau eines JWT (JSON Web Token) in einer URL-safe compact Representation.
RFC7521	Assertion Framework for OAuth 2.0 Client Authentication and Authorization Grants	Wird als Basis von RFC7522 verwendet.
RFC7522	Using SAML Assertions as Authorization Grants	Wird verwendet um mittels ELGA SAML HCP Assertion ein AC-Access-Tokens zu beantragen (Using SAML Assertions as Authorization Grants).
RFC7662	OAuth 2.0 Token Introspection	Stellt eine Schnittstelle zur Verfügung um Tokens die vom EOAS ausgestellt wurden auch gegen das EOAS validieren zu können.
RFC8693	OAuth 2.0 Token Exchange	Wird von der AC-FHIR-Facade verwendet um ein AC-Access-Token gegen ein Community-Token auszutauschen.

Arbeitsweise

Der EOAS wird als zentrale BeS Komponente bereitgestellt und ist eine Ergänzung des existierenden ETS (ELGA Token Service).
Externe Verbindungen werden über eine AGW an einen zentralen Apache geleitet. Innerhalb des K8s (Kubernetes) Clusters wird der EOAS Pod über den integrierten Netty HTTP Server angesprochen.
Der EOAS kommuniziert mit dem KBS und protokolliert im Z-L-ARR. Loginformation wird mittels strukturierter JSON Logs an den Splunk weitergeleitet.
Der Zustand (State) bezüglich Tokens und Attributen für OAuth Flows wird in der zentralen Postgres Datenbank verwaltet.

---
title: Arbeitsweise
config:
  theme: neutral 
---
%%{init: 
  {
    'themeVariables': {
      'lineColor': 'lightgray'
    }
  } 
}%%
block-beta
columns 1
  apache(("Apache"))
  arrow<["&nbsp;&nbsp;"]>(down)

  block:eoas_netty
    netty["<b>EOAS</b> Netty HTTP receiver"]
  end



  block:EOAS
    logic["<b>EOAS</b> OAuth logic"]
  end

  netty --> logic

  space
  space
  block:bes
    kbs["KBS"]
    zlarr["Z-L-ARR"]
    splunk["SplunkLogs"]
    db["Postgres"]    
  end

  logic --> kbs
  logic --> zlarr
  logic --> splunk
  logic --> db["Postgres"]    


  style netty fill:#AED6F1,stroke:#blue,stroke-width:2px
  style logic fill:#AED6F1,stroke:#blue,stroke-width:2px

Interaktionen

Benutzer beantragt ein AC-Access-Token

Um mit der AC-Anwendung kommunizieren zu können, muss der Benutzer ein AC-Access-Token beantragen.
Ein Benutzer kommuniziert mit dem EOAS über das existierende AGW, das sich um Routing und TLS Terminierung innerhalb des ELGA Netzwerks kümmert.
Eine zuvor beantragte ELGA HCP Assertion wird vom Benutzer gegen ein AC-Access-Token eingetauscht. Das AC-Access-Token ist an eine eHealth Applikation (eEKP), an einen Benutzer und einen bestimmten Patienten (bPK-GH) gebunden und kann nachfolgend auch nur in dieser Kombination verwendet werden. Der Patienten-Kontext (bPK-GH) wird mittels einem dem Z-PI bekannten Identifier hergestellt.
Der Benutzer kann mit dem AC-Access-Token über das AGW mit der AC-FHIR-Facade kommunizieren.
Da ein Access Token zeitlich sehr eingeschränkt nutzbar ist, wird dem Benutzer zusätzlich ein AC-Refresh-Token ausgehändigt um weitere Access Tokens beantragen zu können.
Beim AC für den eEKP handelt es sich um eine No-Opt Anwendung (weder Opt-in noch Opt-out). Es werden deshalb keine patientenbezogenen Policies geprüft.
Für jede Interaktion wird ein Audit im Z-L-ARR protokolliert.

Vom zentralen Betreiber muss die client_id (AGW Kennung) der jeweilgen FHIR-Facade am Apache des AGW als HTTP Header hinzugefügt werden. Die client_id der AGW wird in folgendem HTTP Header transportiert e-agw-client. Der Wert aus e-agw-client darf nicht der eigentlichen client_id der Anfrage entsprechen. Der HTTP e-agw-client Header darf nicht vom Client gesetzt werden bzw. darf nicht vom Apache übernommen werden. Der Header MUSS vom Apache neu gesetzt werden und muss in jedem Fall der AGW die aufgerufen wurde entsprechen. Siehe auch: AC-Access-Token

---
title: Benutzer AC Token handling
config:
  theme: neutral 
---
sequenceDiagram
autonumber

actor benutzer as Benutzer

box rgb(252, 243, 207) existing BeS
participant agw as AGW - Apache Central
end

box rgb(174, 214, 241) EOAS
participant eoas as EOAS
end

box rgb(252, 243, 207) existing BeS central
participant kbs as KBS
participant zlarr as Z-L-ARR
participant db as DB
end

Note over benutzer: AC-Tokens anfordern
benutzer->>+eoas: AC-Access-Token (HCP)
eoas-->+eoas: check client <br> check role allowed
eoas->>-kbs: get active contact
kbs-->+kbs: validate HCP
kbs->>+db: query contact
kbs->>+zlarr: write z-l-arr audit
kbs-->>-eoas: return contact
eoas-->+eoas: check contact active
eoas->>+db: state management
eoas->>+zlarr: write z-l-arr audit
eoas-->>-benutzer: return AC-Access + Refresh -Token

Note over benutzer: JWT überprüfen
benutzer->>+eoas: introspect-Token(JWT)
eoas-->+eoas: check client <br> validate JWT
eoas->>+db: state management
eoas->>+zlarr: write z-l-arr audit
eoas-->>-benutzer: return introspect-Token Response

Note over benutzer: JWT erneuern
benutzer->>+eoas: refresh-Token(refreshJWT)
eoas-->+eoas: check client <br> validate refreshJWT
eoas->>+db: state management
eoas->>+zlarr: write z-l-arr audit
eoas-->>-benutzer: return AC-Access-Token Response

Note over benutzer: JWT invalidieren
benutzer->>+eoas: revoke-Token(JWT)
eoas-->+eoas: check client <br> validate JWT
eoas->>+db: state management
eoas->>+zlarr: write z-l-arr audit
eoas-->>-benutzer: return revoke-Token Response

Note over benutzer: JWKS abrufen
benutzer->>+eoas: jwks
eoas->>+zlarr: write z-l-arr audit
eoas-->>-benutzer: return JWKS Response

AC-Tokens anfordern: Folgend der Ablauf um ein AC-Access-Token und ein AC-Refresh-Token anzufordern. Siehe auch: RFC7522 - Using SAML Assertions as Authorization Grants

• 1: Der Benutzer schickt eine /token Anfrage, um seine HCP gegen ein AC-Access + Refresh -Token zu tauschen.
• 2: Der EOAS prüft, ob der client bekannt und die Rolle der HCP für den AC erlaubt ist.
• 3: Es wird der aktive Kontakt zwischen Benutzer und Patient vom KBS abgefragt. Für die Patientenidentifikation kann ein dem Z-PI bekannter Identifier verwendet werden.
• 4: Das KBS validiert die HCP.
• 5: Das KBS fragt Kontakte von der Datenbank ab.
• 6: Das KBS schreibt einen Z-L-ARR Audit.
• 7: Wenn verfügbar, wird der aktive Kontakt zurückgegeben.
• 8: Der EOAS prüft, ob ein Kontakt existiert und aktiv ist (nicht älter als 90 Tage).
• 9: Der EOAS kommuniziert wegen Token-State-Management mit der Datenbank.
• 10: Der EOAS schreibt einen Z-L-ARR Audit.
• 11: Vom EOAS wird die Token Response mit Access und Refresh Token zurückgegeben.

JWT überprüfen: Das AC-Access + Refresh -Token kann gegen den EOAS geprüft werden. RFC7662 - OAuth 2.0 Token Introspection

• 12: Der Benutzer schickt eine /introspect Anfrage, um ein JWT zu überprüfen.
• 13+14: Das JWT wird validiert.
• 15: Der EOAS schreibt einen Z-L-ARR Audit.
• 16: Es wird eine introspect Antwort zurückgegeben.

JWT erneuern: Das AC-Access-Token kann mittels AC-Refresh-Token erneuert werden. RFC6749 Refreshing an Access Token

• 17: Der Benutzer schickt eine /token refresh Anfrage, um das Access-Token mit einem Refresh-Token zu erneuern.
• 18+19: Das Refresh-JWT wird validiert.
• 19: Der State für das neue Access-Token wird gespeichert.
• 20: Der EOAS schreibt einen Z-L-ARR Audit.
• 21: Es wird eine Token Antwort mit einem Access-Token zurückgegeben.

JWT invalidieren: Das AC-Access + Refresh -Token kann invalidiert werden. Beim Invalidieren werden immer alle abhängigen Tokens, die auf Basis desselben "Codes"/Requests ausgegeben wurden, invalidiert. RFC7009 - OAuth 2.0 Token Revocation

• 22: Der Benutzer schickt eine /revoke Anfrage, um ein JWT zu invalidieren.
• 23+24: Das JWT wird validiert.
• 24: Der State für das invalidierte JWT wird aktualisiert.
• 25: Der EOAS schreibt einen Z-L-ARR Audit.
• 26: Es wird eine revoke Antwort zurückgegeben.

JWKS abrufen: Um ein JWT (RFC7519) lokal prüfen zu können, wird ein JWKS (JSON Web Key Set - RFC7517) Endpunkt bereitgestellt. Dieser Endpunkt liefert kryptografische Information, die andernfalls manuell von jedem Betreiber konfiguriert werden müsste (Truststore).

• 27: Der Benutzer schickt eine /jwks Anfrage, um ein JWKS (JSON Web Key Set) abzurufen. Das JWKS wird verwendet, um lokal ein Token "ohne" TrustStore validieren zu können.
• 28: Der EOAS schreibt einen Z-L-ARR Audit.
• 29: Es wird eine JWKS Antwort zurückgegeben.

AC-FHIR-Facade beantragt ein AC-Community-Token

Die AC-FHIR-Facade empfängt vom Benutzer ein AC-Access-Token, dieses Token wird nicht an die Fachanwendung weitergeleitet, sondern gegen ein AC-Community-Token getauscht.
Der AC-Community-Token wird von der AC-FHIR-Facade vom EOAS beantragt und nachfolgend an die Fachanwendung weitergeleitet. Siehe auch: OAuth 2.0 Token Exchange.

---
title: FHIR facade beantragt ein AC-Community-Token
config:
  theme: neutral 
---
sequenceDiagram
autonumber

actor facade as FHIR-Facade

box rgb(252, 243, 207) existing BeS
participant apache as Apache Central
end

box rgb(174, 214, 241) EOAS
participant eoas as EOAS
end

box rgb(252, 243, 207) existing BeS central
participant zlarr as Z-L-ARR
participant db as DB
end

facade->>+eoas: exchange-Token<br>(AC-Access-Token)
eoas-->+eoas: check client <br> validate JWT
eoas->>+db: state management
eoas->>+zlarr: write z-l-arr audit
eoas-->>-facade: return AC-Community-Token

• 1: Die FHIR Facade beantragt mittels token exchange ein AC-Community-Token für das erhaltene AC-Access-Token. Die Facade cached das Community-Token im Memory für nachfolgende Anfragen.
• 2+3: Der client (facade) und das JWT werden geprüft.
• 4: Der EOAS schreibt einen Z-L-ARR Audit.
• 5: Es wird eine Token Antwort mit einem AC-Community-Token zurückgegeben.

Tokens

Nachfolgend werden die verwendeten Tokens erklärt. Die Gültigkeit aller Tokens kann vom Betreiber eingestellt werden.

AC-Access-Token

Das AC-Access-Token wird dem Benutzer im Austausch einer HCP Assertion als Zugriffstoken für die AC-FHIR-Facade vom EOAS mittels RFC7522 - Using SAML Assertions as Authorization Grants bereitgestellt.

In Gegensatz zu den bisher in ELGA verwendeten Verfahren wird bereits an dieser Stelle eine Bindung zum Patienten hergestellt. Der Patientenkontext wird im Token mittels bPK-GH mitgeführt (JWT/extensions/person_id).
Um das Token zu beantragen, muss neben einer validen HCP Assertion auch ein aktiver Kontakt zwischen dem Benutzer und dem Patienten existieren. Der EOAS prüft, ob die Rolle der HCP Assertion für die verwendete eHealth Applikation berechtigt ist. Ein Mapping von eHealth Applikationen auf Rollen ist mittels yaml Konfiguration vom Betreiber einstellbar.

Der Token-Kontext setzt sich zusammen aus:

• der eHealth-Anwendung
• einem Benutzer
• und einem bestimmten Patienten

Die Prüfung der ELGA HCP Assertion und des Patienten wird mittels Kontaktabfrage gegen das existierende KBS realisiert.
Die Prüfung, ob der erhaltene Kontakt aktiv ist, wird vom EOAS durchgeführt - der Kontakt muss dafür aktiv und nicht älter als 90 Tage sein.

Der Inhalt des AC-Access-Token orientiert sich am IHE IUA Profil. .

Die Rolle der HCP wird auf einen "Rollen-Scope" gewandelt, der auf eine Capability Statement Ressource zeigt. Der Scope besitzt einen cs: Präfix und wird nachfolgend von der FHIR-Facade verwendet, um abhängig vom Scope CapabilityStatement Ressourcen zu laden und Berechtigungen durchzusetzen.

In die aud (Audience) Claim wird die client_id des OAuth-Clients (Benutzer) und die der jeweiligen FHIR-Facade (AGW), über die die Token-Anfrage gestartet wurde, übernommen. Die Audience wird von allen FHIR-Facades geprüft.

Es sind nur Abfragen an eine AGW/FHIR-Facade möglich, die ident mit der AGW ist über die das AC-Access-Token beantragt wurde.
Hierzu muss vom zentralen Betreiber die client_id der jeweilgen FHIR-Facade am Apache der AGW als HTTP e-agw-client Header hinzugefügt werden.

AC-Refresh-Token

Das AC-Refresh-Token wird dem Benutzer zusammen mit dem AC-Access-Token beim Eintauschen der HCP Assertion bereitgestellt. Das Refresh Token ist zeitlich länger gültig und kann vom Benutzer verwendet werden, um mittels OAUTH Refresh Interaktion ein weiteres Access Token zu beantragen.

AC-Community-Token

Das AC-Community-Token wird auf Basis eines AC-Access-Token von der AC-FHIR-Facade vom EOAS mittels OAuth 2.0 Token Exchange beantragt. Das Community Token wird an die Fachanwendung weitergeleitet.

Das AC-Community-Token wird von der FHIR-Facade für den Zeitraum der Gültigkeit des Tokens im Cache gehalten werden.

Abgesehen von dynamisch erzeugten Claims, wie act, aud, exp, iat und jti, sind die Inhalte des Community Token mit dem des Access Token ident.
Die Fachanwendung muss neben der Signatur die aud Claim des Tokens validieren und darf nur einem Community Token nicht aber einem Access Token vertrauen.
In der aud Claim ist der Endpunkt der Fachanwendung enthalten.

Die act Claim beinhaltet eine Identifikation für die jeweiligen AC-FHIR-Facade, für die das Token delegiert wurde.

OAuth-Flow und Token-State Verwaltung

Um den OAuth-Flow umzusetzen und gewisse Token Funktionalität erfüllen zu können wird eine State-Verwaltung benötigt. Der State wird in der zentralen Postgres Datenbank verwaltet und existiert nur temporär. Der Betreiber löscht zeitgesteuert (maximale Tokengültigkeitsdauer) ältere Eintrage regelmäßig.

Beispiele für States sind:

• Zwischenspeicher für OAuth Attribute wie z.B.: code und state Parameter die bei Folgetransaktionen überprüft werden müssen.
• Speichern von Token-Informationen um Interaktionen wie Introspect oder Renew bedienen zu können.