feat(actions): local users (#5089)

Actions are extended to to local users. It's possible to run custom code during registration and authentication of local users.
2025-08-12 03:57:32 +00:00 · 2023-01-25 14:08:01 +01:00
parent 19621acfd3
commit c54ddc71a2
48 changed files with 704 additions and 188 deletions
--- a/docs/docs/apis/actions/complement-token.md
+++ b/docs/docs/apis/actions/complement-token.md
@@ -1,16 +1,14 @@
 ---
-title: Login flows
+title: Complement Token Flow
 ---

-## Complement Token
-
 This flow is executed during the creation of tokens and token introspection.

-### Pre Userinfo creation
+## Pre Userinfo creation

 This trigger is called before userinfo are set in the token or response.

-#### Parameters of Pre Userinfo creation
+### Parameters of Pre Userinfo creation

 - `ctx`  
  The first parameter contains the following fields:
@@ -27,11 +25,11 @@ This trigger is called before userinfo are set in the token or response.
      - `setMetadata(string, Any)`  
        Key of the metadata and any value

-### Pre access token creation
+## Pre access token creation

 This trigger is called before the claims are set in the access token and the token type is `jwt`.

-#### Parameters of Pre access token creation
+### Parameters of Pre access token creation

 - `ctx`  
  The first parameter contains the following fields:
--- a/docs/docs/apis/actions/external-authentication.md
+++ b/docs/docs/apis/actions/external-authentication.md
@@ -1,16 +1,14 @@
 ---
-title: Register flows
+title: External Authentication Flow
 ---

-## External Authentication
-
 This flow is executed if the user logs in using an [identity provider](../../guides/integrate/identity-brokering) or using a [jwt token](../../concepts/structure/jwt_idp).

-### Post Authentication
+## Post Authentication

 A user has authenticated externally. ZITADEL retrieved and mapped the external information.

-#### Parameters of post authentication action
+### Parameters of Post Authentication Action

 - `ctx`  
 The first parameter contains the following fields
@@ -24,6 +22,7 @@ The first parameter contains the following fields
    The id token which will be returned to the user
  - `v1`
    - `externalUser()` [*externalUser*](./objects#external-user)
+    - `authRequest` [*auth request*](/docs/apis/actions/objects#auth-request)
 - `api`  
  The second parameter contains the following fields
  - `v1`
@@ -53,16 +52,17 @@ The first parameter contains the following fields
  - `metadata`  
    Array of [*metadata*](./objects#metadata-with-value-as-bytes). This function is deprecated, please use `api.v1.user.appendMetadata`

-### Pre Creation
+## Pre Creation

 A user selected **Register** on the overview page after external authentication. ZITADEL did not create the user yet.

-#### Parameters of Pre Creation
+### Parameters of Pre Creation

 - `ctx`  
  The first parameter contains the following fields
  - `v1`
    - `user` [*human*](./objects#human-user)
+    - `authRequest` [*auth request*](/docs/apis/actions/objects#auth-request)
 - `api`  
  The second parameter contains the following fields
  - `metadata`  
@@ -95,16 +95,17 @@ A user selected **Register** on the overview page after external authentication.
      - `appendMetadata(string, Any)`  
        The first parameter represents the key and the second a value which will be stored

-### Post Creation
+## Post Creation

 A user selected **Register** on the overview page after external authentication and ZITADEL successfully created the user.

-#### Parameters of Post Creation
+### Parameters of Post Creation

 - `ctx`  
  The first parameter contains the following fields
  - `v1`
    - `getUser()` [*user*](./objects#user)
+    - `authRequest` [*auth request*](/docs/apis/actions/objects#auth-request)
 - `api`  
  The second parameter contains the following fields
  - `userGrants` Array of [*userGrant*](./objects#user-grant)'s
--- a/docs/docs/apis/actions/internal-authentication.md
+++ b/docs/docs/apis/actions/internal-authentication.md
@@ -0,0 +1,90 @@
+---
+title: Internal Authentication Flow
+---
+
+## 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.
+
+### Parameters of Post Authentication Action
+
+- `ctx`  
+  The first parameter contains the following fields
+    - `v1`
+        - `authMethod` *string*  
+          This is one of "password", "OTP", "U2F" or "passwordless"
+        - `authError` *string*  
+          This is a verification errors string representation. If the verification succeeds, this is "none"
+        - `authRequest` [*auth request*](/docs/apis/actions/objects#auth-request)
+- `api`  
+  The second parameter contains the following fields
+    - `metadata`  
+      Array of [*metadata*](./objects#metadata-with-value-as-bytes). This function is deprecated, please use `api.v1.user.appendMetadata`
+    - `v1`
+        - `user`
+            - `appendMetadata(string, Any)`  
+              The first parameter represents the key and the second a value which will be stored
+
+## Pre Creation
+
+A user registers directly at ZITADEL.
+ZITADEL did not create the user yet.
+
+### Parameters of Pre Creation
+
+- `ctx`  
+  The first parameter contains the following fields
+    - `v1`
+        - `user` [*human*](./objects#human-user)
+        - `authRequest` [*auth request*](/docs/apis/actions/objects#auth-request)
+- `api`  
+  The second parameter contains the following fields
+    - `metadata`  
+      Array of [*metadata*](./objects#metadata-with-value-as-bytes). This function is deprecated, please use `api.v1.user.appendMetadata`
+    - `setFirstName(string)`  
+      Sets the first name
+    - `setLastName(string)`  
+      Sets the last name
+    - `setNickName(string)`  
+      Sets the nick name
+    - `setDisplayName(string)`  
+      Sets the display name
+    - `setPreferredLanguage(string)`  
+      Sets the preferred language, the string has to be a valid language tag as defined in [RFC 5646](https://www.rfc-editor.org/rfc/rfc5646)
+    - `setGender(int)`  
+      Sets the gender.
+      <ul><li>0: unspecified</li><li>1: female</li><li>2: male</li><li>3: diverse</li></ul>
+    - `setUsername(string)`  
+      Sets the username
+    - `setEmail(string)`  
+      Sets the email
+    - `setEmailVerified(bool)`  
+      If true the email set is verified without user interaction
+    - `setPhone(string)`  
+      Sets the phone number
+    - `setPhoneVerified(bool)`  
+      If true the phone number set is verified without user interaction
+    - `v1`
+        - `user`
+            - `appendMetadata(string, Any)`  
+              The first parameter represents the key and the second a value which will be stored
+
+## Post Creation
+
+A user registers directly at ZITADEL.  
+ZITADEL successfully created the user.
+
+### Parameters of Post Creation
+
+- `ctx`  
+  The first parameter contains the following fields
+    - `v1`
+        - `getUser()` [*user*](./objects#user)
+        - `authRequest` [*auth request*](/docs/apis/actions/objects#auth-request)
+- `api`  
+  The second parameter contains the following fields
+    - `userGrants` Array of [*userGrant*](./objects#user-grant)'s
+    - `v1`
+        - `appendUserGrant(`[`userGrant`](./objects#user-grant)`)`
--- a/docs/docs/apis/actions/introduction.md
+++ b/docs/docs/apis/actions/introduction.md
@@ -46,9 +46,10 @@ Trigger types define the point during execution of request. Each trigger defines

 Currently ZITADEL provides the following flows:

- [Login](./login-flow.md)
- [Register](./register-flow.md)
+- [Internal Authentication](./internal-authentication.md)
+- [External Authentication](./external-authentication.md)
+- [Complement Token](./complement-token.md)

 ## Available Modules inside Javascript

- [HTTP module](./modules#http) to call API's
+- [HTTP module](./modules#http) to call API's
--- a/docs/docs/apis/actions/objects.md
+++ b/docs/docs/apis/actions/objects.md
@@ -108,3 +108,48 @@ title: Objects
 - `phone`
  - `phone` *string*
  - `isPhoneVerified` *boolean*
+
+## Auth Request
+
+This object contains context information about the request to the [authorization endpoint](/docs/apis/openidoauth/endpoints#authorization_endpoint).
+
+- `id` *string*
+- `agentId` *string*
+- `creationDate` *Date*
+- `changeDate` *Date*
+- `browserInfo` *browserInfo*
+  - `userAgent` *string*
+  - `acceptLanguage` *string*
+  - `remoteIp` *string*
+- `applicationId` *string*
+- `callbackUri` *string*
+- `transferState` *string*
+- `prompt` Array of *Number*  
+   <ul><li>0: not specified</li><li>1: none</li><li>2: login</li><li>3: consent</li><li>4: select_account</li><li>5: create</li></ul>
+- `uiLocales` Array of *string*
+- `loginHint` *string*
+- `maxAuthAge` *Number*  
+  Duration in nanoseconds
+- `instanceId` *string*
+- `request`
+  - `oidc`
+    - `scopes` Array of *string*
+- `userId` *string*
+- `userName` *string*
+- `loginName` *string*
+- `displayName` *string*
+- `resourceOwner` *string*
+- `requestedOrgId` *string*
+- `requestedOrgName` *string*
+- `requestedPrimaryDomain` *string*
+- `requestedOrgDomain` *bool*
+- `applicationResourceOwner` *string*
+- `privateLabelingSetting` *Number*
+  <ul><li>0: Unspecified</li><li>1: Enforce project resource owner policy</li><li>2: Allow login user resource owner policy</li></ul>
+- `selectedIdpConfigId` *string*
+- `linkingUsers` Array of [*ExternalUser*](#external-user)
+- `passwordVerified` *bool*
+- `mfasVerified` Array of *Number*  
+  <ul><li>0: OTP</li><li>1: U2F</li><li>2: U2F User verification</li></ul>
+- `audience` Array of *string*
+- `authTime` *Date*
--- a/docs/docs/guides/manage/customize/behavior.md
+++ b/docs/docs/guides/manage/customize/behavior.md
@@ -35,7 +35,7 @@ https://github.com/zitadel/actions/blob/main/examples/add_user_grant.js

 ## Run the action when a user registers

-Now, make the action hook into the [external authentication flow](../../../apis/actions/register-flow#external-authentication).
+Now, make the action hook into the [external authentication flow](../../../apis/actions/external-authentication).

 1. In the **Flows <i className="las la-exchange-alt"></i>** section, select the **+ New** button.
 1. Select the **Flow Type** _External Authentication_.
--- a/docs/sidebars.js
+++ b/docs/sidebars.js
@@ -232,8 +232,9 @@ module.exports = {
      items: [
        "apis/actions/introduction",
        "apis/actions/modules",
-        "apis/actions/login-flow",
-        "apis/actions/register-flow",
+        "apis/actions/internal-authentication",
+        "apis/actions/external-authentication",
+        "apis/actions/complement-token",
        "apis/actions/objects",
      ]
    },