docs(actions): add examples (#7494)

* docs(actions): add use cases

* docs(actions): extend available modules

* docs(actions): add example to http module

* hide code in details

* add saml response,
correct code examples

* describe internal authentication flow

* rename to code examples

docs/docs/apis/actions/code-examples.mdx

@@ -0,0 +1,308 @@
+---
+title: Code examples
+---
+
+Actions are a powerful tool to extend ZITADEL and you might wonder what use cases actions can be used for.
+
+This page provides a non-exhaustive list of possibilities which is provided by [examples](https://github.com/zitadel/actions/tree/main/examples). If a use case is missing feel free to contribute an issue or pull request to the repository, thanks in advance 🤗.
+
+## Customize OIDC response
+
+Append claims returned on OIDC requests.
+
+### Triggers
+
+- Complement token
+  - [Pre Userinfo creation](./complement-token#pre-userinfo-creation-id_token--userinfo--introspection-endpoint)
+  - [Pre access token creation](./complement-token#pre-access-token-creation)
+
+### Set hardcoded claim
+
+Extend the claims by a hardcoded value.
+
+<details open="">
+<summary>Code example</summary>
+
+```js reference
+https://github.com/zitadel/actions/blob/main/examples/add_claim.js
+```
+
+</details>
+
+### Set dynamic claim from user metadata
+
+Extend the claims by dynamically read metadata from a user and sets the picture-claim if idpPicture-metadata value is present.
+
+<details open="">
+<summary>{props.summary ? props.summary : 'Code example'}</summary>
+
+```js reference
+https://github.com/zitadel/actions/blob/main/examples/add_picture_claim_from_idp_metadata.js
+```
+
+</details>
+
+### Set dynamic claim from organization metadata
+
+Extend the claims by dynamically read metadata from an organization and sets the present metadata.
+
+<details open="">
+<summary>Code example</summary>
+
+```js reference
+https://github.com/zitadel/actions/blob/main/examples/org_metadata_claim.js
+```
+
+</details>
+
+### Custom role mapping in claims
+
+Some products require specific role mapping from ZITADEL, no worries we got you covered 😉
+
+<details open="">
+<summary>Code example</summary>
+
+```js reference
+https://github.com/zitadel/actions/blob/main/examples/custom_roles.js
+```
+
+</details>
+
+## Customize SAML response
+
+Append attributes returned on SAML requests.
+
+### Triggers
+
+- Complement SAMLResponse
+  - [Pre SAMLResponse creation](./customize-samlresponse#pre-samlresponse-creation)
+
+### Custom role mapping in attributes
+
+Some products require specific role mapping from ZITADEL, no worries we got you covered 😉
+
+<details open="">
+<summary>Code example</summary>
+
+```js reference
+https://github.com/zitadel/actions/blob/main/examples/set_custom_attribute.js
+```
+
+</details>
+
+### Set dynamic attribute from organization metadata
+
+Extend the attributes by dynamically read metadata from an organization and sets the present metadata.
+
+<details open="">
+<summary>Code example</summary>
+
+```js reference
+https://github.com/zitadel/actions/blob/main/examples/org_metadata_attribute.js
+```
+
+</details>
+
+## Manipulate user
+
+You can automate manual tasks like setting default grants during user creation.
+
+### Set email always verified
+
+Useful if you trust the provided information or don't want the users to verify their e-mail addresses.
+
+#### Triggers
+
+- Internal Authentication
+  - [Pre Creation](/docs/apis/actions/internal-authentication#pre-creation)
+- External Authentication
+  - [Pre Creation](/docs/apis/actions/external-authentication#pre-creation)
+
+<details open="">
+<summary>Code example</summary>
+
+```js reference
+https://github.com/zitadel/actions/blob/main/examples/verify_email.js
+```
+
+</details>
+
+### Add grants to users
+
+Allows you to add default user grants to a user after it was created or federated.
+
+#### Triggers
+
+- Internal Authentication
+  - [Post Creation](/docs/apis/actions/internal-authentication#post-creation)
+- External Authentication
+  - [Post Creation](/docs/apis/actions/external-authentication#post-creation)
+
+<details open="">
+<summary>Code example</summary>
+
+```js reference
+https://github.com/zitadel/actions/blob/main/examples/add_user_grant.js
+```
+
+</details>
+
+### Add metadata to users
+
+Adding metadata to users allows you to set default metadata on users.
+
+#### Triggers
+
+- Internal Authentication
+  - [Post Creation](/docs/apis/actions/internal-authentication#post-creation)
+  - [Post Authentication](/docs/apis/actions/internal-authentication#post-authentication)
+- External Authentication
+  - [Post Creation](/docs/apis/actions/internal-authentication#post-creation)
+  - [Post Authentication](/docs/apis/actions/internal-authentication#post-authentication)
+
+<details open="">
+<summary>Code example</summary>
+
+```js reference
+https://github.com/zitadel/actions/blob/main/examples/add_metadata.js
+```
+
+</details>
+
+## Use provided fields of identity providers
+
+If you want to ensure that the data of a user are always update you can automatically update user fields during authentication and safe time of your customers and your team. 🤯
+
+### Trigger
+
+- External Authentication
+  - [Post Authentication](./external-authentication#post-authentication)
+
+### Fields provided by Okta
+
+If you use [Okta as an identity provider](/guides/integrate/identity-providers/okta) you can improve the onboarding experience of new users by prefilling some basic information during authentication.
+
+<details open="">
+<summary>Code example</summary>
+
+```js reference
+https://github.com/zitadel/actions/blob/main/examples/okta_identity_provider.js
+```
+
+</details>
+
+### Fields provided by Gitlab
+
+If you use [Gitlab as an identity provider](/guides/integrate/identity-providers/gitlab) you can improve the onboarding experience of new users by prefilling some basic information during authentication.
+
+<details open="">
+<summary>Code example</summary>
+
+```js reference
+https://github.com/zitadel/actions/blob/main/examples/gitlab_identity_provider.js
+```
+
+</details>
+
+### Fields provided by Github
+
+If you use [Github as an identity provider](/guides/integrate/identity-providers/github) you can improve the onboarding experience of new users by prefilling some basic information during authentication.
+
+<details open="">
+<summary>Code example</summary>
+
+```js reference
+https://github.com/zitadel/actions/blob/main/examples/github_identity_provider.js
+```
+
+</details>
+
+### Claims provided by a generic OIDC identity provider
+
+If you use a [generic OIDC identity provider](/guides/integrate/identity-providers/migrate#migrate-generic-oidc-provider) you can improve the onboarding experience of new users by prefilling some basic information during authentication.
+
+<details open="">
+<summary>Code example</summary>
+
+```js reference
+https://github.com/zitadel/actions/blob/main/examples/set_idp_picture_metadata.js
+```
+
+</details>
+
+### Attributes provided by a generic SAML identity provider
+
+If you use a [SAML identity provider like mocksaml](/guides/integrate/identity-providers/mocksaml) you can improve the onboarding experience of new users by prefilling some basic information during authentication.
+
+<details open="">
+<summary>Code example</summary>
+
+```js reference
+https://github.com/zitadel/actions/blob/main/examples/post_auth_saml.js
+```
+
+</details>
+
+## Context aware execution
+
+Based on the context the execution path of an action can change. ZITADEL allows complex execution paths of course. 😎
+
+### Based on auth request information
+
+Execution paths might change based on the application initiating the authentication.
+
+#### Triggers
+
+- Internal Authentication
+  - [Pre Creation](/docs/apis/actions/internal-authentication#pre-creation)
+  - [Post Creation](/docs/apis/actions/internal-authentication#post-creation)
+  - [Post Authentication](/docs/apis/actions/internal-authentication#post-authentication)
+- External Authentication
+  - [Pre Creation](/docs/apis/actions/external-authentication#pre-creation)
+  - [Post Creation](/docs/apis/actions/external-authentication#post-creation)
+  - [Post Authentication](/docs/apis/actions/external-authentication#post-authentication)
+
+<details open="">
+<summary>Code example</summary>
+
+```js reference
+https://github.com/zitadel/actions/blob/main/examples/execute_action_on_specific_app.js
+```
+
+</details>
+
+This example uses [zitadel's log module](/docs/apis/actions/modules#log)
+
+### Check authentication error
+
+Your action can also check for errors during the login process.
+
+#### Triggers
+
+- Internal Authentication
+  - [Post Authentication](/docs/apis/actions/internal-authentication#post-authentication)
+- External Authentication
+  - [Post Authentication](/docs/apis/actions/external-authentication#post-authentication)
+
+<details open="">
+<summary>Code example</summary>
+
+```js reference
+https://github.com/zitadel/actions/blob/main/examples/post_auth_log.js
+```
+
+</details>
+
+This example uses [zitadel's log module](/docs/apis/actions/modules#log)
+
+### Throw an error
+
+Allows you to limit the user interaction. The error thrown will be shown to the user if the action is not [allowed to fail](/concepts/features/actions#how-it-works).
+
+<details open="">
+<summary>Code example</summary>
+
+```js reference
+https://github.com/zitadel/actions/blob/main/examples/throw_error.js
+```
+</details>

docs/docs/apis/actions/internal-authentication.md

@@ -2,6 +2,8 @@
 title: Internal Authentication Flow
 ---
 
+This flow is executed if the user logs in using the login UI hosted by ZITADEL.
+
 The flow is represented by the following Ids in the API: `3`
 
 ## Post Authentication

docs/docs/apis/actions/introduction.md

@@ -46,10 +46,13 @@ Trigger types define the point during execution of request. Each trigger defines
 
 Currently ZITADEL provides the following flows:
 
-- [Internal Authentication](./internal-authentication.md)
+- [Internal Authentication](./internal-authentication)
-- [External Authentication](./external-authentication.md)
+- [External Authentication](./external-authentication)
-- [Complement Token](./complement-token.md)
+- [Complement Token](./complement-token)
+- [Customize SAML Response](./customize-samlresponse)
 
 ## Available Modules inside Javascript
 
 - [HTTP module](./modules#http) to call API's
+- [Logging module](./modules#log) logs information to stdout
+- [UUID module](./modules#uuid) generates uuids

docs/docs/apis/actions/modules.md

@@ -52,6 +52,12 @@ The object has the following fields and methods:
 - `text()` *string*  
   Returns the body
 
+### Example
+
+```js reference
+https://github.com/zitadel/actions/blob/main/examples/make_api_call.js#L10-L20
+```
+
 ## Log
 
 The log module provides you with the functionality to log to stdout.

docs/docs/concepts/features/actions.md

@@ -36,3 +36,4 @@ Within the JavaScript code, you can read and manipulate the state.
 - [Assign users a role after they register using an external identity provider](/guides/manage/customize/behavior)
 - [Actions reference](/apis/actions/introduction#action)
 - [Actions Marketplace: Find example actions to use in ZITADEL](https://github.com/zitadel/actions)
+- [Example use cases](/apis/actions/code-examples)

docs/docs/guides/integrate/identity-providers/mocksaml.mdx

@@ -10,6 +10,7 @@ import CustomLoginPolicy from './_custom_login_policy.mdx';
 import IDPsOverview from './_idps_overview.mdx';
 import Activate from './_activate.mdx';
 import TestSetup from './_test_setup.mdx';
+import PrefillAction from './_prefill_action.mdx';
 
 <Intro provider="MockSAML"/>
 
@@ -63,3 +64,11 @@ They are available under [https://{CUSTOMDOMAIN}/idps/{ID of the provider in ZIT
 ![SAML SP Button](/img/guides/zitadel_login_saml.png)
 
 ![SAML SP Login](/img/guides/mocksaml_login.png)
+
+## Optional: Add ZITADEL action to autofill userdata
+
+<PrefillAction fields="firstname, lastname, email, display name and username" provider="mockSaml"/>
+
+```js reference
+https://github.com/zitadel/actions/blob/main/examples/post_auth_saml.js
+```

docs/docs/guides/integrate/identity-providers/okta.mdx

@@ -11,6 +11,7 @@ import IDPsOverview from './_idps_overview.mdx';
 import GenericOIDC from './_generic_oidc.mdx';
 import Activate from './_activate.mdx';
 import TestSetup from './_test_setup.mdx';
+import PrefillAction from './_prefill_action.mdx';
 
 <Intro provider="OKTA"/>
 

docs/docs/guides/integrate/retrieve-user-roles.md

@@ -192,6 +192,19 @@ This request can be tested out in the following way:
 3. When you run the command, you will see the roles in the response.
 4. If you remove the role claims in the scope and run the command, you will not receive the roles.
 
+#### Customize roles using actions
+
+If your application requires a custom role structure, [ZITADEL actions](/docs/apis/actions/complement-token#pre-userinfo-creation-id_token--userinfo--introspection-endpoint) allow you to customize your claims.
+
+<details open="open">
+<summary>Example on github</summary>
+
+```js reference
+https://github.com/zitadel/actions/blob/main/examples/custom_roles.js
+```
+
+</details>
+
 ### Retrieve roles using the auth API
 
 Now we will use the auth API to retrieve roles from a logged in user using the user’s token

docs/sidebars.js

@@ -807,6 +807,7 @@ module.exports = {
       items: [
         "apis/actions/introduction",
         "apis/actions/modules",
+        "apis/actions/code-examples",
         "apis/actions/internal-authentication",
         "apis/actions/external-authentication",
         "apis/actions/complement-token",