From 1a977b4d39765ca50f8cd82c022b906da9c1d746 Mon Sep 17 00:00:00 2001
From: Jan Zickermann <jan.zickermann@dataport.de>
Date: Mon, 10 Mar 2025 11:31:15 +0100
Subject: [PATCH] Readme: Explain configuration
---
README.md | 44 +++++++++++++++++++++++++++++++++++++++-----
1 file changed, 39 insertions(+), 5 deletions(-)
diff --git a/README.md b/README.md
index cba21e6..522dba4 100644
--- a/README.md
+++ b/README.md
@@ -2,8 +2,38 @@
Senden und Empfangen von Postfach-Nachrichten über die OSI-Postfach-Facade 2.0 (OPF).
+Das Maven-Artefakt `osiv2-postach` kann in ein Spring-Boot eingebunden werden.
+Die Spring-Bean `osiPostfachRemoteService` mit dem Interface
+`PostfachRemoteService` kann mit `ozgcloud.osiv2.enabled: true` aktiviert werden.
+
+## Konfiguration
+Um auf die Postfach-Facade zugreifen zu können muss der Client sich beim Servicekonto anmelden.
+Hierzu wird `ozgcloud.osiv2.auth` konfiguriert, wie bspw. hier für Stage-Schleswig-Holstein:
+```yaml
+client-id: 'OZG-Kopfstelle-SH'
+client-secret: 'changeme'
+scope: default, access_urn:dataport:osi:sh:stage:ozgkopfstelle
+token-uri: 'https://idp.serviceportal-stage.schleswig-holstein.de/webidp2/connect/token'
+resource: 'urn:dataport:osi:postfach:rz2:stage:sh'
+```
+Für die Postfach-Facade muss zudem die URL, der Tenant, und der SAML-Name-Identifier konfiguriert werden.
+Beim Nachschlagen des Postfachs der Antragsteller*in wird ein Postfach mit übereinstimmenden Tenant präferiert.
+Zudem werden Tenant und SAML-Name-Identifier beim Upload von Anhängen angegeben.
+
+Hierzu wird `ozgcloud.osiv2.api` konfiguriert:
+```yaml
+url: 'https://api-gateway-stage.dataport.de:443/api/osi_postfach/1.0.0'
+tenant: 'SH'
+name-identifier: 'ozgkopfstelle'
+```
+<small>(Der Wert von `name-identifier` wird momentan nicht von der Postfach-Facade geprüft.)</small>
+
## Senden einer Postfach-Nachricht
+Der Aufruf `sendMessage(PostfachNachricht)` sendet eine Nachricht an die Antragsteller*in. Jede Nachricht ist stets in Bezug zu einem Vorgang.
+1. Mit dem SAML-Name-Identifier der Antragsteller*in wird ein Postfach nachgeschlagen, welches die Nachricht empfangen soll.
+2. Vor dem Senden der Nachricht werden alle Anhänge in die Quarantäne hochgeladen und auf Viren geprüft.
+3. Nach dem erfolgreichen Hochladen der Anhänge wird die Nachricht an das Postfach gesendet.
```mermaid
%% Senden einer Nachricht
sequenceDiagram
@@ -40,7 +70,6 @@ Senden und Empfangen von Postfach-Nachrichten über die OSI-Postfach-Facade 2.0
C-->>B:
deactivate C
end
- Note left of B: (3) Warten auf Prüfung der hochgeladenen Anhänge
loop Regelmäßiges Polling bis alle Anhänge geprüft sind
loop Für jeden Anhang
B->>C: GET /Quarantine/v1/Upload/{guid}
@@ -49,7 +78,7 @@ Senden und Empfangen von Postfach-Nachrichten über die OSI-Postfach-Facade 2.0
deactivate C
end
end
- Note left of B: (4) Nachricht senden
+ Note left of B: (3) Nachricht senden
B->>C: POST /MessageExchange/v1/Send/{mailboxId}
activate C
C-->>B:
@@ -60,9 +89,13 @@ Senden und Empfangen von Postfach-Nachrichten über die OSI-Postfach-Facade 2.0
```
## Empfangen von Postfach-Nachrichten
+Der Aufruf `receiveMessages()` holt alle Nachrichten, die an das OZG-Cloud-Postfach gerichtet sind ab.
+1. Es wird eine Liste an Nachrichten-Kennungen abgerufen.
+2. Für jede Nachricht wird die Nachricht abgerufen und die Anhänge heruntergeladen.
+3. Ein Stream an Nachrichten wird zurückgegeben. Anhand der Vorgangs-Kennung lässt sich jede Nachricht stets einem Vorgang zugordnen.
```mermaid
-%% Empfangen einer Nachricht
+%% Empfangen von Nachrichten
sequenceDiagram
participant N as nachrichten-manager
participant A as file-manager
@@ -92,8 +125,9 @@ Senden und Empfangen von Postfach-Nachrichten über die OSI-Postfach-Facade 2.0
C-->>B:
deactivate C
end
+ Note left of B: (3) Bereitstellung der Postfach-Nachricht
+ B-->>N: {Postfach-Nachricht als Stream-Element}
end
- B-->>N: {Stream an Postfach-Nachrichten}
deactivate B
deactivate N
```
@@ -132,7 +166,7 @@ Der Resource-Server liest die Resource-URI aus dem `aud`-Claim (siehe [RFC 9068,
curl -v --output auth_response.json \
-H "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "grant_type=client_credentials" \
- --data-urlencode "client_id=OZG-Kopfstelle" \
+ --data-urlencode "client_id=OZG-Kopfstelle-SH" \
--data-urlencode "client_secret=${SH_STAGE_CLIENT_SECRET}" \
--data-urlencode "scope=default access_urn:dataport:osi:sh:stage:ozgkopfstelle" \
--data-urlencode "resource=urn:dataport:osi:postfach:rz2:stage:sh" \
--
GitLab