From 7b537243c48e6885e6b7d2c217a851ba442430f0 Mon Sep 17 00:00:00 2001 From: Silvan Date: Mon, 11 Mar 2024 08:24:24 +0100 Subject: [PATCH] docs: describe combinations of flow and trigger types (#7519) * docs(api): describe which flow and trigger types word together * docs(actions): describe which flow and trigger types work together * Update management.proto --------- Co-authored-by: Livio Spring --- docs/docs/apis/actions/complement-token.md | 6 +++++ .../apis/actions/customize-samlresponse.md | 6 ++++- .../apis/actions/external-authentication.md | 8 ++++++ .../apis/actions/internal-authentication.md | 8 ++++++ proto/zitadel/management.proto | 27 ++++++++++++++++--- 5 files changed, 50 insertions(+), 5 deletions(-) diff --git a/docs/docs/apis/actions/complement-token.md b/docs/docs/apis/actions/complement-token.md index 336a5a740a..b0f8fea8e2 100644 --- a/docs/docs/apis/actions/complement-token.md +++ b/docs/docs/apis/actions/complement-token.md @@ -4,10 +4,14 @@ title: Complement Token Flow This flow is executed during the creation of tokens and token introspection. +The flow is represented by the following Ids in the API: `2` + ## Pre Userinfo creation (id_token / userinfo / introspection endpoint) This trigger is called before userinfo are set in the id_token or userinfo and introspection endpoint response. +The trigger is represented by the following Ids in the API: `4` + ### Parameters of Pre Userinfo creation - `ctx` @@ -38,6 +42,8 @@ This trigger is called before userinfo are set in the id_token or userinfo and i This trigger is called before the claims are set in the access token and the token type is `jwt`. +The trigger is represented by the following Ids in the API: `5` + ### Parameters of Pre access token creation - `ctx` diff --git a/docs/docs/apis/actions/customize-samlresponse.md b/docs/docs/apis/actions/customize-samlresponse.md index d52205c7e6..48d45c8433 100644 --- a/docs/docs/apis/actions/customize-samlresponse.md +++ b/docs/docs/apis/actions/customize-samlresponse.md @@ -2,12 +2,16 @@ title: Complement SAMLResponse --- -This flow is executed before the return of the SAMLResponse. +This flow is executed before the return of the SAML Response. + +The flow is represented by the following Ids in the API: `4` ## Pre SAMLResponse creation This trigger is called before attributes are set in the SAMLResponse. +The trigger is represented by the following Ids in the API: `6`. + ### Parameters of Pre SAMLResponse creation - `ctx` diff --git a/docs/docs/apis/actions/external-authentication.md b/docs/docs/apis/actions/external-authentication.md index 5d56066707..594fe9d695 100644 --- a/docs/docs/apis/actions/external-authentication.md +++ b/docs/docs/apis/actions/external-authentication.md @@ -4,10 +4,14 @@ title: External Authentication Flow This flow is executed if the user logs in using an [identity provider](/guides/integrate/identity-providers) or using a [jwt token](/concepts/structure/jwt_idp). +The flow is represented by the following Ids in the API: `FLOW_TYPE_EXTERNAL_AUTHENTICATION` and `1` + ## Post Authentication A user has authenticated externally. ZITADEL retrieved and mapped the external information. +The trigger is represented by the following Ids in the API: `TRIGGER_TYPE_POST_AUTHENTICATION` or `1`. + ### Parameters of Post Authentication Action - `ctx` @@ -62,6 +66,8 @@ The first parameter contains the following fields A user selected **Register** on the overview page after external authentication. ZITADEL did not create the user yet. +The trigger is represented by the following Ids in the API: `TRIGGER_TYPE_PRE_CREATION` or `2`. + ### Parameters of Pre Creation - `ctx` @@ -106,6 +112,8 @@ A user selected **Register** on the overview page after external authentication. A user selected **Register** on the overview page after external authentication and ZITADEL successfully created the user. +The trigger is represented by the following Ids in the API: `TRIGGER_TYPE_POST_CREATION` or `3`. + ### Parameters of Post Creation - `ctx` diff --git a/docs/docs/apis/actions/internal-authentication.md b/docs/docs/apis/actions/internal-authentication.md index 25654257f0..aee2ebe4d2 100644 --- a/docs/docs/apis/actions/internal-authentication.md +++ b/docs/docs/apis/actions/internal-authentication.md @@ -2,12 +2,16 @@ title: Internal Authentication Flow --- +The flow is represented by the following Ids in the API: `3` + ## Post Authentication A user has authenticated directly at ZITADEL. ZITADEL validated the users inputs for password, one-time password, security key or passwordless factor. Each validation step triggers the action. +The trigger is represented by the following Ids in the API: `TRIGGER_TYPE_POST_AUTHENTICATION` or `1`. + ### Parameters of Post Authentication Action - `ctx` @@ -33,6 +37,8 @@ Each validation step triggers the action. A user registers directly at ZITADEL. ZITADEL did not create the user yet. +The trigger is represented by the following Ids in the API: `TRIGGER_TYPE_PRE_CREATION` or `2`. + ### Parameters of Pre Creation - `ctx` @@ -78,6 +84,8 @@ ZITADEL did not create the user yet. A user registers directly at ZITADEL. ZITADEL successfully created the user. +The trigger is represented by the following Ids in the API: `TRIGGER_TYPE_POST_CREATION` or `3`. + ### Parameters of Post Creation - `ctx` diff --git a/proto/zitadel/management.proto b/proto/zitadel/management.proto index 9bb2e1efb3..41cc1c69e2 100644 --- a/proto/zitadel/management.proto +++ b/proto/zitadel/management.proto @@ -13009,18 +13009,37 @@ message ClearFlowResponse { } message SetTriggerActionsRequest { - // id of the flow type + /* id of the flow type. + * Following flows are currently allowed: + * - External Authentication: FLOW_TYPE_EXTERNAL_AUTHENTICATION or 1 + * - Internal Authentication: 3 + * - Complement Token: 2 + * - Complement SAML Response: 4 + */ string flow_type = 1 [ (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = { example: "\"1\""; - description: "At the moment you have to send the ID of the Flow Type: ExternalAuthentication=1, CustomiseToken=2, InternalAuthentication=3, PreUserinfoCreation=3"; } ]; - // id of the trigger type + /* id of the trigger type. + * Following triggers are currently allowed: + * - External Authentication: + * - Post Authentication: TRIGGER_TYPE_POST_AUTHENTICATION or 1 + * - Pre Creation: TRIGGER_TYPE_PRE_CREATION or 2 + * - Post Creation: TRIGGER_TYPE_POST_CREATION or 3 + * - Internal Authentication: + * - Post Authentication: TRIGGER_TYPE_POST_AUTHENTICATION or 1 + * - Pre Creation: TRIGGER_TYPE_PRE_CREATION or 2 + * - Post Creation: TRIGGER_TYPE_POST_CREATION or 3 + * - Complement Token: + * - Pre Userinfo Creation: 4 + * - Pre Access Token Creation: 5 + * - Complement SAML Response: + * - Pre SAML Response Creation: 6 + */ string trigger_type = 2 [ (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = { example: "\"1\""; - description: "At the moment you have to send the ID of the Trigger Type: PostAuthentication=1, PreCreation=2, PostCreation=3, PreUserinfoCreation=4, PreAccessTokenCreation=5"; } ]; repeated string action_ids = 3;