Zum Inhalt

Schnittstellen

Auf der folgenden Seite werden die zu verwendenden Schnittstellen des EOAS beschrieben.

Schnittstellen für den Benutzer

Die gesamte Kommunikation von einem Benutzer mit dem EOAS wird über das AGW geführt. Das AGW kümmert sich um TLS Terminierung und das Routing der Anfrage. Das AGW sendet die Anfrage an das zentrale System weiter. Dort wird die Transaktion wiederum von einem Apache an das EOAS weitergeleitet.

---
title: Kommunikation über AGW
config:
  theme: neutral 
---
%%{init: 
  {
    'themeVariables': {
      'lineColor': 'lightgray'
    }
  } 
}%%
block-beta
block:ID
columns 7
  benutzer(((" Benutzer ")))
    space
    agw["<b>AGW</b> Apache"]
    space
    bes["<b>zentraler</b> Apache"]
    space
    eoas["<b>EOAS</b> zentral"]

 end

  benutzer --> agw
  agw --> bes
  bes --> eoas

  style agw fill:#F9F9CA,stroke-width:2px
  style bes fill:#F9F9CA,stroke-width:2px
  style eoas fill:#AED6F1,stroke-width:2px

EOAS AGW Basis-Endpunkt
HTTPS://AGW/EOAS

OAuth Client Authentication

Der Benutzer bzw. sein OAuth Client muss vom zentralen Betreiber als OAuth Client registriert werden. Dabei wird vom zentralen Betreiber eine client_id und ein client_secret vergeben.

Der OAuth CLient ist im Regelfall der ELGA Bereich und nicht der Endbenutzer.

Vom Client muss bei jeder Interaktion, die eine Client Authentication fordert, die client_id und das client_secret im Authorization Header der Anfrage mitgesendet werden.

  • Der Authorization Header der Anfrage muss die client_id+ : + client_secret base64 encoded enthalten.
  • Siehe: Client Authentication using Client Password.
  • Es muss HTTP Basic authentication scheme RFC2617 mit base64(client_id:client_secret) verwendet werden.

Andere Client Authentication Methoden sind nicht vorgesehen.

Beantragen des AC-Access-Tokens

Um mit der AC-FHIR-Facade Business-Transaktionen durchführen zu können, muss der Benutzer eine zuvor beantragte ELGA HCP Assertion gegen ein AC-Access-Token eintauschen.

---
title: Beantragen des AC-Access-Tokens
config:
  theme: neutral 
---

sequenceDiagram
autonumber

actor benutzer as Benutzer

box rgb(252, 243, 207) AGW
participant agw as AGW Apache
end

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

benutzer-->+benutzer: get HCP & client_id <br>& client_secret
benutzer->>+eoas: EOAS/token
eoas-->>-benutzer: return AC-Access & Refresh -Token

Verwendeter Standard

RFC7522 - Using SAML Assertions as Authorization Grants

zu verwendender AGW Endpunkt

HTTPS://AGW/EOAS/token

Vorbedingungen

  • client_id und client_secret wurden vom zentralen Betreiber beantragt (OAuth Client Authentication).
  • der Benutzer hat Zugang zu einer AGW (Netzwerk, TLS, etc.).
  • der Benutzer ist in Besitz einer validen ELGA HCP Assertion.
  • der Benutzer (GDA) hat einen aktiven Kontakt mit dem Patienten der nicht älter als 90 Tage ist.

Ablaufbeschreibung

  • 1: Vorbedingungen.
  • 2: Es wird vom Benutzer eine HTTP POST Anfrage an den EOAS/token Endpunkt des AGW gesendet. - RFC7522 - Using SAML Assertions as Authorization Grants
  • Der Authorization Header der Anfrage muss die client_id+ : + client_secret base64 encoded enthalten. Siehe: OAuth Client Authentication
  • Der Content-Type Header der Anfrage muss application/ x-www-form-urlencodedsein.
  • Der grant_type Parameter der Anfrage muss den Wert urn:ietf:params:oauth:grant-type:saml2-bearer urlEncoded enthalten.
  • Der assertion Parameter der Anfrage muss die ELGA HCP Assertion PHNhbWxwOl...[omitted for brevity]...ZT4 base64urlEncoded enthalten.
  • Der scope Parameter der Anfrage muss folgende Werte beinhalten: launch/patient context/<AC-App-Id>
    • Die Werte sind mit Leerzeichen getrennt.
    • launch/patient gibt an, dass zusätzlich auch ein patient Parameter enthalten sein muss.
    • context/<AC-App-Id> gibt an für welche ELGA Applikation ein Token angefordert wird. <AC-App-Id> ist mit dem Integer Wert der jeweiligen ELGA Applikation zu ersetzen.
  • Der patient Parameter der Anfrage muss eine dem Z-PI bekannte Patientenidentifikation im FHIR Token Format enthalten. Dabei muss das Format [system]|[code] verwendet werden - z.B.: lpid-domain|lpid-wert.
  • 3: Der Client erhält eine Token-Antwort in JSON Format - RFC6749 - Access Token Response.

Anfrage

HTTP POST EOAS/token

Http Header:
Accept: application/json
Content-Type: application/x-www-form-urlencoded
Authorization: b64(client_id:client_secret) Siehe: OAuth Client Authentication

Http Body:
assertion=b64Url(HCP)
&grant_type=urn:ietf:params:oauth:grant-type:saml2-bearer
&scope=launch/patient context/<AC-App-Id>
&patient=lpid-domain|lpid-wert

Antwort
Der Body der Token-Antwort in JSON Format - RFC6749 - Access Token Response. Das access_token und refresh_token ist JWT formatiert: JWT (JSON Web Token - RFC7519)

HTTP/1.1 200 OK

Http Header:
Content-Type: application/json

Http Body: 

{
    "token_type": "Bearer",
    "access_token": "eyJraWQiOm51...LjaGg",
    "expires_in": 600,
    "refresh_token": "eyJraWQiOmed...xxSS",
}

Überprüfen des AC-Access und Refresh-Tokens

Optional - Das AC-Access + Refresh -Token kann gegen das EOAS geprüft werden.

---
title: Introspect eines JWT
config:
  theme: neutral 
---

sequenceDiagram
autonumber

actor benutzer as Benutzer

box rgb(252, 243, 207) AGW
participant agw as AGW Apache
end

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

benutzer-->+benutzer: get AC-Access-Tokens<br> & client_id <br>& client_secret
benutzer->>+eoas: EOAS/introspect
eoas-->>-benutzer: return introspect-Token Antwort

Verwendeter Standard

RFC7662 - OAuth 2.0 Token Introspection

zu verwendender AGW Endpunkt

HTTPS://AGW/EOAS/introspect

Ablaufbeschreibung

  • 1: Der Benutzer/OAuth-Client muss in Besitz eines AC-Access oder Refresh-Tokens sein.
  • 1: Der Benutzer/OAuth-Client muss sich vom zentralen Betreiber seine client_id und client_secret für die OAuth Kommunikation besorgen.
  • 2: Es wird vom Benutzer eine HTTP POST Anfrage an den EOAS/introspect Endpunkt des AGW gesendet.
  • Der Authorization Header der Anfrage muss die client_id+ : + client_secret base64 encoded enthalten. Siehe: OAuth Client Authentication
  • Der Content-Type Header der Anfrage muss application/ x-www-form-urlencodedsein.
  • Der token Parameter der Anfrage muss das zu prüfende JWT eyJraWQiOm51...LjaGg enthalten.
  • 3: Der Client erhält eine Introspect-Antwort in JSON Format - RFC7662 - Introspection Response.

Anfrage:
Die Anfrage wird in folgendem Format gesendet - RFC7662 - Introspection Request.

HTTP POST EOAS/introspect

Http Header:
Accept: application/json
Content-Type: application/x-www-form-urlencoded
Authorization: b64(client_id:client_secret) Siehe: OAuth Client Authentication

Http Body:
token=eyJraWQiOm51...LjaGg

Antwort:
Der Body der Introspect-Antwort ist in JSON Format - RFC7662 - Introspection Response. Es werden nur die in der Antwort beschriebenen Attribute zurückgegeben.

HTTP/1.1 200 OK

Http Header:
Content-Type: application/json

Http Body: 

{
  "active": true,
  "iat": 1595078454,
  "exp": 1595079054,
  "iss": "EOAS..",
  "scope": "die scope Werte des Tokens.."
}

Erneuern des AC-Access-Tokens

Optional - Das AC-Access-Token ist zeitlich nur begrenzt gültig, kann jedoch mittels AC-Refresh-Token erneuert werden. Das AC-Refresh-Token erhält der Client mit der Beantragen des AC-Access-Tokens Antwort.

---
title:  AC-Access-Token erneuern
config:
  theme: neutral 
---

sequenceDiagram
autonumber

actor benutzer as Benutzer

box rgb(252, 243, 207) AGW
participant agw as AGW Apache
end

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

benutzer-->+benutzer: get AC-Refresh-Token<br> & client_id <br>& client_secret
benutzer->>+eoas: EOAS/token
eoas-->>-benutzer: return Token-Antwort

Verwendeter Standard
RFC6749 Refreshing an Access Token

zu verwendender AGW Endpunkt
HTTPS://AGW/EOAS/token

Ablaufbeschreibung

  • 1: Der Benutzer/OAuth-Client muss in Besitz eines AC-Refresh-Tokens sein.
  • 1: Der Benutzer/OAuth-Client muss sich vom zentralen Betreiber seine client_id und client_secret für die OAuth Kommunikation besorgen.
  • 2: Es wird vom Benutzer eine HTTP POST Anfrage an den EOAS/token Endpunkt des AGW gesendet.
  • Der Authorization Header der Anfrage muss die client_id+ : + client_secret base64 encoded enthalten. Siehe: OAuth Client Authentication
  • Der Content-Type Header der Anfrage muss application/ x-www-form-urlencodedsein.
  • Der grant_type Parameter muss den Wert refresh_token enthalten.
  • Der refresh_token Parameter der Anfrage muss das AC-Refresh-Token eyJraWQiOmed...xxSS enthalten.
  • 3: Der Client erhält eine Token-Antwort in JSON Format - RFC6749 - Access Token Response. Es ist nur das access_token enthalten.

Anfrage:
Die Anfrage wird in folgendem Format gesendet - RFC6749 Refreshing an Access Token.

HTTP POST EOAS/token

Http Header:
Accept: application/json
Content-Type: application/x-www-form-urlencoded
Authorization: b64(client_id:client_secret) Siehe: OAuth Client Authentication

Http Body:
refresh_token=eyJraWQiOmed...xxSS
&grant_type=refresh_token

Antwort:
Der Body der Token-Antwort ist in JSON Format - RFC6749 - Access Token Response.
Das access_token ist JWT formatiert: JWT (JSON Web Token - RFC7519)

HTTP/1.1 200 OK

Http Header:
Content-Type: application/json

Http Body: 

{
    "token_type": "Bearer",
    "access_token": "eyJraWQiOm51...LjaGg",
    "expires_in": 600
}

Invalidieren des AC-Access oder Refresh-Tokens

Optional - Das AC-Access-Token oder AC-Refresh-Token kann invalidiert werden.
Die Tokens erhält der Client mit der Beantragen des AC-Access-Tokens Antwort.

Beim Invalidieren des Tokens werden immer alle abhängigen Tokens (Access und Refresh) als ungültig gekennzeichnet. Es ist deshalb ausreichend ein Access- oder das Refresh-Token zu invalidieren.

---
title:  invalidieren eines JWT
config:
  theme: neutral 
---

sequenceDiagram
autonumber

actor benutzer as Benutzer

box rgb(252, 243, 207) AGW
participant agw as AGW Apache
end

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

benutzer-->+benutzer: get AC-Access/Refresh-Token<br> & client_id <br>& client_secret
benutzer->>+eoas: EOAS/revoke
eoas-->>-benutzer: return Revoke-Token-Antwort

Verwendeter Standard
RFC7009 - OAuth 2.0 Token Revocation

zu verwendender AGW Endpunkt
HTTPS://AGW/EOAS/revoke

Ablaufbeschreibung

  • 1: Der Benutzer/OAuth-Client muss in Besitz eines AC-Refresh/Access-Tokens sein.
  • 1: Der Benutzer/OAuth-Client muss sich vom zentralen Betreiber seine client_id und client_secret für die OAuth Kommunikation besorgen.
  • 2: Es wird vom Benutzer eine HTTP POST Anfrage an den EOAS/revoke Endpunkt des AGW gesendet.
  • Der Authorization Header der Anfrage muss die client_id+ : + client_secret base64 encoded enthalten. Siehe: OAuth Client Authentication
  • Der Content-Type Header der Anfrage muss application/ x-www-form-urlencodedsein.
  • Der token Parameter der Anfrage muss das jeweilige JWT eyJraWQiOmed...xxSS enthalten.
  • 3: Der Client erhält eine Revoke-Antwort ohne Body - RFC7009 - OAuth 2.0 Token Revocation Response.

Anfrage:
Die Anfrage wird in folgendem Format gesendet - RFC7009 - OAuth 2.0 Token Request.

HTTP POST EOAS/revoke

Http Header:
Content-Type: application/x-www-form-urlencoded
Authorization: b64(client_id:client_secret) Siehe: OAuth Client Authentication

Http Body:
token=eyJraWQiOmed...xxSS

Antwort:
Die Antwort enthält den HTTP Status 200 OK und keinen Body - RFC7009 - OAuth 2.0 Token Revocation Response.

HTTP/1.1 200 OK

JWKS Abrufen

Optional - 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 für die JWT Signaturprüfung).

Für den JWKS Abruf ist KEINE OAuth Client Authentication notwendig!

---
title:  JWKS abrufen
config:
  theme: neutral 
---

sequenceDiagram
autonumber

actor benutzer as Benutzer

box rgb(252, 243, 207) AGW
participant agw as AGW Apache
end

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

benutzer->>+eoas: EOAS/jwks
eoas-->>-benutzer: return JWKS-Antwort

Verwendeter Standard
RFC7517 - JWKS (JSON Web Key Set)

zu verwendender AGW Endpunkt
HTTPS://AGW/EOAS/jwks

Ablaufbeschreibung

  • 1: Es wird vom Benutzer eine HTTP GET Anfrage an den EOAS/jwks Endpunkt des AGW gesendet.
  • Der Accept Header der Anfrage muss application/json beinhalten.
  • 2: Der Client erhält eine JWKS-Antwort in JSON Format.

Anfrage:
Die Anfrage ist ein HTTPS GET ohne weitere Parameter und ohne Body.

HTTP GET EOAS/jwks

Http Header:
Accept: application/json

Antwort:
Der Body der Token-Antwort in JSON Format - RFC7517 - JWKS (JSON Web Key Set) - JWK Set Format.

Der kid Wert jedes JWK entspricht dem kid Wert des jeweiligen JWT Headers RFC7515 - JSON Web Signature (JWS) - kid. Mit dem übereinstimmenden JWK kann die Signatur des jeweiligen JWT geprüft werden.

HTTP/1.1 200 OK

Http Header:
Content-Type: application/json

Http Body: 

{
    "keys": [
        {
            "kty": "RSA",
            "kid": "accessTokenIssuer",
            "use": "sig",
            "n": "-fPy5a6iELJ3ejP9sxHh_v_bzHp...",
            "e": "AQAB"
        },
        {
            "kty": "RSA",
            "kid": "refreshTokenIssuer",
            "use": "sig",
            "n": "-fPy5a6iELJ3ejP9sxHh_...",
            "e": "AQAB"
        }
    ]
}

Interne Schnittstellen der FHIR-Facade mit dem EOAS

Hierbei handelt es sich um keine externe Schnittstelle im herkömmlichen Sinn. Diese Schnittstelle wird nur von BeS intern - von der FHIR-Facade zum EOAS verwendet - nicht aber von extern z.b.: durch einen Benutzer angesprochen.
Diese Schnittstelle darf nur von einer FHIR-Facade, nicht aber von einem Benutzer aufgerufen werden können!

Austausch des Access-Token auf ein Community-Token

Das Community-Token wird von der AC-FHIR-Facade vom EOAS beantragt und nachfolgend an die Fachanwendung weitergeleitet. Hierfür wird OAuth 2.0 Token Exchange verwendet.

Anfrage:

HTTP POST EOAS/token

Http Header:
Content-Type: application/x-www-form-urlencoded
Authorization: b64(client_id:client_secret)` Siehe: OAuth Client Authentication

Http Body:
subject_token=eyJraWQiOm51bGwsImFsZyI6IlJTMjU2In0.fQte..
&subject_token_type=urn:ietf:params:oauth:token-type:access_token &grant_type=urn:ietf:params:oauth:grant-type:token-exchange`

Antwort:
Der Body der Token-Antwort in JSON Format - RFC6749 - Access Token Response.
Das access_token ist JWT formatiert: JWT (JSON Web Token - RFC7519)

HTTP/1.1 200 OK

Http Header:
Content-Type: application/json

Http Body: 

{
    "token_type": "Bearer",
    "access_token": "eyJraWQiOm51...xxxyy",
    "expires_in": 600
}