mirror of
https://github.com/andwati/zitadel.git
synced 2026-11-19 19:48:45 +00:00
docs: add actions v2 docs (#9652)
# Which Problems Are Solved There is no documentation yet for Actions v2 regarding the different usable types and for migrating from Actions v1 to v2. # How the Problems Are Solved Add documentation for all use-cases. # Additional Changes None # Additional Context Closes #9456 --------- Co-authored-by: Livio Spring <[email protected]> Co-authored-by: Silvan <[email protected]> Co-authored-by: Ramon <[email protected]> Co-authored-by: Elio Bischof <[email protected]> Co-authored-by: Kenta Yamaguchi <[email protected]> Co-authored-by: Harsha Reddy <[email protected]> Co-authored-by: Livio Spring <[email protected]> Co-authored-by: Max Peintner <[email protected]> Co-authored-by: Iraq <[email protected]> Co-authored-by: Copilot <[email protected]>
This commit is contained in:
co-authored by
Livio Spring
Silvan
Ramon
Elio Bischof
Kenta Yamaguchi
Harsha Reddy
Livio Spring
Max Peintner
Iraq
Copilot
parent
a7a5124643
commit
8fdd58f506
@@ -0,0 +1,114 @@
|
||||
---
|
||||
title: Migrate from Actions v1 to v2
|
||||
---
|
||||
|
||||
In this guide, you will have all necessary information to migrate from Actions v1 to Actions v2 with all currently [available Flow Types](/apis/actions/introduction#available-flow-types).
|
||||
|
||||
## Internal Authentication
|
||||
|
||||
### Post Authentication
|
||||
|
||||
A user has authenticated directly at ZITADEL.
|
||||
ZITADEL validated the users inputs for password, one-time password, security key or passwordless factor.
|
||||
|
||||
To react to different authentication actions, the session service, `zitadel.session.v2.SessionService`, provides the different endpoints. As a rule of thumb, use response triggers if you primarily want to handle successful and failed authentications. On the other hand, use event triggers if you need more fine-granular handling, for example by the used authentication factors.
|
||||
|
||||
Some use-cases:
|
||||
|
||||
- Handle successful authentication through the response of `/zitadel.session.v2.SessionService/CreateSession` and `/zitadel.session.v2.SessionService/SetSession`, [Action Response Example](./testing-response)
|
||||
- Handle failed authentication through the response of `/zitadel.session.v2.SessionService/CreateSession` and `/zitadel.session.v2.SessionService/SetSession`, [Action Response Example](./testing-response)
|
||||
- Handle session with password checked through the creation of event `session.password.checked`, [Action Event Example](./testing-event)
|
||||
- Handle successful authentication through the creation of event `user.human.password.check.succeeded`, [Action Event Example](./testing-event)
|
||||
- Handle failed authentication through the creation of event `user.human.password.check.failed`, [Action Event Example](./testing-event)
|
||||
|
||||
### Pre Creation
|
||||
|
||||
A user registers directly at ZITADEL.
|
||||
ZITADEL did not create the user yet.
|
||||
|
||||
Some use-cases:
|
||||
|
||||
- Before a user is created through the request on `/zitadel.user.v2.UserService/AddHumanUser`, [Action Request Example](./testing-request)
|
||||
- Add information to the user through the request on `/zitadel.user.v2.UserService/AddHumanUser`, [Action Request Manipulation Example](./testing-request-manipulation)
|
||||
|
||||
### Post Creation
|
||||
|
||||
A user registers directly at ZITADEL.
|
||||
ZITADEL successfully created the user.
|
||||
|
||||
Some use-cases:
|
||||
|
||||
- After user is created through the response on `/zitadel.user.v2.UserService/AddHumanUser`, [Action Response Example](./testing-response)
|
||||
- At the event of a user creation on `user.human.added`, [Action Event Example](./testing-event)
|
||||
|
||||
## External Authentication
|
||||
|
||||
### Post Authentication
|
||||
|
||||
A user has authenticated externally. ZITADEL retrieved and mapped the external information.
|
||||
|
||||
Some use-cases:
|
||||
|
||||
- Handle the information mapping from the external authentication to internal structure through the response on `/zitadel.user.v2.UserService/RetrieveIdentityProviderIntent`, [Action Response Example](./testing-response)
|
||||
- information about the link to the external IDP available in the response under [`idpInformation`](/apis/resources/user_service_v2/user-service-retrieve-identity-provider-intent)
|
||||
- information if a new user has to be created available in the response under [`addHumanUser`](/apis/resources/user_service_v2/user-service-retrieve-identity-provider-intent), including metadata and link to external IDP
|
||||
|
||||
### Pre Creation
|
||||
|
||||
A user registers directly at ZITADEL.
|
||||
ZITADEL did not create the user yet.
|
||||
|
||||
Some use-cases:
|
||||
|
||||
- Before a user is created through the request on `/zitadel.user.v2.UserService/AddHumanUser`, [Action Request Example](./testing-request)
|
||||
- Add information to the user through the request on `/zitadel.user.v2.UserService/AddHumanUser`, [Action Request Manipulation Example](./testing-request-manipulation)
|
||||
|
||||
### Post Creation
|
||||
|
||||
A user registers directly at ZITADEL.
|
||||
ZITADEL successfully created the user.
|
||||
|
||||
Some use-cases:
|
||||
|
||||
- After user is created through the response on `/zitadel.user.v2.UserService/AddHumanUser`, [Action Response Example](./testing-response)
|
||||
- At the event of a user creation on `user.human.added`, [Action Event Example](./testing-event)
|
||||
|
||||
## Complement Token
|
||||
|
||||
These are executed during the creation of tokens and token introspection.
|
||||
|
||||
### Pre Userinfo
|
||||
|
||||
These are called before userinfo are set in the id_token or userinfo and introspection endpoint response.
|
||||
|
||||
Some use-cases:
|
||||
|
||||
- Add claims to the userinfo through function on `preuserinfo`, [Action Function Example](./testing-function)
|
||||
- Add metadata to user through function on `preuserinfo`, [Action Function Example](./testing-function)
|
||||
- Add logs to the log claim through function on `preuserinfo`, [Action Function Example](./testing-function)
|
||||
|
||||
### Pre Access Token
|
||||
|
||||
These are called before the claims are set in the access token and the token type is `jwt`.
|
||||
|
||||
Some use-cases:
|
||||
|
||||
- Add claims to the userinfo through function on `preaccesstoken`, [Action Function Example](./testing-function)
|
||||
- Add metadata to user through function on `preaccesstoken`, [Action Function Example](./testing-function)
|
||||
- Add logs to the log claim through function on `preaccesstoken`, [Action Function Example](./testing-function)
|
||||
|
||||
## Customize SAML Response
|
||||
|
||||
These are executed before the return of the SAML Response.
|
||||
|
||||
### Pre SAMLResponse Creation
|
||||
|
||||
These are called before attributes are set in the SAMLResponse.
|
||||
|
||||
Some use-cases:
|
||||
|
||||
- Add custom attributes to the response through function on `presamlresponse`, [Action Function Example](./testing-function)
|
||||
- Add metadata to user through function on `presamlresponse`, [Action Function Example](./testing-function)
|
||||
|
||||
|
||||
|
||||
@@ -0,0 +1,169 @@
|
||||
---
|
||||
title: Test Actions Event
|
||||
---
|
||||
|
||||
This guide shows you how to leverage the ZITADEL actions feature to react to events in your ZITADEL instance.
|
||||
You can use the actions feature to create a target that will be called when a specific event occurs.
|
||||
This is useful for integrating with other systems or for triggering workflows based on events in ZITADEL.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before you start, make sure you have everything set up correctly.
|
||||
|
||||
- You need to be at least a ZITADEL [_IAM_OWNER_](/guides/manage/console/managers)
|
||||
- Your ZITADEL instance needs to have the actions feature enabled.
|
||||
|
||||
:::info
|
||||
Note that this guide assumes that ZITADEL is running on the same machine as the target and can be reached via `localhost`.
|
||||
In case you are using a different setup, you need to adjust the target URL accordingly and will need to make sure that the target is reachable from ZITADEL.
|
||||
:::
|
||||
|
||||
## Start example target
|
||||
|
||||
To test the actions feature, you need to create a target that will be called when an event occurs.
|
||||
You will need to implement a listener that can receive HTTP requests and process the events.
|
||||
For this example, we will use a simple Go HTTP server that will print the received events to standard output.
|
||||
|
||||
:::info
|
||||
The signature of the received request can be checked, [please refer to the example for more information on how to](/guides/integrate/actions/testing-request-signature).
|
||||
:::
|
||||
|
||||
```go
|
||||
package main
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"io"
|
||||
"net/http"
|
||||
)
|
||||
|
||||
// webhook HandleFunc to read the request body and then print out the contents
|
||||
func webhook(w http.ResponseWriter, req *http.Request) {
|
||||
// read the body content
|
||||
sentBody, err := io.ReadAll(req.Body)
|
||||
if err != nil {
|
||||
// if there was an error while reading the body return an error
|
||||
http.Error(w, "error", http.StatusInternalServerError)
|
||||
return
|
||||
}
|
||||
defer req.Body.Close()
|
||||
// print out the read content
|
||||
fmt.Println(string(sentBody))
|
||||
}
|
||||
|
||||
func main() {
|
||||
// handle the HTTP call under "/webhook"
|
||||
http.HandleFunc("/webhook", webhook)
|
||||
|
||||
// start an HTTP server with the before defined function to handle the endpoint under "http://localhost:8090"
|
||||
http.ListenAndServe(":8090", nil)
|
||||
}
|
||||
```
|
||||
|
||||
## Create target
|
||||
|
||||
As you see in the example above the target is created with HTTP and port '8090' and if we want to use it as webhook, the
|
||||
target can be created as follows:
|
||||
|
||||
See [Create a target](/apis/resources/action_service_v2/action-service-create-target) for more detailed information.
|
||||
|
||||
```shell
|
||||
curl -L -X POST 'https://$CUSTOM-DOMAIN/v2beta/actions/targets' \
|
||||
-H 'Content-Type: application/json' \
|
||||
-H 'Accept: application/json' \
|
||||
-H 'Authorization: Bearer <TOKEN>' \
|
||||
--data-raw '{
|
||||
"name": "local webhook",
|
||||
"restWebhook": {
|
||||
"interruptOnError": true
|
||||
},
|
||||
"endpoint": "http://localhost:8090/webhook",
|
||||
"timeout": "10s"
|
||||
}'
|
||||
```
|
||||
|
||||
Save the returned ID to set in the execution.
|
||||
|
||||
## Set execution
|
||||
|
||||
To configure ZITADEL to call the target when an event occurs, you need to set an execution and define the event
|
||||
condition.
|
||||
|
||||
See [Set an execution](/apis/resources/action_service_v2/action-service-set-execution) for more detailed information.
|
||||
|
||||
```shell
|
||||
curl -L -X PUT 'https://$CUSTOM-DOMAIN/v2beta/actions/executions' \
|
||||
-H 'Content-Type: application/json' \
|
||||
-H 'Accept: application/json' \
|
||||
-H 'Authorization: Bearer <TOKEN>' \
|
||||
--data-raw '{
|
||||
"condition": {
|
||||
"event": {
|
||||
"event": "user.human.added"
|
||||
}
|
||||
},
|
||||
"targets": [
|
||||
{
|
||||
"target": "<TargetID returned>"
|
||||
}
|
||||
]
|
||||
}'
|
||||
```
|
||||
|
||||
## Example call
|
||||
|
||||
Now that you have set up the target and execution, you can test it by creating a user through the Console UI or
|
||||
by calling the ZITADEL API to create a human user.
|
||||
|
||||
```shell
|
||||
curl -L -X PUT 'https://$CUSTOM-DOMAIN/v2/users/human' \
|
||||
-H 'Content-Type: application/json' \
|
||||
-H 'Accept: application/json' \
|
||||
-H 'Authorization: Bearer <TOKEN>' \
|
||||
--data-raw '{
|
||||
"userId": {
|
||||
"givenName": "Test",
|
||||
"familyName": "User"
|
||||
},
|
||||
"email": {
|
||||
"email": "[email protected]"
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
Your server should now print out something like the following. Check out
|
||||
the [Sent information Event](./usage#sent-information-event) payload description.
|
||||
|
||||
```json
|
||||
{
|
||||
"aggregateID": "313014806065971608",
|
||||
"aggregateType": "user",
|
||||
"resourceOwner": "312909075211944344",
|
||||
"instanceID": "312909075211878808",
|
||||
"version": "v2",
|
||||
"sequence": 1,
|
||||
"event_type": "user.human.added",
|
||||
"created_at": "2025-03-27T10:22:43.262665+01:00",
|
||||
"userID": "312909075212468632",
|
||||
"event_payload": "eyJ1c2VyTmFtZSI6ImV4YW1wbGVAdGVzdC5jb20iLCJmaXJzdE5hbWUiOiJUZXN0IiwibGFzdE5hbWUiOiJVc2VyIiwiZGlzcGxheU5hbWUiOiJUZXN0IFVzZXIiLCJwcmVmZXJyZWRMYW5ndWFnZSI6InVuZCIsImVtYWlsIjoiZXhhbXBsZUB0ZXN0LmNvbSJ9"
|
||||
}
|
||||
```
|
||||
|
||||
The event_payload is base64 encoded and has the following content:
|
||||
|
||||
```json
|
||||
{
|
||||
"userName": "[email protected]",
|
||||
"firstName": "Test",
|
||||
"lastName": "User",
|
||||
"displayName": "Test User",
|
||||
"preferredLanguage": "und",
|
||||
"email": "[email protected]"
|
||||
}
|
||||
```
|
||||
|
||||
## Conclusion
|
||||
|
||||
You have successfully set up a target and execution to react to events in your ZITADEL instance.
|
||||
This feature can now be used to integrate with your existing systems to create custom workflows or automate tasks based on events in ZITADEL.
|
||||
Find more information about the actions feature in the [API documentation](/concepts/features/actions_v2).
|
||||
@@ -0,0 +1,155 @@
|
||||
---
|
||||
title: Test Actions Function Manipulation
|
||||
---
|
||||
|
||||
This guide shows you how to leverage the ZITADEL actions feature to enhance different functions in your ZITADEL instance.
|
||||
You can use the actions feature to create a target that will be called when a specific functionality is used.
|
||||
This is useful for integrating with other systems which need specific claims in tokens or for executing external code during OIDC or SAML flows.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before you start, make sure you have everything set up correctly.
|
||||
|
||||
- You need to be at least a ZITADEL [_IAM_OWNER_](/guides/manage/console/managers)
|
||||
- Your ZITADEL instance needs to have the actions feature enabled.
|
||||
|
||||
:::info
|
||||
Note that this guide assumes that ZITADEL is running on the same machine as the target and can be reached via `localhost`.
|
||||
In case you are using a different setup, you need to adjust the target URL accordingly and will need to make sure that the target is reachable from ZITADEL.
|
||||
:::
|
||||
|
||||
## Available functions
|
||||
|
||||
The available conditions can be found under [all available Functions](/apis/resources/action_service_v2/action-service-list-execution-functions).
|
||||
|
||||
## Start example target
|
||||
|
||||
To test the actions feature, you need to create a target that will be called when a function is used.
|
||||
You will need to implement a listener that can receive HTTP requests and process the data.
|
||||
For this example, we will use a simple Go HTTP server that will send back static data.
|
||||
|
||||
:::info
|
||||
The signature of the received request can be checked, [please refer to the example for more information on how to](/guides/integrate/actions/testing-request-signature).
|
||||
:::
|
||||
|
||||
```go
|
||||
package main
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"net/http"
|
||||
)
|
||||
|
||||
type Response struct {
|
||||
SetUserMetadata []*Metadata `json:"set_user_metadata,omitempty"`
|
||||
AppendClaims []*AppendClaim `json:"append_claims,omitempty"`
|
||||
AppendLogClaims []string `json:"append_log_claims,omitempty"`
|
||||
}
|
||||
|
||||
type Metadata struct {
|
||||
Key string `json:"key"`
|
||||
Value []byte `json:"value"`
|
||||
}
|
||||
|
||||
type AppendClaim struct {
|
||||
Key string `json:"key"`
|
||||
Value any `json:"value"`
|
||||
}
|
||||
|
||||
// call HandleFunc to respond with static data
|
||||
func call(w http.ResponseWriter, req *http.Request) {
|
||||
// create the response with the correct structure
|
||||
resp := &Response{
|
||||
SetUserMetadata: []*Metadata{
|
||||
{Key: "key", Value: []byte("value")},
|
||||
},
|
||||
AppendClaims: []*AppendClaim{
|
||||
{Key: "claim", Value: "value"},
|
||||
},
|
||||
AppendLogClaims: []string{"log1", "log2", "log3"},
|
||||
}
|
||||
data, err := json.Marshal(resp)
|
||||
if err != nil {
|
||||
// if there was an error while marshalling the json
|
||||
http.Error(w, "error", http.StatusInternalServerError)
|
||||
return
|
||||
}
|
||||
w.Write(data)
|
||||
}
|
||||
|
||||
func main() {
|
||||
// handle the HTTP call under "/call"
|
||||
http.HandleFunc("/call", call)
|
||||
|
||||
// start an HTTP server with the before defined function to handle the endpoint under "http://localhost:8090"
|
||||
http.ListenAndServe(":8090", nil)
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
## Create target
|
||||
|
||||
As you see in the example above the target is created with HTTP and port '8090' and if we want to use it as call, the target can be created as follows:
|
||||
|
||||
See [Create a target](/apis/resources/action_service_v2/action-service-create-target) for more detailed information.
|
||||
|
||||
```shell
|
||||
curl -L -X POST 'https://$CUSTOM-DOMAIN/v2beta/actions/targets' \
|
||||
-H 'Content-Type: application/json' \
|
||||
-H 'Accept: application/json' \
|
||||
-H 'Authorization: Bearer <TOKEN>' \
|
||||
--data-raw '{
|
||||
"name": "local call",
|
||||
"restCall": {
|
||||
"interruptOnError": true
|
||||
},
|
||||
"endpoint": "http://localhost:8090/call",
|
||||
"timeout": "10s"
|
||||
}'
|
||||
```
|
||||
|
||||
Save the returned ID to set in the execution.
|
||||
|
||||
## Set execution
|
||||
|
||||
To configure ZITADEL to call the target when a function is executed, you need to set an execution and define the function
|
||||
condition.
|
||||
|
||||
See [Set an execution](/apis/resources/action_service_v2/action-service-set-execution) for more detailed information.
|
||||
|
||||
```shell
|
||||
curl -L -X PUT 'https://$CUSTOM-DOMAIN/v2beta/actions/executions' \
|
||||
-H 'Content-Type: application/json' \
|
||||
-H 'Accept: application/json' \
|
||||
-H 'Authorization: Bearer <TOKEN>' \
|
||||
--data-raw '{
|
||||
"condition": {
|
||||
"function": {
|
||||
"name": "preuserinfo"
|
||||
}
|
||||
},
|
||||
"targets": [
|
||||
{
|
||||
"target": "<TargetID returned>"
|
||||
}
|
||||
]
|
||||
}'
|
||||
```
|
||||
|
||||
## Example call
|
||||
|
||||
Now that you have set up the target and execution, you can test it by logging into Console UI or
|
||||
by using any OIDC flow.
|
||||
|
||||
As a result 3 things happen:
|
||||
- the user get the metadata with the key "key" and value "value" added
|
||||
- the token has a claim "urn:zitadel:iam:claim" added with value "value"
|
||||
- the token has the log claim "urn:zitadel:iam:action:preuserinfo:log" added with values "log1", "log2" and "log3".
|
||||
|
||||
For any further information related to [the OIDC Flow, refer to our documentation.](/guides/integrate/login/oidc/login-users)
|
||||
|
||||
## Conclusion
|
||||
|
||||
You have successfully set up a target and execution to react to functions in your ZITADEL instance.
|
||||
This feature can now be used to integrate with your existing systems to create custom workflows or automate tasks based on functionality in ZITADEL.
|
||||
Find more information about the actions feature in the [API documentation](/concepts/features/actions_v2).
|
||||
@@ -0,0 +1,171 @@
|
||||
---
|
||||
title: Test Actions Function
|
||||
---
|
||||
|
||||
This guide shows you how to leverage the ZITADEL actions feature to enhance different functions in your ZITADEL instance.
|
||||
You can use the actions feature to create a target that will be called when a specific functionality is used.
|
||||
This is useful for integrating with other systems which need specific claims in tokens or for executing external code during OIDC or SAML flows.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before you start, make sure you have everything set up correctly.
|
||||
|
||||
- You need to be at least a ZITADEL [_IAM_OWNER_](/guides/manage/console/managers)
|
||||
- Your ZITADEL instance needs to have the actions feature enabled.
|
||||
|
||||
:::info
|
||||
Note that this guide assumes that ZITADEL is running on the same machine as the target and can be reached via `localhost`.
|
||||
In case you are using a different setup, you need to adjust the target URL accordingly and will need to make sure that the target is reachable from ZITADEL.
|
||||
:::
|
||||
|
||||
## Available functions
|
||||
|
||||
The available conditions can be found under [all available Functions](/apis/resources/action_service_v2/action-service-list-execution-functions).
|
||||
|
||||
## Start example target
|
||||
|
||||
To test the actions feature, you need to create a target that will be called when a function is used.
|
||||
You will need to implement a listener that can receive HTTP requests and process the data.
|
||||
For this example, we will use a simple Go HTTP server that will print the received data to standard output.
|
||||
|
||||
:::info
|
||||
The signature of the received request can be checked, [please refer to the example for more information on how to](/guides/integrate/actions/testing-request-signature).
|
||||
:::
|
||||
|
||||
```go
|
||||
package main
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"io"
|
||||
"net/http"
|
||||
)
|
||||
|
||||
// webhook HandleFunc to read the request body and then print out the contents
|
||||
func webhook(w http.ResponseWriter, req *http.Request) {
|
||||
// read the body content
|
||||
sentBody, err := io.ReadAll(req.Body)
|
||||
if err != nil {
|
||||
// if there was an error while reading the body return an error
|
||||
http.Error(w, "error", http.StatusInternalServerError)
|
||||
return
|
||||
}
|
||||
defer req.Body.Close()
|
||||
// print out the read content
|
||||
fmt.Println(string(sentBody))
|
||||
}
|
||||
|
||||
func main() {
|
||||
// handle the HTTP call under "/webhook"
|
||||
http.HandleFunc("/webhook", webhook)
|
||||
|
||||
// start an HTTP server with the before defined function to handle the endpoint under "http://localhost:8090"
|
||||
http.ListenAndServe(":8090", nil)
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
## Create target
|
||||
|
||||
As you see in the example above the target is created with HTTP and port '8090' and if we want to use it as webhook, the target can be created as follows:
|
||||
|
||||
See [Create a target](/apis/resources/action_service_v2/action-service-create-target) for more detailed information.
|
||||
|
||||
```shell
|
||||
curl -L -X POST 'https://$CUSTOM-DOMAIN/v2beta/actions/targets' \
|
||||
-H 'Content-Type: application/json' \
|
||||
-H 'Accept: application/json' \
|
||||
-H 'Authorization: Bearer <TOKEN>' \
|
||||
--data-raw '{
|
||||
"name": "local call",
|
||||
"restWebhook": {
|
||||
"interruptOnError": true
|
||||
},
|
||||
"endpoint": "http://localhost:8090/webhook",
|
||||
"timeout": "10s"
|
||||
}'
|
||||
```
|
||||
|
||||
Save the returned ID to set in the execution.
|
||||
|
||||
## Set execution
|
||||
|
||||
To configure ZITADEL to call the target when a function is executed, you need to set an execution and define the function
|
||||
condition.
|
||||
|
||||
See [Set an execution](/apis/resources/action_service_v2/action-service-set-execution) for more detailed information.
|
||||
|
||||
```shell
|
||||
curl -L -X PUT 'https://$CUSTOM-DOMAIN/v2beta/actions/executions' \
|
||||
-H 'Content-Type: application/json' \
|
||||
-H 'Accept: application/json' \
|
||||
-H 'Authorization: Bearer <TOKEN>' \
|
||||
--data-raw '{
|
||||
"condition": {
|
||||
"function": {
|
||||
"name": "preuserinfo"
|
||||
}
|
||||
},
|
||||
"targets": [
|
||||
{
|
||||
"target": "<TargetID returned>"
|
||||
}
|
||||
]
|
||||
}'
|
||||
```
|
||||
|
||||
## Example call
|
||||
|
||||
Now that you have set up the target and execution, you can test it by logging into Console UI or
|
||||
by using any OIDC flow.
|
||||
|
||||
Your server should now print out something like the following. Check out the [Sent information Function](./usage#sent-information-function) payload description.
|
||||
```json
|
||||
{
|
||||
"function" : "function/preuserinfo",
|
||||
"userinfo" : {
|
||||
"sub" : "312909075212468632"
|
||||
},
|
||||
"user" : {
|
||||
"id" : "312909075212468632",
|
||||
"creation_date" : "2025-03-26T15:52:23.917636Z",
|
||||
"change_date" : "2025-03-26T15:52:23.917636Z",
|
||||
"resource_owner" : "312909075211944344",
|
||||
"sequence" : 2,
|
||||
"state" : 1,
|
||||
"username" : "[email protected]",
|
||||
"preferred_login_name" : "[email protected]",
|
||||
"human" : {
|
||||
"first_name" : "Example firstname",
|
||||
"last_name" : "Example lastname",
|
||||
"display_name" : "Example displayname",
|
||||
"preferred_language" : "en",
|
||||
"email" : "[email protected]",
|
||||
"is_email_verified" : true,
|
||||
"password_changed" : "0001-01-01T00:00:00Z",
|
||||
"mfa_init_skipped" : "0001-01-01T00:00:00Z"
|
||||
}
|
||||
},
|
||||
"user_metadata" : [ {
|
||||
"creation_date" : "2025-03-27T09:10:25.879677Z",
|
||||
"change_date" : "2025-03-27T09:10:25.879677Z",
|
||||
"resource_owner" : "312909075211944344",
|
||||
"sequence" : 18,
|
||||
"key" : "key",
|
||||
"value" : "dmFsdWU="
|
||||
} ],
|
||||
"org" : {
|
||||
"id" : "312909075211944344",
|
||||
"name" : "ZITADEL",
|
||||
"primary_domain" : "example.com"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
For any further information related to [the OIDC Flow, refer to our documentation.](/guides/integrate/login/oidc/login-users)
|
||||
|
||||
## Conclusion
|
||||
|
||||
You have successfully set up a target and execution to react to functions in your ZITADEL instance.
|
||||
This feature can now be used to customize the functionality in ZITADEL, in particular the content of the OIDC tokens and SAML responses.
|
||||
Find more information about the actions feature in the [API documentation](/concepts/features/actions_v2).
|
||||
@@ -0,0 +1,188 @@
|
||||
---
|
||||
title: Test Actions Request Manipulation
|
||||
---
|
||||
|
||||
This guide shows you how to leverage the ZITADEL actions feature to manipulate API requests in your ZITADEL instance.
|
||||
You can use the actions feature to create a target that will be called when a specific API request occurs.
|
||||
This is useful for adding information to managed resources in ZITADEL.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before you start, make sure you have everything set up correctly.
|
||||
|
||||
- You need to be at least a ZITADEL [_IAM_OWNER_](/guides/manage/console/managers)
|
||||
- Your ZITADEL instance needs to have the actions feature enabled.
|
||||
|
||||
:::info
|
||||
Note that this guide assumes that ZITADEL is running on the same machine as the target and can be reached via `localhost`.
|
||||
In case you are using a different setup, you need to adjust the target URL accordingly and will need to make sure that the target is reachable from ZITADEL.
|
||||
:::
|
||||
|
||||
## Start example target
|
||||
|
||||
To test the actions feature, you need to create a target that will be called when an API endpoint is called.
|
||||
You will need to implement a listener that can receive HTTP requests, process the request and returns the manipulated request.
|
||||
For this example, we will use a simple Go HTTP server that will return the request with added metadata.
|
||||
|
||||
:::info
|
||||
The signature of the received request can be checked, [please refer to the example for more information on how to](/guides/integrate/actions/testing-request-signature).
|
||||
:::
|
||||
|
||||
```go
|
||||
package main
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"io"
|
||||
"net/http"
|
||||
|
||||
"github.com/zitadel/zitadel/pkg/grpc/user/v2"
|
||||
)
|
||||
|
||||
type contextRequest struct {
|
||||
Request *user.AddHumanUserRequest `json:"request"`
|
||||
}
|
||||
|
||||
// call HandleFunc to read the request body, manipulate the content and return the manipulated request
|
||||
func call(w http.ResponseWriter, req *http.Request) {
|
||||
// read the body content
|
||||
sentBody, err := io.ReadAll(req.Body)
|
||||
if err != nil {
|
||||
// if there was an error while reading the body return an error
|
||||
http.Error(w, "error", http.StatusInternalServerError)
|
||||
return
|
||||
}
|
||||
defer req.Body.Close()
|
||||
|
||||
// read the request into the expected structure
|
||||
request := new(contextRequest)
|
||||
if err := json.Unmarshal(sentBody, request); err != nil {
|
||||
http.Error(w, "error", http.StatusInternalServerError)
|
||||
}
|
||||
|
||||
// build the response from the received request
|
||||
response := request.Request
|
||||
// manipulate the request to send back as response
|
||||
if response.Metadata == nil {
|
||||
response.Metadata = make([]*user.SetMetadataEntry, 0)
|
||||
}
|
||||
response.Metadata = append(response.Metadata, &user.SetMetadataEntry{Key: "organization", Value: []byte("company")})
|
||||
|
||||
// marshal the request into json
|
||||
data, err := json.Marshal(response)
|
||||
if err != nil {
|
||||
// if there was an error while marshalling the json
|
||||
http.Error(w, "error", http.StatusInternalServerError)
|
||||
return
|
||||
}
|
||||
|
||||
// return the manipulated request
|
||||
w.Write(data)
|
||||
}
|
||||
|
||||
func main() {
|
||||
// handle the HTTP call under "/call"
|
||||
http.HandleFunc("/call", call)
|
||||
|
||||
// start an HTTP server with the before defined function to handle the endpoint under "http://localhost:8090"
|
||||
http.ListenAndServe(":8090", nil)
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
## Create target
|
||||
|
||||
As you see in the example above the target is created with HTTP and port '8090' and if we want to use it as call, the target can be created as follows:
|
||||
|
||||
See [Create a target](/apis/resources/action_service_v2/action-service-create-target) for more detailed information.
|
||||
|
||||
```shell
|
||||
curl -L -X POST 'https://$CUSTOM-DOMAIN/v2beta/actions/targets' \
|
||||
-H 'Content-Type: application/json' \
|
||||
-H 'Accept: application/json' \
|
||||
-H 'Authorization: Bearer <TOKEN>' \
|
||||
--data-raw '{
|
||||
"name": "local call",
|
||||
"restCall": {
|
||||
"interruptOnError": true
|
||||
},
|
||||
"endpoint": "http://localhost:8090/call",
|
||||
"timeout": "10s"
|
||||
}'
|
||||
```
|
||||
|
||||
Save the returned ID to set in the execution.
|
||||
|
||||
## Set execution
|
||||
|
||||
To call the target just created before, with the intention to manipulate the request used for user creation by the user V2 API, we define an execution with a method condition.
|
||||
|
||||
See [Set an execution](/apis/resources/action_service_v2/action-service-set-execution) for more detailed information.
|
||||
|
||||
```shell
|
||||
curl -L -X PUT 'https://$CUSTOM-DOMAIN/v2beta/actions/executions' \
|
||||
-H 'Content-Type: application/json' \
|
||||
-H 'Accept: application/json' \
|
||||
-H 'Authorization: Bearer <TOKEN>' \
|
||||
--data-raw '{
|
||||
"condition": {
|
||||
"request": {
|
||||
"method": "/zitadel.user.v2.UserService/AddHumanUser"
|
||||
}
|
||||
},
|
||||
"targets": [
|
||||
{
|
||||
"target": "<TargetID returned>"
|
||||
}
|
||||
]
|
||||
}'
|
||||
```
|
||||
|
||||
## Example call
|
||||
|
||||
Now that you have set up the target and execution, you can test it by creating a user through the Console UI or
|
||||
by calling the ZITADEL API to create a human user.
|
||||
|
||||
```shell
|
||||
curl -L -X PUT 'https://$CUSTOM-DOMAIN/v2/users/human' \
|
||||
-H 'Content-Type: application/json' \
|
||||
-H 'Accept: application/json' \
|
||||
-H 'Authorization: Bearer <TOKEN>' \
|
||||
--data-raw '{
|
||||
"profile": {
|
||||
"givenName": "Example_given",
|
||||
"familyName": "Example_family"
|
||||
},
|
||||
"email": {
|
||||
"email": "[email protected]"
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
Your server should now manipulate the request to something like the following. Check out
|
||||
the [Sent information Request](./usage#sent-information-request) payload description.
|
||||
|
||||
```shell
|
||||
curl -L -X PUT 'https://$CUSTOM-DOMAIN/v2/users/human' \
|
||||
-H 'Content-Type: application/json' \
|
||||
-H 'Accept: application/json' \
|
||||
-H 'Authorization: Bearer <TOKEN>' \
|
||||
--data-raw '{
|
||||
"profile": {
|
||||
"givenName": "Example_given",
|
||||
"familyName": "Example_family"
|
||||
},
|
||||
"email": {
|
||||
"email": "[email protected]"
|
||||
}
|
||||
"metadata": [
|
||||
{"key": "organization", "value": "Y29tcGFueQ=="}
|
||||
]
|
||||
}'
|
||||
```
|
||||
|
||||
## Conclusion
|
||||
|
||||
You have successfully set up a target and execution to manipulate API requests in your ZITADEL instance.
|
||||
This feature can now be used to add or manipulate information to managed resources in ZITADEL.
|
||||
Find more information about the actions feature in the [API documentation](/concepts/features/actions_v2).
|
||||
@@ -0,0 +1,167 @@
|
||||
---
|
||||
title: Test Actions Request Signature Check
|
||||
---
|
||||
|
||||
This guide shows you how to leverage the ZITADEL actions feature to react to API requests in your ZITADEL instance.
|
||||
You can use the actions feature to create a target that will be called when a specific API request occurs.
|
||||
This is useful for information provisioning in between systems or for triggering workflows based on API requests in ZITADEL.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before you start, make sure you have everything set up correctly.
|
||||
|
||||
- You need to be at least a ZITADEL [_IAM_OWNER_](/guides/manage/console/managers)
|
||||
- Your ZITADEL instance needs to have the actions feature enabled.
|
||||
|
||||
:::info
|
||||
Note that this guide assumes that ZITADEL is running on the same machine as the target and can be reached via `localhost`.
|
||||
In case you are using a different setup, you need to adjust the target URL accordingly and will need to make sure that the target is reachable from ZITADEL.
|
||||
:::
|
||||
|
||||
## Start example target
|
||||
|
||||
To test the actions feature, you need to create a target that will be called when an API endpoint is called.
|
||||
You will need to implement a listener that can receive HTTP requests, check the signature and process the request.
|
||||
For this example, we will use a simple Go HTTP server that will print the received request to standard output.
|
||||
The 'signingKey' is the key received in the next step 'Create target'.
|
||||
|
||||
```go
|
||||
package main
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"io"
|
||||
"net/http"
|
||||
|
||||
"github.com/zitadel/zitadel/pkg/actions"
|
||||
)
|
||||
|
||||
const signingKey = "somekey"
|
||||
|
||||
// webhook HandleFunc to read the request body and then print out the contents
|
||||
func webhook(w http.ResponseWriter, req *http.Request) {
|
||||
// read the body content
|
||||
sentBody, err := io.ReadAll(req.Body)
|
||||
if err != nil {
|
||||
// if there was an error while reading the body return an error
|
||||
http.Error(w, "error", http.StatusInternalServerError)
|
||||
return
|
||||
}
|
||||
defer req.Body.Close()
|
||||
// validate signature
|
||||
if err := actions.ValidatePayload(sentBody, req.Header.Get(actions.SigningHeader), signingKey); err != nil {
|
||||
// if the signed content is not equal the sent content return an error
|
||||
http.Error(w, "error", http.StatusInternalServerError)
|
||||
return
|
||||
}
|
||||
// print out the read content
|
||||
fmt.Println(string(sentBody))
|
||||
}
|
||||
|
||||
func main() {
|
||||
// handle the HTTP call under "/webhook"
|
||||
http.HandleFunc("/webhook", webhook)
|
||||
|
||||
// start an HTTP server with the before defined function to handle the endpoint under "http://localhost:8090"
|
||||
http.ListenAndServe(":8090", nil)
|
||||
}
|
||||
```
|
||||
|
||||
## Create target
|
||||
|
||||
As you see in the example above the target is created with HTTP and port '8090' and if we want to use it as webhook, the target can be created as follows:
|
||||
|
||||
See [Create a target](/apis/resources/action_service_v2/action-service-create-target) for more detailed information.
|
||||
|
||||
```shell
|
||||
curl -L -X POST 'https://$CUSTOM-DOMAIN/v2beta/actions/targets' \
|
||||
-H 'Content-Type: application/json' \
|
||||
-H 'Accept: application/json' \
|
||||
-H 'Authorization: Bearer <TOKEN>' \
|
||||
--data-raw '{
|
||||
"name": "local webhook",
|
||||
"restWebhook": {
|
||||
"interruptOnError": true
|
||||
},
|
||||
"endpoint": "http://localhost:8090/webhook",
|
||||
"timeout": "10s"
|
||||
}'
|
||||
```
|
||||
|
||||
Save the returned ID to set in the execution.
|
||||
|
||||
## Set execution
|
||||
|
||||
To configure ZITADEL to call the target when an API endpoint is called, you need to set an execution and define the request
|
||||
condition.
|
||||
|
||||
See [Set an execution](/apis/resources/action_service_v2/action-service-set-execution) for more detailed information.
|
||||
|
||||
```shell
|
||||
curl -L -X PUT 'https://$CUSTOM-DOMAIN/v2beta/actions/executions' \
|
||||
-H 'Content-Type: application/json' \
|
||||
-H 'Accept: application/json' \
|
||||
-H 'Authorization: Bearer <TOKEN>' \
|
||||
--data-raw '{
|
||||
"condition": {
|
||||
"request": {
|
||||
"method": "/zitadel.user.v2.UserService/AddHumanUser"
|
||||
}
|
||||
},
|
||||
"targets": [
|
||||
{
|
||||
"target": "<TargetID returned>"
|
||||
}
|
||||
]
|
||||
}'
|
||||
```
|
||||
|
||||
## Example call
|
||||
|
||||
Now that you have set up the target and execution, you can test it by creating a user through the Console UI or
|
||||
by calling the ZITADEL API to create a human user.
|
||||
|
||||
```shell
|
||||
curl -L -X PUT 'https://$CUSTOM-DOMAIN/v2/users/human' \
|
||||
-H 'Content-Type: application/json' \
|
||||
-H 'Accept: application/json' \
|
||||
-H 'Authorization: Bearer <TOKEN>' \
|
||||
--data-raw '{
|
||||
"profile": {
|
||||
"givenName": "Example_given",
|
||||
"familyName": "Example_family"
|
||||
},
|
||||
"email": {
|
||||
"email": "[email protected]"
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
Your server should now print out something like the following. Check out
|
||||
the [Sent information Request](./usage#sent-information-request) payload description.
|
||||
|
||||
```shell
|
||||
{
|
||||
"fullMethod": "/zitadel.user.v2.UserService/AddHumanUser",
|
||||
"instanceID": "262851882718855632",
|
||||
"orgID": "262851882718921168",
|
||||
"projectID": "262851882719052240",
|
||||
"userID": "262851882718986704",
|
||||
"request": {
|
||||
"profile": {
|
||||
"given_name": "Example_given",
|
||||
"family_name": "Example_family"
|
||||
},
|
||||
"email": {
|
||||
"email": "[email protected]"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Conclusion
|
||||
|
||||
You have successfully set up a target and execution to react to API requests in your ZITADEL instance.
|
||||
This feature can now be used to provision information in between systems or for triggering workflows based on API requests in ZITADEL.
|
||||
Additionally, you are sure that the request was not tempered with, as the signature was created with the combination of signing key and payload.
|
||||
Find more information about the actions feature in the [API documentation](/concepts/features/actions_v2).
|
||||
@@ -0,0 +1,159 @@
|
||||
---
|
||||
title: Test Actions Request
|
||||
---
|
||||
|
||||
This guide shows you how to leverage the ZITADEL actions feature to react to API requests in your ZITADEL instance.
|
||||
You can use the actions feature to create a target that will be called when a specific API request occurs.
|
||||
This is useful for information provisioning in between systems or for triggering workflows based on API requests in ZITADEL.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before you start, make sure you have everything set up correctly.
|
||||
|
||||
- You need to be at least a ZITADEL [_IAM_OWNER_](/guides/manage/console/managers)
|
||||
- Your ZITADEL instance needs to have the actions feature enabled.
|
||||
|
||||
:::info
|
||||
Note that this guide assumes that ZITADEL is running on the same machine as the target and can be reached via `localhost`.
|
||||
In case you are using a different setup, you need to adjust the target URL accordingly and will need to make sure that the target is reachable from ZITADEL.
|
||||
:::
|
||||
|
||||
## Start example target
|
||||
|
||||
To test the actions feature, you need to create a target that will be called when an API endpoint is called.
|
||||
You will need to implement a listener that can receive HTTP requests and process the request.
|
||||
For this example, we will use a simple Go HTTP server that will print the received request to standard output.
|
||||
|
||||
:::info
|
||||
The signature of the received request can be checked, [please refer to the example for more information on how to](/guides/integrate/actions/testing-request-signature).
|
||||
:::
|
||||
|
||||
```go
|
||||
package main
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"io"
|
||||
"net/http"
|
||||
)
|
||||
|
||||
// webhook HandleFunc to read the request body and then print out the contents
|
||||
func webhook(w http.ResponseWriter, req *http.Request) {
|
||||
// read the body content
|
||||
sentBody, err := io.ReadAll(req.Body)
|
||||
if err != nil {
|
||||
// if there was an error while reading the body return an error
|
||||
http.Error(w, "error", http.StatusInternalServerError)
|
||||
return
|
||||
}
|
||||
defer req.Body.Close()
|
||||
// print out the read content
|
||||
fmt.Println(string(sentBody))
|
||||
}
|
||||
|
||||
func main() {
|
||||
// handle the HTTP call under "/webhook"
|
||||
http.HandleFunc("/webhook", webhook)
|
||||
|
||||
// start an HTTP server with the before defined function to handle the endpoint under "http://localhost:8090"
|
||||
http.ListenAndServe(":8090", nil)
|
||||
}
|
||||
```
|
||||
|
||||
## Create target
|
||||
|
||||
As you see in the example above the target is created with HTTP and port '8090' and if we want to use it as webhook, the target can be created as follows:
|
||||
|
||||
See [Create a target](/apis/resources/action_service_v2/action-service-create-target) for more detailed information.
|
||||
|
||||
```shell
|
||||
curl -L -X POST 'https://$CUSTOM-DOMAIN/v2beta/actions/targets' \
|
||||
-H 'Content-Type: application/json' \
|
||||
-H 'Accept: application/json' \
|
||||
-H 'Authorization: Bearer <TOKEN>' \
|
||||
--data-raw '{
|
||||
"name": "local webhook",
|
||||
"restWebhook": {
|
||||
"interruptOnError": true
|
||||
},
|
||||
"endpoint": "http://localhost:8090/webhook",
|
||||
"timeout": "10s"
|
||||
}'
|
||||
```
|
||||
|
||||
Save the returned ID to set in the execution.
|
||||
|
||||
## Set execution
|
||||
|
||||
To configure ZITADEL to call the target when an API endpoint is called, you need to set an execution and define the request
|
||||
condition.
|
||||
|
||||
See [Set an execution](/apis/resources/action_service_v2/action-service-set-execution) for more detailed information.
|
||||
|
||||
```shell
|
||||
curl -L -X PUT 'https://$CUSTOM-DOMAIN/v2beta/actions/executions' \
|
||||
-H 'Content-Type: application/json' \
|
||||
-H 'Accept: application/json' \
|
||||
-H 'Authorization: Bearer <TOKEN>' \
|
||||
--data-raw '{
|
||||
"condition": {
|
||||
"request": {
|
||||
"method": "/zitadel.user.v2.UserService/AddHumanUser"
|
||||
}
|
||||
},
|
||||
"targets": [
|
||||
{
|
||||
"target": "<TargetID returned>"
|
||||
}
|
||||
]
|
||||
}'
|
||||
```
|
||||
|
||||
## Example call
|
||||
|
||||
Now that you have set up the target and execution, you can test it by creating a user through the Console UI or
|
||||
by calling the ZITADEL API to create a human user.
|
||||
|
||||
```shell
|
||||
curl -L -X PUT 'https://$CUSTOM-DOMAIN/v2/users/human' \
|
||||
-H 'Content-Type: application/json' \
|
||||
-H 'Accept: application/json' \
|
||||
-H 'Authorization: Bearer <TOKEN>' \
|
||||
--data-raw '{
|
||||
"profile": {
|
||||
"givenName": "Test",
|
||||
"familyName": "User"
|
||||
},
|
||||
"email": {
|
||||
"email": "[email protected]"
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
Your server should now print out something like the following. Check out
|
||||
the [Sent information Request](./usage#sent-information-request) payload description.
|
||||
|
||||
```shell
|
||||
{
|
||||
"fullMethod": "/zitadel.user.v2.UserService/AddHumanUser",
|
||||
"instanceID": "262851882718855632",
|
||||
"orgID": "262851882718921168",
|
||||
"projectID": "262851882719052240",
|
||||
"userID": "262851882718986704",
|
||||
"request": {
|
||||
"profile": {
|
||||
"given_name": "Test",
|
||||
"family_name": "User"
|
||||
},
|
||||
"email": {
|
||||
"email": "[email protected]"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Conclusion
|
||||
|
||||
You have successfully set up a target and execution to react to API requests in your ZITADEL instance.
|
||||
This feature can now be used to provision information in between systems or for triggering workflows based on API requests in ZITADEL.
|
||||
Find more information about the actions feature in the [API documentation](/concepts/features/actions_v2).
|
||||
@@ -0,0 +1,254 @@
|
||||
---
|
||||
title: Test Actions Response Manipulation
|
||||
---
|
||||
|
||||
This guide shows you how to leverage the ZITADEL actions feature to manipulate API responses in your ZITADEL instance.
|
||||
You can use the actions feature to create a target that will be called when a specific API response occurs.
|
||||
This is useful for triggering workflows based on API responses in ZITADEL. You can even use this to provide data necessary data to the new login UI as shown in this example.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before you start, make sure you have everything set up correctly.
|
||||
|
||||
- You need to be at least a ZITADEL [_IAM_OWNER_](/guides/manage/console/managers)
|
||||
- Your ZITADEL instance needs to have the actions feature enabled.
|
||||
|
||||
:::info
|
||||
Note that this guide assumes that ZITADEL is running on the same machine as the target and can be reached via `localhost`.
|
||||
In case you are using a different setup, you need to adjust the target URL accordingly and will need to make sure that the target is reachable from ZITADEL.
|
||||
:::
|
||||
|
||||
## Start example target
|
||||
|
||||
To test the actions feature, you need to create a target that will be called when an API endpoint is called.
|
||||
You will need to implement a listener that can receive HTTP requests, process the request and returns the manipulated request.
|
||||
For this example, we will use a simple Go HTTP server that will return the request with added metadata.
|
||||
|
||||
:::info
|
||||
The signature of the received request can be checked, [please refer to the example for more information on how to](/guides/integrate/actions/testing-request-signature).
|
||||
:::
|
||||
|
||||
```go
|
||||
package main
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"io"
|
||||
"net/http"
|
||||
|
||||
"github.com/zitadel/zitadel/pkg/grpc/user/v2"
|
||||
)
|
||||
|
||||
type response struct {
|
||||
Request *user.RetrieveIdentityProviderIntentRequest `json:"request"`
|
||||
Response *user.RetrieveIdentityProviderIntentResponse `json:"response"`
|
||||
}
|
||||
|
||||
// call HandleFunc to read the response body, manipulate the content and return the response
|
||||
func call(w http.ResponseWriter, req *http.Request) {
|
||||
// read the body content
|
||||
sentBody, err := io.ReadAll(req.Body)
|
||||
if err != nil {
|
||||
// if there was an error while reading the body return an error
|
||||
http.Error(w, "error", http.StatusInternalServerError)
|
||||
return
|
||||
}
|
||||
defer req.Body.Close()
|
||||
|
||||
// read the response into the expected structure
|
||||
request := new(response)
|
||||
if err := json.Unmarshal(sentBody, request); err != nil {
|
||||
http.Error(w, "error", http.StatusInternalServerError)
|
||||
}
|
||||
|
||||
// build the response from the received response
|
||||
resp := request.Response
|
||||
// manipulate the received response to send back as response
|
||||
if resp != nil && resp.AddHumanUser != nil {
|
||||
// manipulate the response
|
||||
resp.AddHumanUser.Metadata = append(resp.AddHumanUser.Metadata, &user.SetMetadataEntry{Key: "organization", Value: []byte("company")})
|
||||
}
|
||||
|
||||
// marshal the response into json
|
||||
data, err := json.Marshal(resp)
|
||||
if err != nil {
|
||||
// if there was an error while marshalling the json
|
||||
http.Error(w, "error", http.StatusInternalServerError)
|
||||
return
|
||||
}
|
||||
|
||||
// return the manipulated response
|
||||
w.Write(data)
|
||||
}
|
||||
|
||||
func main() {
|
||||
// handle the HTTP call under "/call"
|
||||
http.HandleFunc("/call", call)
|
||||
|
||||
// start an HTTP server with the before defined function to handle the endpoint under "http://localhost:8090"
|
||||
http.ListenAndServe(":8090", nil)
|
||||
}
|
||||
```
|
||||
|
||||
## Create target
|
||||
|
||||
As you see in the example above the target is created with HTTP and port '8090' and if we want to use it as call, the
|
||||
target can be created as follows:
|
||||
|
||||
See [Create a target](/apis/resources/action_service_v2/action-service-create-target) for more detailed information.
|
||||
|
||||
```shell
|
||||
curl -L -X POST 'https://$CUSTOM-DOMAIN/v2beta/actions/targets' \
|
||||
-H 'Content-Type: application/json' \
|
||||
-H 'Accept: application/json' \
|
||||
-H 'Authorization: Bearer <TOKEN>' \
|
||||
--data-raw '{
|
||||
"name": "local call",
|
||||
"restCall": {
|
||||
"interruptOnError": true
|
||||
},
|
||||
"endpoint": "http://localhost:8090/call",
|
||||
"timeout": "10s"
|
||||
}'
|
||||
```
|
||||
|
||||
Save the returned ID to set in the execution.
|
||||
|
||||
## Set execution
|
||||
|
||||
To call the target just created before, with the intention to manipulate the retrieve of an intent by the user V2 API,
|
||||
we define an execution with a response condition.
|
||||
|
||||
See [Set an execution](/apis/resources/action_service_v2/action-service-set-execution) for more detailed information.
|
||||
|
||||
```shell
|
||||
curl -L -X PUT 'https://$CUSTOM-DOMAIN/v2beta/actions/executions' \
|
||||
-H 'Content-Type: application/json' \
|
||||
-H 'Accept: application/json' \
|
||||
-H 'Authorization: Bearer <TOKEN>' \
|
||||
--data-raw '{
|
||||
"condition": {
|
||||
"response": {
|
||||
"method": "/zitadel.user.v2.UserService/RetrieveIdentityProviderIntent"
|
||||
}
|
||||
},
|
||||
"targets": [
|
||||
{
|
||||
"target": "<TargetID returned>"
|
||||
}
|
||||
]
|
||||
}'
|
||||
```
|
||||
|
||||
## Example call
|
||||
|
||||
Now that you have set up the target and execution, you can test it by using a login-flow in the typescript login with an external IDP.
|
||||
|
||||
```json
|
||||
{
|
||||
"details": {
|
||||
"sequence": "599",
|
||||
"changeDate": "2023-06-15T06:44:26.039444Z",
|
||||
"resourceOwner": "163840776835432705"
|
||||
},
|
||||
"idpInformation": {
|
||||
"oauth": {
|
||||
"accessToken": "ya29...",
|
||||
"idToken": "ey..."
|
||||
},
|
||||
"idpId": "218528353504723201",
|
||||
"userId": "218528353504723202",
|
||||
"username": "test-user@localhost",
|
||||
"rawInformation": {
|
||||
"User": {
|
||||
"email": "test-user@localhost",
|
||||
"email_verified": true,
|
||||
"family_name": "User",
|
||||
"given_name": "Test",
|
||||
"hd": "mouse.com",
|
||||
"locale": "de",
|
||||
"name": "Minnie Mouse",
|
||||
"picture": "https://lh3.googleusercontent.com/a/AAcKTtf973Q7NH8KzKTMEZELPU9lx45WpQ9FRBuxFdPb=s96-c",
|
||||
"sub": "111392805975715856637"
|
||||
}
|
||||
}
|
||||
},
|
||||
"addHumanUser": {
|
||||
"idpLinks": [
|
||||
{"idpId": "218528353504723201", "userId": "218528353504723202", "userName": "test-user@localhost"}
|
||||
],
|
||||
"username": "test-user@localhost",
|
||||
"profile": {
|
||||
"givenName": "Test",
|
||||
"familyName": "User",
|
||||
"displayName": "Test User",
|
||||
"preferredLanguage": "de"
|
||||
},
|
||||
"email": {
|
||||
"email": "[email protected]",
|
||||
"isVerified": true
|
||||
},
|
||||
"metadata": []
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Your server should now manipulate the response to something like the following. Check out
|
||||
the [Sent information Response](./usage#sent-information-response) payload description.
|
||||
|
||||
```json
|
||||
{
|
||||
"details": {
|
||||
"sequence": "599",
|
||||
"changeDate": "2023-06-15T06:44:26.039444Z",
|
||||
"resourceOwner": "163840776835432705"
|
||||
},
|
||||
"idpInformation": {
|
||||
"oauth": {
|
||||
"accessToken": "ya29...",
|
||||
"idToken": "ey..."
|
||||
},
|
||||
"idpId": "218528353504723201",
|
||||
"userId": "218528353504723202",
|
||||
"username": "test-user@localhost",
|
||||
"rawInformation": {
|
||||
"User": {
|
||||
"email": "test-user@localhost",
|
||||
"email_verified": true,
|
||||
"family_name": "User",
|
||||
"given_name": "Test",
|
||||
"hd": "mouse.com",
|
||||
"locale": "de",
|
||||
"name": "Minnie Mouse",
|
||||
"picture": "https://lh3.googleusercontent.com/a/AAcKTtf973Q7NH8KzKTMEZELPU9lx45WpQ9FRBuxFdPb=s96-c",
|
||||
"sub": "111392805975715856637"
|
||||
}
|
||||
}
|
||||
},
|
||||
"addHumanUser": {
|
||||
"idpLinks": [
|
||||
{"idpId": "218528353504723201", "userId": "218528353504723202", "userName": "test-user@localhost"}
|
||||
],
|
||||
"username": "test-user@localhost",
|
||||
"profile": {
|
||||
"givenName": "Test",
|
||||
"familyName": "User",
|
||||
"displayName": "Test User",
|
||||
"preferredLanguage": "de"
|
||||
},
|
||||
"email": {
|
||||
"email": "[email protected]",
|
||||
"isVerified": true
|
||||
},
|
||||
"metadata": [
|
||||
{"key": "organization", "value": "Y29tcGFueQ=="}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Conclusion
|
||||
|
||||
You have successfully set up a target and execution to manipulate API responses in your ZITADEL instance.
|
||||
This feature can now be used to add necessary information for clients including the new login UI.
|
||||
Find more information about the actions feature in the [API documentation](/concepts/features/actions_v2).
|
||||
@@ -0,0 +1,167 @@
|
||||
---
|
||||
title: Test Actions Response
|
||||
---
|
||||
|
||||
This guide shows you how to leverage the ZITADEL actions feature to react to API responses in your ZITADEL instance.
|
||||
You can use the actions feature to create a target that will be called when a specific API response occurs.
|
||||
This is useful for information provisioning in between systems or for triggering workflows based on API responses in ZITADEL.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before you start, make sure you have everything set up correctly.
|
||||
|
||||
- You need to be at least a ZITADEL [_IAM_OWNER_](/guides/manage/console/managers)
|
||||
- Your ZITADEL instance needs to have the actions feature enabled.
|
||||
|
||||
:::info
|
||||
Note that this guide assumes that ZITADEL is running on the same machine as the target and can be reached via `localhost`.
|
||||
In case you are using a different setup, you need to adjust the target URL accordingly and will need to make sure that the target is reachable from ZITADEL.
|
||||
:::
|
||||
|
||||
## Start example target
|
||||
|
||||
To test the actions feature, you need to create a target that will be called when an API endpoint is called.
|
||||
You will need to implement a listener that can receive HTTP requests and process the request.
|
||||
For this example, we will use a simple Go HTTP server that will print the received request to standard output.
|
||||
|
||||
:::info
|
||||
The signature of the received request can be checked, [please refer to the example for more information on how to](/guides/integrate/actions/testing-request-signature).
|
||||
:::
|
||||
|
||||
```go
|
||||
package main
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"io"
|
||||
"net/http"
|
||||
)
|
||||
|
||||
// webhook HandleFunc to read the request body and then print out the contents
|
||||
func webhook(w http.ResponseWriter, req *http.Request) {
|
||||
// read the body content
|
||||
sentBody, err := io.ReadAll(req.Body)
|
||||
if err != nil {
|
||||
// if there was an error while reading the body return an error
|
||||
http.Error(w, "error", http.StatusInternalServerError)
|
||||
return
|
||||
}
|
||||
defer req.Body.Close()
|
||||
// print out the read content
|
||||
fmt.Println(string(sentBody))
|
||||
}
|
||||
|
||||
func main() {
|
||||
// handle the HTTP call under "/webhook"
|
||||
http.HandleFunc("/webhook", webhook)
|
||||
|
||||
// start an HTTP server with the before defined function to handle the endpoint under "http://localhost:8090"
|
||||
http.ListenAndServe(":8090", nil)
|
||||
}
|
||||
```
|
||||
|
||||
## Create target
|
||||
|
||||
As you see in the example above the target is created with HTTP and port '8090' and if we want to use it as webhook, the target can be created as follows:
|
||||
|
||||
See [Create a target](/apis/resources/action_service_v2/action-service-create-target) for more detailed information.
|
||||
|
||||
```shell
|
||||
curl -L -X POST 'https://$CUSTOM-DOMAIN/v2beta/actions/targets' \
|
||||
-H 'Content-Type: application/json' \
|
||||
-H 'Accept: application/json' \
|
||||
-H 'Authorization: Bearer <TOKEN>' \
|
||||
--data-raw '{
|
||||
"name": "local webhook",
|
||||
"restWebhook": {
|
||||
"interruptOnError": true
|
||||
},
|
||||
"endpoint": "http://localhost:8090/webhook",
|
||||
"timeout": "10s"
|
||||
}'
|
||||
```
|
||||
|
||||
Save the returned ID to set in the execution.
|
||||
|
||||
## Set execution
|
||||
|
||||
To configure Zitadel to call the target when an API endpoint is called, you need to set an execution and define the response
|
||||
condition.
|
||||
|
||||
See [Set an execution](/apis/resources/action_service_v2/action-service-set-execution) for more detailed information.
|
||||
|
||||
```shell
|
||||
curl -L -X PUT 'https://$CUSTOM-DOMAIN/v2beta/actions/executions' \
|
||||
-H 'Content-Type: application/json' \
|
||||
-H 'Accept: application/json' \
|
||||
-H 'Authorization: Bearer <TOKEN>' \
|
||||
--data-raw '{
|
||||
"condition": {
|
||||
"response": {
|
||||
"method": "/zitadel.user.v2.UserService/AddHumanUser"
|
||||
}
|
||||
},
|
||||
"targets": [
|
||||
{
|
||||
"target": "<TargetID returned>"
|
||||
}
|
||||
]
|
||||
}'
|
||||
```
|
||||
|
||||
## Example call
|
||||
|
||||
Now that you have set up the target and execution, you can test it by creating a user through the Console UI or
|
||||
by calling the ZITADEL API to create a human user.
|
||||
|
||||
```shell
|
||||
curl -L -X PUT 'https://$CUSTOM-DOMAIN/v2/users/human' \
|
||||
-H 'Content-Type: application/json' \
|
||||
-H 'Accept: application/json' \
|
||||
-H 'Authorization: Bearer <TOKEN>' \
|
||||
--data-raw '{
|
||||
"userId": {
|
||||
"givenName": "Example_given",
|
||||
"familyName": "Example_family"
|
||||
},
|
||||
"email": {
|
||||
"email": "[email protected]"
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
Your server should now print out something like the following. Check out
|
||||
the [Sent information Response](./usage#sent-information-response) payload description.
|
||||
|
||||
```json
|
||||
{
|
||||
"fullMethod": "/zitadel.user.v2.UserService/AddHumanUser",
|
||||
"instanceID": "262851882718855632",
|
||||
"orgID": "262851882718921168",
|
||||
"projectID": "262851882719052240",
|
||||
"userID": "262851882718986704",
|
||||
"request": {
|
||||
"profile": {
|
||||
"given_name": "Example_given",
|
||||
"family_name": "Example_family"
|
||||
},
|
||||
"email": {
|
||||
"email": "[email protected]"
|
||||
}
|
||||
},
|
||||
"response": {
|
||||
"user_id": "312918757460672920",
|
||||
"details": {
|
||||
"sequence": "2",
|
||||
"change_date": "2025-03-26T17:28:33.856436Z",
|
||||
"resource_owner": "312909075211944344",
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Conclusion
|
||||
|
||||
You have successfully set up a target and execution to react to API responses in your ZITADEL instance.
|
||||
This feature can now be used to provision information in between systems or for triggering workflows based on API responses in ZITADEL.
|
||||
Find more information about the actions feature in the [API documentation](/concepts/features/actions_v2).
|
||||
@@ -0,0 +1,492 @@
|
||||
---
|
||||
title: Using Actions
|
||||
---
|
||||
|
||||
The Action API provides a flexible mechanism for customizing and extending the functionality of ZITADEL. By allowing you to define targets and executions, you can implement custom workflows triggered on an API requests and responses, events or specific functions.
|
||||
|
||||
**How it works:**
|
||||
- Create Target
|
||||
- Set Execution with condition and target
|
||||
- Custom Code will be triggered and executed
|
||||
|
||||
**Use Cases:**
|
||||
- User Management: Automate provisioning user data to external systems when users are crreated, updated or deleted.
|
||||
- Security: Implement IP blocking or rate limiting based on API usage patterns.
|
||||
- Extend Workflows: Automatically setup resources in your application, when a new organization in ZITADEL is created.
|
||||
- Token extension: Add custom claims to the tokens.
|
||||
|
||||
## Endpoints
|
||||
|
||||
ZITADEL sends an HTTP Post request to the endpoint set as Target, the received request than can be edited and send back or custom processes can be handled.
|
||||
|
||||
### Sent information Request
|
||||
|
||||
The information sent to the Endpoint is structured as JSON:
|
||||
|
||||
```json
|
||||
{
|
||||
"fullMethod": "full method of the GRPC call",
|
||||
"instanceID": "instanceID of the called instance",
|
||||
"orgID": "ID of the organization related to the calling context",
|
||||
"projectID": "ID of the project related to the used application",
|
||||
"userID": "ID of the calling user",
|
||||
"request": {
|
||||
"attribute": "Attribute value of full request of the call"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Sent information Response
|
||||
|
||||
The information sent to the Endpoint is structured as JSON:
|
||||
|
||||
```json
|
||||
{
|
||||
"fullMethod": "full method of the GRPC call",
|
||||
"instanceID": "instanceID of the called instance",
|
||||
"orgID": "ID of the organization related to the calling context",
|
||||
"projectID": "ID of the project related to the used application",
|
||||
"userID": "ID of the calling user",
|
||||
"request": {
|
||||
"attribute": "Attribute value of full request of the call"
|
||||
},
|
||||
"response": {
|
||||
"attribute": "Attribute value of full response of the call"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Sent information Function
|
||||
|
||||
Information sent and expected back are specific to the function.
|
||||
|
||||
#### PreUserinfo
|
||||
|
||||
The information sent to the Endpoint is structured as JSON:
|
||||
```json
|
||||
{
|
||||
"function": "Name of the function",
|
||||
"userinfo": {
|
||||
"given_name": "",
|
||||
"family_name": "",
|
||||
"middle_name": "",
|
||||
"nickname": "",
|
||||
"profile": "",
|
||||
"picture": "",
|
||||
...
|
||||
"preferred_username": "",
|
||||
"email": "",
|
||||
"email_verified": true,
|
||||
"phone_number": "",
|
||||
"phone_number_verified": true
|
||||
},
|
||||
"user": {
|
||||
"id": "",
|
||||
"creation_date": "",
|
||||
...
|
||||
"human": {
|
||||
"first_name": "",
|
||||
"last_name": "",
|
||||
...
|
||||
"email": "",
|
||||
"is_email_verified": true,
|
||||
"phone": "",
|
||||
"is_phone_verified": true
|
||||
}
|
||||
},
|
||||
"user_metadata": [
|
||||
{
|
||||
"creation_date": "",
|
||||
"change_date": "",
|
||||
"resource_owner": "",
|
||||
"sequence": "",
|
||||
"key": "",
|
||||
"value": ""
|
||||
}
|
||||
],
|
||||
"org": {
|
||||
"id": "ID of the organization the user belongs to",
|
||||
"name": "Name of the organization the user belongs to",
|
||||
"primary_domain": "Primary domain of the organization the user belongs to"
|
||||
},
|
||||
"user_grants": [
|
||||
{
|
||||
"id": "",
|
||||
"projectGrantId": "The ID of the project grant",
|
||||
"state": 1,
|
||||
"creationDate": "",
|
||||
"changeDate": "",
|
||||
"sequence": 1,
|
||||
"userId": "",
|
||||
"roles": [
|
||||
"role"
|
||||
],
|
||||
"userResourceOwner": "The ID of the organization the user belongs to",
|
||||
"userGrantResourceOwner": "The ID of the organization the user got authorization granted",
|
||||
"userGrantResourceOwnerName": "The name of the organization the user got authorization granted",
|
||||
"projectId": "",
|
||||
"projectName": ""
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
The expected structure of the JSON as response:
|
||||
|
||||
```json
|
||||
{
|
||||
"set_user_metadata": [
|
||||
{
|
||||
"key": "key of metadata to be set on the user",
|
||||
"value": "base64 value of metadata to be set on the user"
|
||||
}
|
||||
],
|
||||
"append_claims": [
|
||||
{
|
||||
"key": "key of claim to be set on the user",
|
||||
"value": "value of claim to be set on the user"
|
||||
}
|
||||
],
|
||||
"append_log_claims": [
|
||||
"Log to be appended to the log claim on the token"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### PreAccessToken
|
||||
|
||||
The information sent to the Endpoint is structured as JSON:
|
||||
|
||||
```json
|
||||
{
|
||||
"function": "Name of the function",
|
||||
"userinfo": {
|
||||
"given_name": "",
|
||||
"family_name": "",
|
||||
"middle_name": "",
|
||||
"nickname": "",
|
||||
"profile": "",
|
||||
"picture": "",
|
||||
...
|
||||
"preferred_username": "",
|
||||
"email": "",
|
||||
"email_verified": true/false,
|
||||
"phone_number": "",
|
||||
"phone_number_verified": true/false
|
||||
},
|
||||
"user": {
|
||||
"id": "",
|
||||
"creation_date": "",
|
||||
...
|
||||
"human": {
|
||||
"first_name": "",
|
||||
"last_name": "",
|
||||
...
|
||||
"email": "",
|
||||
"is_email_verified": true,
|
||||
"phone": "",
|
||||
"is_phone_verified": true
|
||||
}
|
||||
},
|
||||
"user_metadata": [
|
||||
{
|
||||
"creation_date": "",
|
||||
"change_date": "",
|
||||
"resource_owner": "",
|
||||
"sequence": "",
|
||||
"key": "",
|
||||
"value": ""
|
||||
}
|
||||
],
|
||||
"org": {
|
||||
"id": "ID of the organization the user belongs to",
|
||||
"name": "Name of the organization the user belongs to",
|
||||
"primary_domain": "Primary domain of the organization the user belongs to"
|
||||
},
|
||||
"user_grants": [
|
||||
{
|
||||
"id": "",
|
||||
"projectGrantId": "The ID of the project grant",
|
||||
"state": 1,
|
||||
"creationDate": "",
|
||||
"changeDate": "",
|
||||
"sequence": 1,
|
||||
"userId": "",
|
||||
"roles": [
|
||||
"role"
|
||||
],
|
||||
"userResourceOwner": "The ID of the organization the user belongs to",
|
||||
"userGrantResourceOwner": "The ID of the organization the user got authorization granted",
|
||||
"userGrantResourceOwnerName": "The name of the organization the user got authorization granted",
|
||||
"projectId": "",
|
||||
"projectName": ""
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
The expected structure of the JSON as response:
|
||||
|
||||
```json
|
||||
{
|
||||
"set_user_metadata": [
|
||||
{
|
||||
"key": "key of metadata to be set on the user",
|
||||
"value": "base64 value of metadata to be set on the user"
|
||||
}
|
||||
],
|
||||
"append_claims": [
|
||||
{
|
||||
"key": "key of claim to be set on the user",
|
||||
"value": "value of claim to be set on the user"
|
||||
}
|
||||
],
|
||||
"append_log_claims": [
|
||||
"Log to be appended to the log claim on the token"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### PreSAMLResponse
|
||||
|
||||
The information sent to the Endpoint is structured as JSON:
|
||||
```json
|
||||
{
|
||||
"function": "Name of the function",
|
||||
"userinfo": {
|
||||
"given_name": "",
|
||||
"family_name": "",
|
||||
"middle_name": "",
|
||||
"nickname": "",
|
||||
"profile": "",
|
||||
"picture": "",
|
||||
...
|
||||
"preferred_username": "",
|
||||
"email": "",
|
||||
"email_verified": true,
|
||||
"phone_number": "",
|
||||
"phone_number_verified": true
|
||||
},
|
||||
"user": {
|
||||
"id": "",
|
||||
"creation_date": "",
|
||||
...
|
||||
"human": {
|
||||
"first_name": "",
|
||||
"last_name": "",
|
||||
...
|
||||
"email": "",
|
||||
"is_email_verified": true,
|
||||
"phone": "",
|
||||
"is_phone_verified": true
|
||||
}
|
||||
},
|
||||
"user_grants": [
|
||||
{
|
||||
"id": "",
|
||||
"projectGrantId": "The ID of the project grant",
|
||||
"state": 1,
|
||||
"creationDate": "",
|
||||
"changeDate": "",
|
||||
"sequence": 1,
|
||||
"userId": "",
|
||||
"roles": [
|
||||
"role"
|
||||
],
|
||||
"userResourceOwner": "The ID of the organization the user belongs to",
|
||||
"userGrantResourceOwner": "The ID of the organization the user got authorization granted",
|
||||
"userGrantResourceOwnerName": "The name of the organization the user got authorization granted",
|
||||
"projectId": "",
|
||||
"projectName": ""
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
The expected structure of the JSON as response:
|
||||
|
||||
```json
|
||||
{
|
||||
"set_user_metadata": [
|
||||
{
|
||||
"key": "key of metadata to be set on the user",
|
||||
"value": "base64 value of metadata to be set on the user"
|
||||
}
|
||||
],
|
||||
"append_attribute": [
|
||||
{
|
||||
"name": "name of the attribute to be added to the response",
|
||||
"name_format": "name format of the attribute to be added to the response",
|
||||
"value": "value of the attribute to be added to the response"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Sent information Event
|
||||
|
||||
The information sent to the Endpoint is structured as JSON:
|
||||
|
||||
```json
|
||||
{
|
||||
"aggregateID": "ID of the aggregate",
|
||||
"aggregateType": "Type of the aggregate",
|
||||
"resourceOwner": "Resourceowner the aggregate belongs to",
|
||||
"instanceID": "ID of the instance the aggregate belongs to",
|
||||
"version": "Version of the aggregate",
|
||||
"sequence": "Sequence of the event",
|
||||
"event_type": "Type of the event",
|
||||
"created_at": "Time the event was created",
|
||||
"userID": "ID of the creator of the event",
|
||||
"event_payload": "Base64 encoded content of the event"
|
||||
}
|
||||
```
|
||||
|
||||
## Target
|
||||
|
||||
The Target describes how ZITADEL interacts with the Endpoint.
|
||||
|
||||
There are different types of Targets:
|
||||
|
||||
- `Webhook`, the call handles the status code but response is irrelevant, can be InterruptOnError
|
||||
- `Call`, the call handles the status code and response, can be InterruptOnError
|
||||
- `Async`, the call handles neither status code nor response, but can be called in parallel with other Targets
|
||||
|
||||
`InterruptOnError` means that the Execution gets interrupted if any of the calls return with a status code >= 400, and the next Target will not be called anymore.
|
||||
|
||||
The API documentation to create a target can be found [here](/apis/resources/action_service_v2/action-service-create-target)
|
||||
|
||||
### Content Signing
|
||||
|
||||
To ensure the integrity of request content, each call includes a 'ZITADEL-Signature' in the headers. This header contains an HMAC value computed from the request content and a timestamp, which can be used to time out requests. The logic for this process is provided in 'pkg/actions/signing.go'. The goal is to verify that the HMAC value in the header matches the HMAC value computed by the Target, ensuring that the sent and received requests are identical.
|
||||
|
||||
Each Target resource now contains also a Signing Key, which gets generated and returned when a Target is [created](/apis/resources/action_service_v2/action-service-create-target),
|
||||
and can also be newly generated when a Target is [patched](/apis/resources/action_service_v2/action-service-patch-target).
|
||||
|
||||
For an example on how to check the signature, [refer to the example](/guides/integrate/actions/testing-request-signature).
|
||||
|
||||
## Execution
|
||||
|
||||
ZITADEL decides on specific conditions if one or more Targets have to be called.
|
||||
The Execution resource contains 2 parts, the condition and the called targets.
|
||||
|
||||
The condition can be defined for 4 types of processes:
|
||||
|
||||
- `Requests`, before a request is processed by ZITADEL
|
||||
- `Responses`, before a response is sent back to the application
|
||||
- `Functions`, handling specific functionality in the logic of ZITADEL
|
||||
- `Events`, after a specific event happened and was stored in ZITADEL
|
||||
|
||||
The API documentation to set an Execution can be found [here](/apis/resources/action_service_v2/action-service-set-execution)
|
||||
|
||||
### Condition Best Match
|
||||
|
||||
As the conditions can be defined on different levels, ZITADEL tries to find out which Execution is the best match.
|
||||
This means that for example if you have an Execution defined on `all requests`, on the service `zitadel.user.v2.UserService` and on `/zitadel.user.v2.UserService/AddHumanUser`,
|
||||
ZITADEL would with a call on the `/zitadel.user.v2.UserService/AddHumanUser` use the Executions with the following priority:
|
||||
|
||||
1. `/zitadel.user.v2.UserService/AddHumanUser`
|
||||
2. `zitadel.user.v2.UserService`
|
||||
3. `all`
|
||||
|
||||
If you then have a call on `/zitadel.user.v2.UserService/UpdateHumanUser` the following priority would be found:
|
||||
|
||||
1. `zitadel.user.v2.UserService`
|
||||
2. `all`
|
||||
|
||||
And if you use a different service, for example `zitadel.session.v2.SessionService`, then the `all` Execution would still be used.
|
||||
|
||||
### Targets and Includes
|
||||
|
||||
:::info
|
||||
Includes are limited to 3 levels, which mean that include1->include2->include3 is the maximum for now.
|
||||
If you have feedback to the include logic, or a reason why 3 levels are not enough, please open [an issue on github](https://github.com/zitadel/zitadel/issues) or [start a discussion on github](https://github.com/zitadel/zitadel/discussions)/[start a topic on discord](https://zitadel.com/chat)
|
||||
:::
|
||||
|
||||
An execution can not only contain a list of Targets, but also Includes.
|
||||
The Includes can be defined in the Execution directly, which means you include all defined Targets by a before set Execution.
|
||||
|
||||
If you define 2 Executions as follows:
|
||||
|
||||
```json
|
||||
{
|
||||
"condition": {
|
||||
"request": {
|
||||
"service": "zitadel.user.v2.UserService"
|
||||
}
|
||||
},
|
||||
"targets": [
|
||||
{
|
||||
"target": "<TargetID1>"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"condition": {
|
||||
"request": {
|
||||
"method": "/zitadel.user.v2.UserService/AddHumanUser"
|
||||
}
|
||||
},
|
||||
"targets": [
|
||||
{
|
||||
"target": "<TargetID2>"
|
||||
},
|
||||
{
|
||||
"include": {
|
||||
"request": {
|
||||
"service": "zitadel.user.v2.UserService"
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
The called Targets on "/zitadel.user.v2.UserService/AddHumanUser" would be, in order:
|
||||
|
||||
1. `<TargetID2>`
|
||||
2. `<TargetID1>`
|
||||
|
||||
### Condition for Requests and Responses
|
||||
|
||||
For Request and Response there are 3 levels the condition can be defined:
|
||||
|
||||
- `Method`, handling a request or response of a specific GRPC full method, which includes the service name and method of the ZITADEL API
|
||||
- `Service`, handling any request or response under a service of the ZITADEL API
|
||||
- `All`, handling any request or response under the ZITADEL API
|
||||
|
||||
The available conditions can be found under:
|
||||
- [All available Methods](/apis/resources/action_service_v2/action-service-list-execution-methods), for example `/zitadel.user.v2.UserService/AddHumanUser`
|
||||
- [All available Services](/apis/resources/action_service_v2/action-service-list-execution-services), for example `zitadel.user.v2.UserService`
|
||||
|
||||
### Condition for Functions
|
||||
|
||||
The available conditions can be found under [all available Functions](/apis/resources/action_service_v2/action-service-list-execution-functions).
|
||||
|
||||
### Condition for Events
|
||||
|
||||
For event there are 3 levels the condition can be defined:
|
||||
|
||||
- Event, handling a specific event
|
||||
- Group, handling a specific group of events
|
||||
- All, handling any event in ZITADEL
|
||||
|
||||
The concept of events can be found under [Events](/concepts/architecture/software#events)
|
||||
|
||||
### Error forwarding
|
||||
|
||||
If you want to forward a specific error from the Target through ZITADEL, you can provide a response from the Target with status code 200 and a JSON in the following format:
|
||||
|
||||
```json
|
||||
{
|
||||
"forwardedStatusCode": 403,
|
||||
"forwardedErrorMessage": "Call is forbidden through the IP AllowList definition"
|
||||
}
|
||||
```
|
||||
|
||||
Only values from 400 to 499 will be forwarded through ZITADEL, other StatusCodes will end in a PreconditionFailed error.
|
||||
|
||||
If the Target returns any other status code than >= 200 and < 299, the execution is looked at as failed, and a PreconditionFailed error is logged.
|
||||
Reference in New Issue
Block a user