From 530dc3d566ff15319258b14462cfcd1253e3eac8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20Harasimowicz?= Date: Thu, 17 Mar 2022 10:03:18 +0100 Subject: [PATCH 1/5] Add documentation about blocking web hooks --- docs/kratos/self-service/hooks.mdx | 73 ++++++++++++++++++++++++------ 1 file changed, 59 insertions(+), 14 deletions(-) diff --git a/docs/kratos/self-service/hooks.mdx b/docs/kratos/self-service/hooks.mdx index 92b706dad..219309859 100644 --- a/docs/kratos/self-service/hooks.mdx +++ b/docs/kratos/self-service/hooks.mdx @@ -104,6 +104,7 @@ following structure: url: https://test.kratos.ory.sh/after_verification_hook method: POST # GET, DELETE, etc body: file:///path/of/my/jsonnet/file + can_interrupt: true auth: type: config: @@ -116,17 +117,14 @@ The configuration section of a web-hook consists of - `body` - URI of a jsonnet template, used by the web-hook to render the payload to send (optional). Use a `file://path/to/body.jsonnet` URL for referring to local files. This property is ignored for HTTP `method`s, which don't support sending of HTTP body payloads. -- `auth` - configuration of authentication and authorization mechanisms to be used by the web-hook - -Web-Hooks bind the `flow`, as well as request headers (`request_headers`), request method (`request_method`), and the request url -(`request_url`) of the flow into the jsonnet template for all methods and execution paths (before and after). For the `after` -execution path of all flows, it binds the `identity` object into the jsonnet template as well. These objects are available through -a `ctx` object. To create a body looking like `{ user_id: }` to be sent to the web hook endpoint, the Jsonnet template -would look like this: - -```jsonnet -function(ctx) { user_id: ctx.identity.id } -``` +- `auth` - configuration of authentication and authorization mechanisms to be + used by the web-hook +- `can_interrupt` - specifies if a given web hook can interrupt the flow by + returning a predefined JSON message with validation errors or just stop flow + without user facing errors. This is useful when integrating Kratos + self-service flows with external systems that can do some extra input + validation (i.e. user identity, username availability in other systems etc.). + See below for an example response. #### Canceling Webhooks @@ -171,7 +169,7 @@ To do that, set `response.ignore` to `true` in the webhook config: #### Web-Hook Authentication and Authorization Mechanisms -For `auth` following mechanisms are supported: +Web-hooks supports the following mechanisms for the `auth` parameter: - Authentication via an Api Key. Type must be set to `api_key`. - Authentication via Basic Authentication. Type must be set to `basic_auth`. @@ -195,10 +193,57 @@ password: My-Pass-Value All properties are mandatory. +### Interruptable Web-Hooks + +Sometimes notification-like web hooks are not enough and one need to integrate +some external business logic into user's self-service flows. Here interruptable +web-hooks comes with help. Basic flow is to pass self-service flow to an +external service that will decide if the process should continue or user should +be notified about an error (or fail silently). To achieve that interruptable +web-hook can be defined by specifying `can_interrupt` flag and pointing it to a +web service that will process the payload from the webhook and will return a +predefined JSON that will instruct Kratos to forward this information to the +front end. When hook service returns status code that is equal or lower than 399 +the self-service flow continues normally but if web hook returns 400 or higher +Kratos parses the returned JSON and looks for a messages that can be forwarded +to the front end. Sample payload may look like this: + +```json +{ + "messages": [ + { + "instance_ptr": "#/traits/foo/bar", + "message": "bar field is violating our policies", + "detailed_meesages": [ + { + "id": 123, + "text": "field must be longer than 12 characters", + "type": "validation", + "context": { + "value": "short value" + } + } + ] + } + ] +} +``` + +Since the whole idea of blocking hooks is to allow to interrupt selfservice flow +and provide user with a meaningfull information (messages/errors) please cofigure +them in `after` web hooks configurations. + +Some clarifications about meaning of some fields: + +- `instance_ptr` points to the field in the payload/schema that this error + refers to (displayed by the frontend next to the corresponding field) +- `id` is the unique numeric error ID that helps to translate messages in the + front end aplpication. + ## Login -Hooks running before or after successful user login are defined per Self-Service Registration Method in Ory Kratos' configuration -file. +For each Registration Method in Ory Kratos' configuration file allows to setup +hooks that runs before or after successful user login. ### Before From 6f887de5457cb9fa55f416770a1414c55613925a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20Harasimowicz?= Date: Wed, 8 Jun 2022 12:55:38 +0200 Subject: [PATCH 2/5] Apply suggestions from code review Co-authored-by: Henning Perl --- docs/kratos/self-service/hooks.mdx | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/kratos/self-service/hooks.mdx b/docs/kratos/self-service/hooks.mdx index 219309859..66247bf15 100644 --- a/docs/kratos/self-service/hooks.mdx +++ b/docs/kratos/self-service/hooks.mdx @@ -120,6 +120,10 @@ The configuration section of a web-hook consists of - `auth` - configuration of authentication and authorization mechanisms to be used by the web-hook - `can_interrupt` - specifies if a given web hook can interrupt the flow by + returning a predefined JSON message either with or without user-facing validation errors. This is useful when integrating Kratos + self-service flows with external systems that can perform some extra input + validation (i.e. user identity, username availability in other systems etc.). + See [below](#interruptable-web-hooks) for an example response.``` returning a predefined JSON message with validation errors or just stop flow without user facing errors. This is useful when integrating Kratos self-service flows with external systems that can do some extra input @@ -169,7 +173,7 @@ To do that, set `response.ignore` to `true` in the webhook config: #### Web-Hook Authentication and Authorization Mechanisms -Web-hooks supports the following mechanisms for the `auth` parameter: +Web-hooks support the following mechanisms for the `auth` parameter: - Authentication via an Api Key. Type must be set to `api_key`. - Authentication via Basic Authentication. Type must be set to `basic_auth`. @@ -238,7 +242,7 @@ Some clarifications about meaning of some fields: - `instance_ptr` points to the field in the payload/schema that this error refers to (displayed by the frontend next to the corresponding field) - `id` is the unique numeric error ID that helps to translate messages in the - front end aplpication. + frontend application. ## Login From 761d1b4931e7118054ccc43f4d01008bc6ab4df8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20Harasimowicz?= Date: Wed, 8 Jun 2022 13:14:10 +0200 Subject: [PATCH 3/5] Update docs regarding blocking webhooks --- docs/kratos/self-service/hooks.mdx | 23 ++++++++++++----------- 1 file changed, 12 insertions(+), 11 deletions(-) diff --git a/docs/kratos/self-service/hooks.mdx b/docs/kratos/self-service/hooks.mdx index 66247bf15..cf7b370b7 100644 --- a/docs/kratos/self-service/hooks.mdx +++ b/docs/kratos/self-service/hooks.mdx @@ -199,18 +199,19 @@ All properties are mandatory. ### Interruptable Web-Hooks -Sometimes notification-like web hooks are not enough and one need to integrate -some external business logic into user's self-service flows. Here interruptable -web-hooks comes with help. Basic flow is to pass self-service flow to an -external service that will decide if the process should continue or user should -be notified about an error (or fail silently). To achieve that interruptable -web-hook can be defined by specifying `can_interrupt` flag and pointing it to a -web service that will process the payload from the webhook and will return a +Sometimes notification-like web hooks are not enough and one needs to integrate +some external business logic into user's self-service flows. This can be solved with interruptible web-hooks. Kratos passes the self-service flow to an +external service that will decide if the flow should continue or not. If the flow is interrupted, the web-hook can further decide if the user should +be notified about the error, or if the failure is silent. + +Interruptable web-hooks must be defined by specifying can_interrupt flag. The +web service specified with url will process the payload from the webhook and will return a predefined JSON that will instruct Kratos to forward this information to the -front end. When hook service returns status code that is equal or lower than 399 -the self-service flow continues normally but if web hook returns 400 or higher -Kratos parses the returned JSON and looks for a messages that can be forwarded -to the front end. Sample payload may look like this: +frontend as follows: +- Status code <400: The self-service flow continues as normal +- Status code 400 or higher: Kratos parses the returned JSON and looks for a messages that can be forwarded to the frontend. + +Sample payload may look like this: ```json { From aba51362dae8bc8d047b55267890c73837ade289 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20Harasimowicz?= Date: Wed, 8 Jun 2022 13:20:06 +0200 Subject: [PATCH 4/5] Revert unwanted change in Login hook documentation --- docs/kratos/self-service/hooks.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/kratos/self-service/hooks.mdx b/docs/kratos/self-service/hooks.mdx index cf7b370b7..71675ef21 100644 --- a/docs/kratos/self-service/hooks.mdx +++ b/docs/kratos/self-service/hooks.mdx @@ -247,8 +247,8 @@ Some clarifications about meaning of some fields: ## Login -For each Registration Method in Ory Kratos' configuration file allows to setup -hooks that runs before or after successful user login. +Hooks running before or after successful user login are defined per Self-Service +Registration Method in Ory Kratos' configuration file. ### Before From 5a3141297a73a5b56e88ef05335f3cb58de3da35 Mon Sep 17 00:00:00 2001 From: aeneasr <3372410+aeneasr@users.noreply.github.com> Date: Thu, 21 Jul 2022 20:02:55 +0200 Subject: [PATCH 5/5] fix: update api --- docs/kratos/self-service/hooks.mdx | 55 +++++++++++++----------------- 1 file changed, 24 insertions(+), 31 deletions(-) diff --git a/docs/kratos/self-service/hooks.mdx b/docs/kratos/self-service/hooks.mdx index 71675ef21..229da4245 100644 --- a/docs/kratos/self-service/hooks.mdx +++ b/docs/kratos/self-service/hooks.mdx @@ -117,18 +117,14 @@ The configuration section of a web-hook consists of - `body` - URI of a jsonnet template, used by the web-hook to render the payload to send (optional). Use a `file://path/to/body.jsonnet` URL for referring to local files. This property is ignored for HTTP `method`s, which don't support sending of HTTP body payloads. -- `auth` - configuration of authentication and authorization mechanisms to be - used by the web-hook -- `can_interrupt` - specifies if a given web hook can interrupt the flow by - returning a predefined JSON message either with or without user-facing validation errors. This is useful when integrating Kratos - self-service flows with external systems that can perform some extra input - validation (i.e. user identity, username availability in other systems etc.). - See [below](#interruptable-web-hooks) for an example response.``` - returning a predefined JSON message with validation errors or just stop flow - without user facing errors. This is useful when integrating Kratos - self-service flows with external systems that can do some extra input - validation (i.e. user identity, username availability in other systems etc.). - See below for an example response. +- `auth` - configuration of authentication and authorization mechanisms to be used by the web-hook +- `can_interrupt` - specifies if a given web hook can interrupt the flow by returning a predefined JSON message either with or + without user-facing validation errors. This is useful when integrating Kratos self-service flows with external systems that can + perform some extra input validation (i.e. user identity, username availability in other systems etc.). See + [below](#interruptable-web-hooks) for an example response.``` returning a predefined JSON message with validation errors or just + stop flow without user facing errors. This is useful when integrating Kratos self-service flows with external systems that can + do some extra input validation (i.e. user identity, username availability in other systems etc.). See below for an example + response. #### Canceling Webhooks @@ -199,15 +195,15 @@ All properties are mandatory. ### Interruptable Web-Hooks -Sometimes notification-like web hooks are not enough and one needs to integrate -some external business logic into user's self-service flows. This can be solved with interruptible web-hooks. Kratos passes the self-service flow to an -external service that will decide if the flow should continue or not. If the flow is interrupted, the web-hook can further decide if the user should -be notified about the error, or if the failure is silent. +Sometimes notification-like web hooks are not enough and one needs to integrate some external business logic into user's +self-service flows. This can be solved with interruptible web-hooks. Kratos passes the self-service flow to an external service +that will decide if the flow should continue or not. If the flow is interrupted, the web-hook can further decide if the user +should be notified about the error, or if the failure is silent. + +Interruptable web-hooks must be defined by specifying can_interrupt flag. The web service specified with url will process the +payload from the webhook and will return a predefined JSON that will instruct Kratos to forward this information to the frontend +as follows: -Interruptable web-hooks must be defined by specifying can_interrupt flag. The -web service specified with url will process the payload from the webhook and will return a -predefined JSON that will instruct Kratos to forward this information to the -frontend as follows: - Status code <400: The self-service flow continues as normal - Status code 400 or higher: Kratos parses the returned JSON and looks for a messages that can be forwarded to the frontend. @@ -218,8 +214,7 @@ Sample payload may look like this: "messages": [ { "instance_ptr": "#/traits/foo/bar", - "message": "bar field is violating our policies", - "detailed_meesages": [ + "messages": [ { "id": 123, "text": "field must be longer than 12 characters", @@ -234,21 +229,19 @@ Sample payload may look like this: } ``` -Since the whole idea of blocking hooks is to allow to interrupt selfservice flow -and provide user with a meaningfull information (messages/errors) please cofigure -them in `after` web hooks configurations. +Since the whole idea of blocking hooks is to allow to interrupt selfservice flow and provide user with a meaningfull information +(messages/errors) please cofigure them in `after` web hooks configurations. Some clarifications about meaning of some fields: -- `instance_ptr` points to the field in the payload/schema that this error - refers to (displayed by the frontend next to the corresponding field) -- `id` is the unique numeric error ID that helps to translate messages in the - frontend application. +- `instance_ptr` points to the field in the payload/schema that this error refers to (displayed by the frontend next to the + corresponding field) +- `id` is the unique numeric error ID that helps to translate messages in the frontend application. ## Login -Hooks running before or after successful user login are defined per Self-Service -Registration Method in Ory Kratos' configuration file. +Hooks running before or after successful user login are defined per Self-Service Registration Method in Ory Kratos' configuration +file. ### Before