Skip to content
Snippets Groups Projects
Commit 6dc1719f authored by David Schwarzmann's avatar David Schwarzmann
Browse files

docs(event-log): Document how to accept/reject/... a submission

parent 84583f2a
No related branches found
No related tags found
1 merge request!3docs(event-log): Start documenting the event log and interaction with signed JWTs
Hide whitespace changes
Inline Side-by-side
docs/details/crypto.md
+ 2
− 1
View file @ 6dc1719f
......@@ -84,7 +84,8 @@ Die folgenden Attribute müssen im JOSE-Header bei der Übertragung verschlüsse
| `cty` | *MIME-Type der Inhaltsdaten* | MIME-Type der Inhaltsdaten (Fachdaten, Medatadaten) nach [RFC 7516, Abschnitt 4.1.12](https://tools.ietf.org/html/rfc7516#section-4.1.12) |
## Vorgaben zur Signaturerstellung und -prüfung
### Vorgaben für JSON Web Keys zur Signaturprüfung
### Vorgaben für JSON Web Keys zur Signaturprüfung {#signature-key}
Eine Signaturprüfung erfolgt in FIT-Connect auf Basis des Standards JSON Web Signature gemäß [RFC 7515](https://tools.ietf.org/html/rfc7515).
......
docs/getting-started/receiving/process-and-acknowledge.mdx
+ 92
− 22
View file @ 6dc1719f
......@@ -3,31 +3,55 @@ sidebar_position: 8
title: 🚧 Empfangsbestätigung
---
Der letzte Schritt zum Empfang einer Einreichung ist die Bestätigung des Empfangs und damit auch der Gültigkeit der Einreichung.
Mit Gültigkeit ist hier gemeint, dass alle Informationen erfolgreich heruntergeladen, entschlüsselt und im Falle der Metadaten validiert werden konnten.
import Tabs from '@theme/Tabs'
import TabItem from '@theme/TabItem'
Der letzte Schritt zum Empfang einer Einreichung ist die Bestätigung des Empfangs und damit auch der Gültigkeit der
Einreichung. Mit Gültigkeit ist hier gemeint, dass alle Informationen erfolgreich heruntergeladen, entschlüsselt und im
Falle der Metadaten validiert werden konnten.
Wie auf der [Event Log Übersichtsseite](../event-log.md#events) zu sehen, gibt es für ein empfangendes System ein festes
Set an Events, die dem Zustelldienst gesendet werden können.
| Event | Autor | Bedeutung |
|-----------------------------------------------------------------|---------------------|-------------------------------|
| `https://schema.fitko.de/fit-connect/events/forward-submission` | | Ein nachgelagertes System hat die Einreichung zur Weiterleitung übernommen. |
| `https://schema.fitko.de/fit-connect/events/reject-submission` | Empfangendes System | Die Einreichung wurde durch den Empfänger zurückgewiesen. |
| `https://schema.fitko.de/fit-connect/events/accept-submission` | Empfangendes System | Die Einreichung wurde durch den Empfänger akzeptiert. |
Um diese Events bzw. ein entsprechendes Event korrekt an den Zustelldienst zu versenden, muss es in Form eines SETs an
diesen gesendet werden.
- Es sollte grundsätzlich beschrieben werden, welche Optionen für den SET aus Sicht des Empfänger bestehen und welche Folgen das hat (Im Sinne des Statusmodells. Wird können gerne das zusammen durchgehen)
- Die Generierung des SETs und die Übermittlung an die API
- Der Abruf des Logs. Für die Validierung wird auf diesen Artikel hier verwiesen
## :construction: Erstellung eines Security-Event-Token (SET)
## Erstellung und Versand eines Security-Event-Token (SET)
Um ein SET zu erstellen ist es notwendig ein JWK zu haben, dass den [Vorgaben eine Signaturschlüssels](../../details/crypto.md#signature-key)
entspricht. Weiterhin ist es notwendig, dass die Id der Einreichung und des zugehörigen Vorgangs bekannt ist.
```java
private static final InputStream jwksPath = GenerateSignedToken.class.getClassLoader().getResourceAsStream("jwks.json");;
private static final UUID signatureKeyId = UUID.fromString("6508dbcd-ab3b-4edb-a42b-37bc69f38fed");
<Tabs
defaultValue="java"
values={[
{ label: 'Java', value: 'java', },
{ label: 'C#', value: 'csharp', },
]
}>
<TabItem value="java">
private static final String subject = "submission:f65feab2-4883-4dff-85fb-169448545d9f";
private static final String event = "https://schema.fitko.de/fit-connect/events/accept-submission";
private static final String transactionId = "case:f73d30c6-8894-4444-8687-00ae756fea90";
// …
try {
JWKSet localKeys = JWKSet.load(jwksPath);
JWK key = localKeys.getKeyByKeyId(signatureKeyId.toString());
```java title=Annahmen
JWK key;
String subject = "submission:f65feab2-4883-4dff-85fb-169448545d9f";
String event ="https://schema.fitko.de/fit-connect/events/accept-submission";
String transactionId = "case:f73d30c6-8894-4444-8687-00ae756fea90";
```
if (key == null) {
throw new RuntimeException("Cannot find key with specified Key Id");
}
Hiermit kann dann den markierten Zeilen die Payload und der Header des SET mit den oben beschriebenen Informationen
definiert werden. Im dritten markierten Block wird das SET mit dem Schlüssel signiert und danach kann der serialisierte
Wert an den [Zustelldienst](../../apis/delivery-service.mdx#post-/submissions/-submissionId-/events) gesendet werden.
```java {3-10,12-16,22-24}
try {
JWSSigner signer = new RSASSASigner(key.toRSAKey());
JWTClaimsSet claimsSet = new JWTClaimsSet.Builder()
.issuer("https://my-custom-identifiable-service.domain")
......@@ -51,9 +75,55 @@ try {
signedJWT.sign(signer);
signedJWT.serialize(); // => SET, serialized as Base64 encoded string
} catch (IOException | ParseException e) {
throw new RuntimeException("Error during loading of JWK-Set with signature keys.");
} catch (JOSEException e) {
throw new RuntimeException("Could not generate SET");
} catch (JOSEException e) {
throw new RuntimeException("Could not generate SET");
}
```
</TabItem>
</Tabs>
Dies kann dann über ein `POST /submissions/<uuid>/events` erreicht werden. Hier wird das Event über den Request-Body
übertragen und vom Zustelldienst syntaktisch und auf eine korrekte Signatur geprüft. Sind alle Prüfungen erfolgreich
durchlaufen, wird das SET im Event Log abgespeichert und der Zustand der Einreichung abhängig vom Event geändert.
## Event Log abfragen
Der Event Log einer Einreichung kann über `GET /submissions/<uuid>/events` abgefragt werden. Hierbei wird der Event Log der Einreichung
zurückgeliefert, der die verschiedenen Statusübergänge bzw. abgelegten Ereignisse beinhaltet. Das Ergebnis könnte wie folgt aussehen:
```json
{
"eventLog": [
"eyJraWQiOiJkZDA0MDllNS00MTBlLTRkOTgtODViNi1mODFhNDBiOGQ5ODAiLCJ0eXAiOiJzZWNldmVudCtqd3QiLCJhbGciOiJQUzUxMiJ9.ewogICJpc3MiOiAiaHR0cHM6Ly9hcGkuZml0a28uZGUvZml0LWNvbm5lY3QvIiwKICAiaWF0IjogMTYyMjc5NDMxOSwKICAianRpIjogIkVEQ0ZCRjIxLTVCMTYtNEQwNi05OUQwLURDNEMyNkY0RkI5RSIsCiAgInN1YiI6ICJzdWJtaXNzaW9uOkY2NUZFQUIyLTQ4ODMtNERGRi04NUZCLTE2OTQ0ODU0NUQ5RiIsCiAgImV2ZW50cyI6IHsKICAgICJodHRwczovL3NjaGVtYS5maXRrby5kZS9maXQtY29ubmVjdC9ldmVudHMvY3JlYXRlLXN1Ym1pc3Npb24iOiB7fQogIH0sCiAgInR4biI6ICJjYXNlOkY3M0QzMEM2LTg4OTQtNDQ0NC04Njg3LTAwQUU3NTZGRUE5MCIKfQ.TQBR_CBsoULi3cGaGg4oqFelQ9GVn8G-cNokzTVDZgZf4D7x_8wjsDcgTd0aamiy8ErlnV1xoAoDcPw81vajrBCaYgf9KI4sNhsW78jlDi_ywK04YhFbkvloDMioGf_5zCNTBreN9bTnU_VYuWB23R_YrYGi2exONft-ZReN_crEvDaKLdG9hqnaCRFwKJ1t8TbLvIyBKLqQYEqP0Oh6m3WA9IRz3EB41S-PZgJCIzmz_GvXdRvw_1B8A_Q7aHr2SQ6Dc-c406UJ5P_7FuypE6tLyuYf5GkmFZSauQ51H4LLl8pLrsW2PJJ28cMavOEx0AWoRLwB7yKK5bAGtcALWw-0W7Wmw1QEX3DZGTpXbEUM0U_7iXeEFrdtfCCbFPMVbmlK-b66IyKK_6yeaOAEjQvCUOrALfa2sSOS6RWiNOKyA1l1L29VoIBXgQ8np72NMV8-AP7UnQO1NPBghBM6LW6tcXceWeP8ayy4eEaZQ639pqH4TJRRkQqnuoTeADpYL9sX2hM9173O4abWiE-Z8zW2AQ1jhUvVXJ8w9ddtMIyjZJZOqoy3TbHxUYpn4UqbedlDyahpUiKCT7-qU2jOjeXAXEPQvWlSzLigNtFvYCEq-fOe1lpeNktoQQrC3Y-szk2vNj5fT_KmJY1QG1bhyrUMoGbA-pe45c-FcCE7ErQ",
"eyJraWQiOiJkZDA0MDllNS00MTBlLTRkOTgtODViNi1mODFhNDBiOGQ5ODAiLCJ0eXAiOiJzZWNldmVudCtqd3QiLCJhbGciOiJQUzUxMiJ9.ewogICJpc3MiOiAiaHR0cHM6Ly9hcGkuZml0a28uZGUvZml0LWNvbm5lY3QvIiwKICAiaWF0IjogMTYyMjc5NTczMiwKICAianRpIjogIjkwRDlCMjlELUMwNUYtNEYwMy04MUMwLUUyMzMxMTZDNTZEOSIsCiAgInN1YiI6ICJzdWJtaXNzaW9uOkY2NUZFQUIyLTQ4ODMtNERGRi04NUZCLTE2OTQ0ODU0NUQ5RiIsCiAgImV2ZW50cyI6IHsKICAgICJodHRwczovL3NjaGVtYS5maXRrby5kZS9maXQtY29ubmVjdC9ldmVudHMvc3VibWl0LXN1Ym1pc3Npb24iOiB7fQogIH0sCiAgInR4biI6ICJjYXNlOkY3M0QzMEM2LTg4OTQtNDQ0NC04Njg3LTAwQUU3NTZGRUE5MCIKfQ.THmHiZoYEMyyWCu2R4nEJtvgtB5PF0KAqtfu_Z-yVjfjSkXW7TtZnX96UAeCGsjpxkBJvXTXAgSB5n378KjZXebAtI7nbFE0gYgt3fwmxmpJitA-4e8v6KfvhwNcdqJHLKDzYRMq_yw7UiwLx1Cxz6nBiOKfR4piL707muKXTgD7DuP0kv-c6V9dGNQ4KzT_sJP5zDWogEzGWSVaLaJZrmDZHoUZMZ6C9kI7SvC-A7Q0ROkFznU_cpjjEAIG74_YCiICvjr91ueQWTdNyc1DBvxpEBtBWq6nWPTg0d91iQlhPUgNKbmC4QtG_tFctTYhX7stO-JbL-4VnAQjQHD5uw4SvvpPrTN4Z3Wz2IjMm8-ClI9imGKThfAqwTaWtJv7Bn_FDiN_nEuGyN2of-M2vZWa-DlZ2iPFct6ESp9PumaO_pIF5cUrX4IBoe3fcmg788-ClReytCMjD13uPVOVoIb3yimUdupOUROxb3MITowHP2-YG1gWqhQp22XSQXktugDHWezAuN0xuimwAJq_OvyoDxj4lsnn6BQkqZYdqD0hJghwqZIytg8PlIi76Cdvh8NFgVw48xZ0WUOFvBPJO2Qe8PiTSVX_P9CIIWxsKlYwg8vJ226qi0eYfD70ynjBDQIPmsOOSut6bFKgOLBFa9ZvCy6HmhyLa-EsgLhS4uc",
"eyJraWQiOiJkZDA0MDllNS00MTBlLTRkOTgtODViNi1mODFhNDBiOGQ5ODAiLCJ0eXAiOiJzZWNldmVudCtqd3QiLCJhbGciOiJQUzUxMiJ9.ewogICJpc3MiOiAiaHR0cHM6Ly9hcGkuZml0a28uZGUvZml0LWNvbm5lY3QvIiwKICAiaWF0IjogMTYyMjc5NjUzMiwKICAianRpIjogIjBCRjZEQkY2LUNFN0UtNDRBMy04ODlGLTgyRkU3NEMzRTcxNSIsCiAgInN1YiI6ICJzdWJtaXNzaW9uOkY2NUZFQUIyLTQ4ODMtNERGRi04NUZCLTE2OTQ0ODU0NUQ5RiIsCiAgImV2ZW50cyI6IHsKICAgICJodHRwczovL3NjaGVtYS5maXRrby5kZS9maXQtY29ubmVjdC9ldmVudHMvYWNjZXB0LXN1Ym1pc3Npb24iOiB7fQogIH0sCiAgInR4biI6ICJjYXNlOkY3M0QzMEM2LTg4OTQtNDQ0NC04Njg3LTAwQUU3NTZGRUE5MCIKfQ.blxz8Tw_Sl8_tomcqxezamX_DVGyGiu61iYGv3mA3yVLLSDlPscjcHm_MCNm5iq-ODUk-FCW1ljOexN2czZJic8wvLhWhcUt8U2kkkjis-CWz4oqhuB4ynAj7Yyn4H4xkLoH7Y6k9pqW9P2mN7984o_578mJJ4mQSNEGcPr_BDbRc2nUKcupG7iS-hx6VTjrRTP7LGPyOblDB8oL_QyT9qY0US7PT35QgiraUSK3RWhDpj6C0I4bOV5cQeSqlXT2xIfeO3sUPeWLYVmGjuB8QWvDsniKz6JqRN-v39FrAppsOufdiRim36wtBZt9o-3txjtz5wu0_eSfjOueGJbfqAeWsbd2TYwZtL-7Z-MPfoe3XInDNmmTfxo4KXkF1GkRnGnjniwrWBHeh18A04NNHYcX-vsoijEreqDN2lEKwks3pDK5Twe5O9RxJ0cYB8oeKB55rJzs15pfla69qVn9zFvCAc_ji_9WaAa_mIG0zimMucG3qA0KrUww88FaS4heh5-Gs1Ik35QoUOCCa7ZMJMKxYArFCgUqHw-gX60U5mp4hy7tVe3hD-RxIRnlTIkEkHgDGmslVc1t8fC9oPgljQirPcTIeWhVyLmk6rJLgR5nqizujz3hDUCdBuRF43fS6qedmYfHq1MyakJzEFe2ht1rpGw4ftAt0kcOBOf2jyQ"
]
}
```
Im Log dieser Einreichung wurden drei Events aufgezeichnet. Das letzte, aktuellste Security-Event-Token hat folgenden Payload.
```json
{
"iss": "https://api.fitko.de/fit-connect/",
"iat": 1622796532,
"jti": "0BF6DBF6-CE7E-44A3-889F-82FE74C3E715",
"sub": "submission:F65FEAB2-4883-4DFF-85FB-169448545D9F",
"events": {
"https://schema.fitko.de/fit-connect/events/accept-submission": {}
},
"txn": "case:F73D30C6-8894-4444-8687-00AE756FEA90"
}
```
In dem SET ist folgende Information abgelegt:
- Er wurde vom Zustelldienst https://api.fitko.de/fit-connect/ ausgestellt (iss = issuer)
- Er wurde am 04.06.2021 um 08:48:52 GMT+0 (Unixzeit 1622796532) aufgezeichnet (iat = issued at)
- Er hat die eindeutige ID `0BF6DBF6-CE7E-44A3-889F-82FE74C3E715` (jti = JWT ID)
- Er betrifft die Einreichung `F65FEAB2-4883-4DFF-85FB-169448545D9F` (sub = subject)
- Die Submission wurde angelegt "accept-submission" (events)
- Die Submission gehört zur Vorgangsreferenz (case) `F73D30C6-8894-4444-8687-00AE756FEA90`
Aus dem Event des SET lässt sich ableiten, dass der aktuelle Status der Einreichung `accepted` ist und der Zeitpunkt des
Übergangs der 04.06.2021 um 08:48:52 GMT+0 war. Da alle SETs im Event Log signiert sind, kann diese Signatur auch noch
überprüft werden. Die Überprüfung ist im Artikel zum [Event Log](../event-log.md#set-validation) beschrieben.
docs/getting-started/sending/query-status.mdx
+ 1
− 1
View file @ 6dc1719f
......@@ -91,6 +91,6 @@ In dem SET ist folgende Information abgelegt:
- Die Submission wurde angelegt "accept-submission" (events)
- Die Submission gehört zur Vorgangsreferenz (case) `F73D30C6-8894-4444-8687-00AE756FEA90`
Aus dem Event des SET lässt sich ableiten dass der aktuelle Status der Einreichung `accepted` ist und der Zeitpunkt des
Aus dem Event des SET lässt sich ableiten, dass der aktuelle Status der Einreichung `accepted` ist und der Zeitpunkt des
Übergangs der 04.06.2021 um 08:48:52 GMT+0 war. Da alle SETs im Event Log signiert sind, kann diese Signatur auch noch
überprüft werden. Die Überprüfung ist im Artikel zum [Event Log](../event-log.md#set-validation) beschrieben.
src/css/custom.css
+ 7
− 0
View file @ 6dc1719f
......@@ -9,3 +9,10 @@ dl dt {
fill: var(--ifm-font-color-base);
stroke: var(--ifm-font-color-base);
}
.docusaurus-highlight-code-line {
background-color: rgba(0,0,0, 0.3);
display: block;
margin: 0 calc(-1 * var(--ifm-pre-padding));
padding: 0 var(--ifm-pre-padding);
}
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment