Skip to content
Snippets Groups Projects
Verified Commit d58deebe authored by Florian Kaufmann's avatar Florian Kaufmann
Browse files

docs: :pencil2: Verbesserung der set-validation doku (planning#366)

parent f779b883
No related branches found
No related tags found
1 merge request!154Doku anpassung set-payload-schema (planning#366)
Hide whitespace changes
Inline Side-by-side
docs/getting-started/event-log/set-validation.mdx
+ 19
− 11
View file @ d58deebe
......@@ -8,10 +8,18 @@ import TabItem from '@theme/TabItem'
# SET Prüfung
## Einleitung {#einleitung}
Um eine vollständige Prüfung eines Security-Event-Tokens durchzuführen, MUSS zwingend sowohl die Einhaltung der (kryptografischen) Vorgaben als auch die Signatur geprüft werden.
Die Prüfung der Signatur des SET ist abhängig vom ausstellenden System (Zustelldienst, Subscriber oder Sender).
Aus technischer Sicht sollte auch das SET-Payload-Schema validiert werden um
Sowohl die Prüfung der kryptografischen Vorgaben, als auch die Prüfung der Signatur darf KEINESFALLS ausgelassen werden.
Aus technischer Sicht sollte auch das unter `$schema` angegebene SET-Payload-Schema validiert werden.
Dies wird z.B. auch schon vom zuständigen Zustelldienst gemacht.
Aktuell ist die Angabe eines SET-Payload-Schemas aber noch optional und kann nicht existieren.
Dies wird in unspezifizierter Zukunft `deprecated` und alle SETs müssen ein valides SET-Payload-Schema verwenden und angeben.
In dem Fall, dass das SET-Payload-Schema nicht angegeben ist, müssen trotzdem die kryptografischen Vorgaben bzw. die kryptografische Signatur validiert werden.
:::caution
Sowohl die Prüfung der kryptografischen Vorgaben, als auch die Prüfung der kryptografischen Signatur darf KEINESFALLS ausgelassen werden.
:::
## Prüfung der Einhaltung von kryptografischen Vorgaben und der Struktur
......@@ -25,15 +33,15 @@ Alle generierten Security-Event-Tokens MÜSSEN den Vorgaben aus [RFC 7519](https
In der Payload des signierten SET MÜSSEN die folgenden [standardisierten Felder](https://www.iana.org/assignments/jwt/jwt.xhtml) gesetzt sein (Temporäre Ausnahme `$schema`):
| Feld | Inhalt | Erläuterung |
|-----------|----------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `$schema` | URL Referenz auf das verwendete SET-Payload-Schema | Gibt das SET-Payload-Schema an, dem das SET entspricht. Dieses Schema wird auch vom Zustelldienst validert. <br/> Jeddoch ist es aktuell noch möglich kein `$schema` anzugeben. In diesem Fall findet keine Validation im Zustelldienst statt. <br/> Das Schema kann zur eigenen Validierung der SET Payload von der referenzierten URL bezogen werden. Derzeit ist die Version [1.0.0](https://schema.fitko.de/fit-connect/set-payload/1.0.0/set-payload.schema.json) des SET-Payload-Schemas aktuell. Mit diesem Schema `1.0.0` stellt auch der Zustelldienst seine SETs aus. Bis auf Weiteres kann auch noch die Version [0.1.0](https://schema.fitko.de/fit-connect/set-payload/1.0.0/set-payload.schema.json) verwendet werden. Inhaltlich ist sie deckungsgleich mit der Version `1.0.0`. Diese Version `0.1.0` wird deswegen in noch unspezifizierter Zukunft mit Ankündigung `deprecated` und sollte nicht mehr verwendet werden. Aktuell muss eine Validation aber beide Schema Versionen (`0.1.0` und `1.0.0`) unterstüzen. |
| `jti` | UUID des Token | Die JWT ID ist eine eindeutige ID des SET bzw. JWT. Es wird eine zufällige UUID verwendet. |
| `iss` | ID des Token Issuers | Diese Angabe dient dazu, um herauszufinden, wer den Token ausgestellt hat. Für SETs, die vom Zustelldienst ausgestellt sind, wird die Host-Adresse (API-URL) verwendet. Bei SETs von empfangenden Systemen ist die `destinationId`, an der dieser die Submission schickt. |
| `iat` | Timestamp (UNIX-Format) | Zeitpunkt der Ausstellung des SET. |
| `sub` | URI, die den Gegenstand des SET identifiziert | Das Subject eines SET ist eine Kombination aus dem Schlüsselwort `submission` und der Id `submissionId` der Resource. |
| `txn` | URI, die den Vorgang identifiziert | Als "Transaction Identifier" wird die Vorgangsreferenz `caseId` angegeben. |
| `events` | JSON-Objekt der Events in diesem Event-Token | Das Objekt `events` enthält genau ein Ereignis zu einem logischen Sachverhalt bzw. Gesamtereignis, wie bspw. der Versendung einer Einreichung durch den Sender. Dieses Objekt beinhaltet immer zwingend eine URI, die das jeweilige Gesamtereignis eindeutig identifiziert. Das Objekt der URI des Gesamtereignisses kann leer sein oder weitergehende Informationen beinhalten (Siehe [Ereignisse](./events.mdx)) |
| Feld | Inhalt | Erläuterung |
|-----------|----------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `$schema` | URL Referenz auf das verwendete SET-Payload-Schema | Gibt das SET-Payload-Schema an, dem das SET entspricht. Dieses Schema wird auch vom Zustelldienst validert. <br/><br/> Aktuell ist es noch möglich kein `$schema` anzugeben. In diesem Fall findet keine Validation im Zustelldienst statt und ist auch keine client-seitige Validierung möglich. Siehe [Einleitung](#einleitung) <br/><br/> Das Schema kann zur client-seitigen Validierung der SET Payload von der referenzierten URL bezogen werden. Auch eine client-seitige Validierung durch statisch hinterlegten Schema Versionen ist möglich, solange die von uns vorgegebenen Versionen unterstützt werden. Derzeit ist die Version [1.0.0](https://schema.fitko.de/fit-connect/set-payload/1.0.0/set-payload.schema.json) des SET-Payload-Schemas aktuell. Mit diesem Schema `1.0.0` stellt auch der Zustelldienst seine SETs aus. Bis auf Weiteres kann auch noch die Version [0.1.0](https://schema.fitko.de/fit-connect/set-payload/1.0.0/set-payload.schema.json) verwendet werden. Inhaltlich ist sie deckungsgleich mit der Version `1.0.0`. Diese Version `0.1.0` wird deswegen in noch unspezifizierter Zukunft mit Ankündigung `deprecated` und sollte nicht mehr verwendet werden. <br/><br/> Aktuell muss eine SET-Payload Validation beide SET-Payload-Schema Versionen (`0.1.0` und `1.0.0`) sowie ein fehlendes SET-Payload-Schema unterstüzten. |
| `jti` | UUID des Token | Die JWT ID ist eine eindeutige ID des SET bzw. JWT. Es wird eine zufällige UUID verwendet. |
| `iss` | ID des Token Issuers | Diese Angabe dient dazu, um herauszufinden, wer den Token ausgestellt hat. Für SETs, die vom Zustelldienst ausgestellt sind, wird die Host-Adresse (API-URL) verwendet. Bei SETs von empfangenden Systemen ist die `destinationId`, an der dieser die Submission schickt. |
| `iat` | Timestamp (UNIX-Format) | Zeitpunkt der Ausstellung des SET. |
| `sub` | URI, die den Gegenstand des SET identifiziert | Das Subject eines SET ist eine Kombination aus dem Schlüsselwort `submission` und der Id `submissionId` der Resource. |
| `txn` | URI, die den Vorgang identifiziert | Als "Transaction Identifier" wird die Vorgangsreferenz `caseId` angegeben. |
| `events` | JSON-Objekt der Events in diesem Event-Token | Das Objekt `events` enthält genau ein Ereignis zu einem logischen Sachverhalt bzw. Gesamtereignis, wie bspw. der Versendung einer Einreichung durch den Sender. Dieses Objekt beinhaltet immer zwingend eine URI, die das jeweilige Gesamtereignis eindeutig identifiziert. Das Objekt der URI des Gesamtereignisses kann leer sein oder weitergehende Informationen beinhalten (Siehe [Ereignisse](./events.mdx)) |
:::note SET Beispiel
......
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