feat(actions): add fields to complement token flow (#5336)

* deprecated `ctx.v1.userinfo`-field in "pre userinfo creation" trigger in favour of `ctx.v1.claims`. The trigger now behaves the same as "pre access token creation"
* added `ctx.v1.claims` to "complement tokens" flow
* added `ctx.v1.grants` to "complement tokens" flow
* document `ctx.v1.getUser()` in "complement tokens" flow

* feat(actions): add getUser() and grant

* map user grants

* map claims

* feat(actions): claims in complement token ctx

* docs(actions): add new fields of complement token

* docs(actions): additions to complement token

* docs(actions): correct field names

docs/docs/apis/actions/complement-token.md

@@ -13,14 +13,21 @@ This trigger is called before userinfo are set in the token or response.
 - `ctx`  
   The first parameter contains the following fields:
   - `v1`
+    - `claims` [*Claims*](./objects#claims)
+    - `getUser()` [*User*](./objects#user)
     - `user`
       - `getMetadata()` [*metadataResult*](./objects#metadata-result)
+    - `grants` [*UserGrantList*](./objects#user-grant-list)
 - `api`  
   The second parameter contains the following fields:
   - `v1`
-    - `userinfo`
+    - `userinfo`  
+      This function is deprecated, please use `api.v1.claims`
       - `setClaim(string, Any)`  
-        Key of the claim and any value
+        Sets any value if the key is not already present. If it's already present there is a message added to `urn:zitadel:iam:action:${action.name}:log`
+    - `claims`
+      - `setClaim(string, Any)`  
+        Sets any value if the key is not already present. If it's already present there is a message added to `urn:zitadel:iam:action:${action.name}:log`
     - `user`
       - `setMetadata(string, Any)`  
         Key of the metadata and any value
@@ -34,14 +41,17 @@ This trigger is called before the claims are set in the access token and the tok
 - `ctx`  
   The first parameter contains the following fields:
   - `v1`
+    - `claims` [*Claims*](./objects#claims)
+    - `getUser()` [*User*](./objects#user)
     - `user`
       - `getMetadata()` [*metadataResult*](./objects#metadata-result)
+    - `grants` [*UserGrantList*](./objects#user-grant-list)
 - `api`  
   The second parameter contains the following fields:
   - `v1`
     - `claims`
       - `setClaim(string, Any)`  
-        Sets any value if the key is not already present
+        Sets any value if the key is not already present. If it's already present there is a message added to `urn:zitadel:iam:action:${action.name}:log`
       - `appendLogIntoClaims(string)`  
         Appends the entry into the claim `urn:zitadel:action:{action.name}:log` the value of the claim is an Array of *string*
     - `user`

docs/docs/apis/actions/objects.md

@@ -166,4 +166,44 @@ This object is based on the Golang struct [http.Request](https://pkg.go.dev/net/
 - `form` Map *string* of Array of *string*
 - `postForm` Map *string* of Array of *string*
 - `remoteAddr` *string*
-- `headers` Map *string* of Array of *string*
+- `headers` Map *string* of Array of *string*
+
+## Claims
+
+This object represents [the claims](../openidoauth/claims) which will be written into the oidc token.
+
+- `sub` *string*
+- `name` *string*
+- `email` *string*
+- `locale` *string*
+- `given_name` *string*
+- `family_name` *string*
+- `preferred_username` *string*
+- `email_verified` *bool*
+- `updated_at` *Number*
+
+Additionally there could additional fields depending on the configuration of your [project](../../guides/manage/console/projects#role-settings) and your [application](../../guides/manage/console/applications#token-settings)
+
+## user grant list
+
+This object represents a list of user grant stored in ZITADEL.
+
+- `count` *Number*
+- `sequence` *Number*
+- `timestamp` *Date*
+- `grants` Array of
+  - `id` *string*
+  - `projectGrantId` *string*  
+    The id of the [project grant](../../concepts/usecases/saas#project-grant)
+  - `state` *Number*  
+    <ul><li>0: unspecified</li><li>1: active</li><li>2: inactive</li><li>3: removed</li></ul>
+  - `creationDate` *Date*
+  - `changeDate` *Date*
+  - `sequence` *Number*
+  - `userId` *string*
+  - `roles` Array of *string*
+  - `userResourceOwner` *string*
+  - `userGrantResourceOwner` *string*
+  - `userGrantResourceOwnerName` *string*
+  - `projectId` *string*
+  - `projectName` *string*

docs/docs/apis/openidoauth/claims.md

@@ -67,11 +67,11 @@ Please check below the matrix for an overview where which scope is asserted.
 
 ## Custom Claims
 
-> This feature is not yet released
+You can add custom claims using the [complement token flow](/docs/apis/actions/complement-token) of the [actions feature](/docs/apis/actions/introduction).
 
 ## Reserved Claims
 
-ZITADEL reserves some claims to assert certain data. Please check out the [reserved scopes](scopes#reserved-scopes). 
+ZITADEL reserves some claims to assert certain data. Please check out the [reserved scopes](scopes#reserved-scopes).
 
 | Claims                                            | Example                                                                                              | Description                                                                                                                                                                        |
 |:--------------------------------------------------|:-----------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|

docs/docs/examples/identity-proxy/oauth2-proxy.md

@@ -59,7 +59,16 @@ cookie_secure = false #localdev only false
 http_address = "127.0.0.1:4180" #localdev only
 ```
 
-> This was tested with version `oauth2-proxy v6.1.1 (built with go1.14.2)`
+> This was tested with version `oauth2-proxy v7.4.0 (built with go1.20.0)`
+
+### Check for groups
+
+If you want oauth2-proxy to check for roles in the tokens you have to add an [action](/docs/apis/actions/introduction) in ZITADEL to [complement the token](/docs/apis/actions/complement-token) according to [this example](https://github.com/zitadel/actions/blob/main/examples/custom_roles.js) and add the following configuration to the config:
+
+```toml
+oidc_groups_claim = "{your_actions_group_key}"
+allowed_groups = ["list", "of", "allowed", "roles"]
+```
 
 ## Completion