Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

document meta property in secret rotated lifecycle webhooks for extension #300

Merged
merged 2 commits into from
Oct 25, 2024
Merged

document meta property in secret rotated lifecycle webhooks for extension #300

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c26fb8e
document meta property in secret rotated lifecycle webhooks for exten…
freisenhauer-mittwald Oct 24, 2024
46f4847
Update i18n/de/docusaurus-plugin-content-docs/current/contribution/5-…
freisenhauer Oct 25, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
54 changes: 36 additions & 18 deletions docs/contribution/5-reference/4-webhooks.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -91,10 +91,7 @@ You may use the following placeholders:
},
meta: {
type: "object",
required: [
"extensionId",
"contributorId"
],
required: ["extensionId", "contributorId"],
properties: {
extensionId: {
type: "string",
Expand Down Expand Up @@ -212,10 +209,7 @@ You may use the following placeholders:
},
meta: {
type: "object",
required: [
"extensionId",
"contributorId"
],
required: ["extensionId", "contributorId"],
properties: {
extensionId: {
type: "string",
Expand Down Expand Up @@ -271,7 +265,15 @@ You may use the following placeholders:
format="yaml"
schema={{
type: "object",
required: ["apiVersion", "context", "kind", "id", "secret", "request"],
required: [
"apiVersion",
"context",
"kind",
"id",
"meta",
"secret",
"request",
],
properties: {
apiVersion: {
type: "string",
Expand Down Expand Up @@ -300,6 +302,22 @@ You may use the following placeholders:
},
},
},
meta: {
type: "object",
required: ["extensionId", "contributorId"],
properties: {
extensionId: {
type: "string",
format: "uuid",
example: "c593348d-f594-492a-8185-2b89848a4160",
},
contributorId: {
type: "string",
format: "uuid",
example: "680ba069-7465-4932-8b23-e73914b2e051",
},
},
},
secret: {
type: "string",
example: "ROFLieg83rjfdoi9lLIifdlfi399fndLKFHj39fjdlr",
Expand Down Expand Up @@ -404,10 +422,7 @@ You may use the following placeholders:
},
meta: {
type: "object",
required: [
"extensionId",
"contributorId"
],
required: ["extensionId", "contributorId"],
properties: {
extensionId: {
type: "string",
Expand Down Expand Up @@ -515,9 +530,12 @@ In that case, domain actions of that extension instance are not accepted.

### meta

Meta information about the extension instance.
Currently, the mStudio only sends the creation date of the extension instance.
This should not be confused with the request meta information which describes the webhook call.
Meta information about the extension (instance).
This includes the extensionID and the contributorID.

These information should be used to ensure that the webhook not only originates from mittwald, but is also intended for the own extension.
This prevents forward replay attacks.
This should not be confused with the request meta information which describes the webhook call itself.

### secret

Expand Down Expand Up @@ -659,8 +677,8 @@ If the values are not set, the mStudio derives them from the extension or genera
},
secret: {
type: "string",
example: "<<SECRET>>"
}
example: "<<SECRET>>",
},
},
}}
/>
60 changes: 41 additions & 19 deletions .../docusaurus-plugin-content-docs/current/contribution/5-reference/4-webhooks.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -91,10 +91,7 @@ Folgende Platzhalter können verwendet werden:
},
meta: {
type: "object",
required: [
"extensionId",
"contributorId"
],
required: ["extensionId", "contributorId"],
properties: {
extensionId: {
type: "string",
Expand Down Expand Up @@ -212,10 +209,7 @@ Folgende Platzhalter können verwendet werden:
},
meta: {
type: "object",
required: [
"extensionId",
"contributorId"
],
required: ["extensionId", "contributorId"],
properties: {
extensionId: {
type: "string",
Expand Down Expand Up @@ -271,7 +265,15 @@ Folgende Platzhalter können verwendet werden:
format="yaml"
schema={{
type: "object",
required: ["apiVersion", "context", "kind", "id", "secret", "request"],
required: [
"apiVersion",
"context",
"kind",
"id",
"meta",
"secret",
"request",
],
properties: {
apiVersion: {
type: "string",
Expand Down Expand Up @@ -300,6 +302,22 @@ Folgende Platzhalter können verwendet werden:
},
},
},
meta: {
type: "object",
required: ["extensionId", "contributorId"],
properties: {
extensionId: {
type: "string",
format: "uuid",
example: "c593348d-f594-492a-8185-2b89848a4160",
},
contributorId: {
type: "string",
format: "uuid",
example: "680ba069-7465-4932-8b23-e73914b2e051",
},
},
},
secret: {
type: "string",
example: "ROFLieg83rjfdoi9lLIifdlfi399fndLKFHj39fjdlr",
Expand Down Expand Up @@ -404,10 +422,7 @@ Folgende Platzhalter können verwendet werden:
},
meta: {
type: "object",
required: [
"extensionId",
"contributorId"
],
required: ["extensionId", "contributorId"],
properties: {
extensionId: {
type: "string",
Expand Down Expand Up @@ -516,7 +531,12 @@ Somit würden auch Domain Actions für eine deaktivierte Extension Instance nich

### meta

Meta-Informationen über die Extension Instance. Derzeit wird lediglich der Erstellungszeitpunkt der Extension Instance übermittelt.
Meta-Informationen über die Extension (Instance).
Diese beinhalten die IDs der Extension und des Contributors.

Diese Informationen sollten bspw. verwendet werden, um sicherzustellen, dass der Webhook nicht nur ursprünglich von mittwald stammt,
sondern auch für die eigene Extension bestimmt ist.
Dies beugt Forward-Replay-Attacken vor.
Dies ist nicht zu verwechseln mit den Request Meta Informationen, die Aufschluss über den Webhook an sich geben.

### secret
Expand Down Expand Up @@ -574,9 +594,10 @@ if err != nil {
}

if !ed25519.Verify(publicKey, bodyBytes, signature) {
panic("invalid signature")
panic("invalid signature")
freisenhauer marked this conversation as resolved.
Show resolved Hide resolved
}
```

````
</TabItem>
<TabItem value="php" label="PHP">
```php
Expand All @@ -593,7 +614,8 @@ $valid = sodium_crypto_sign_verify_detached(
if (!$valid) {
throw new \Exception('invalid request signature');
}
```
````

</TabItem>
</Tabs>

Expand Down Expand Up @@ -649,8 +671,8 @@ Sind diese Werte nicht gesetzt, werden sie aus der Extension abgeleitet oder zuf
},
secret: {
type: "string",
example: "<<SECRET>>"
}
example: "<<SECRET>>",
},
},
}}
/>