mirror of
https://github.com/andwati/zitadel.git
synced 2026-10-18 21:52:54 +00:00
f4f43f5248
# Which Problems Are Solved Pages in `apps/docs` that embed source from GitHub via the Docusaurus convention ```` ```js reference https://github.com/zitadel/actions/blob/main/examples/org_metadata_claim.js ``` ```` stopped working after the migration from Docusaurus to fumadocs. The old `docusaurus-theme-github-codeblock` plugin used to fetch the file and render it; fumadocs has no support for that meta, so the page rendered the raw URL as plain code-block text. Visible at `/docs/apis/actions/code-examples` and 16 other pages. # How the Problems Are Solved - Converted every ```` ```<lang> reference\n<URL>\n``` ```` block (46 total across 17 `.mdx` files) to the native fumadocs JSX form: `<GithubCodeBlock url="<URL>" />`. The existing `<details>`/`<summary>` collapsibles around blocks are kept — they're an authoring choice, not part of the rendering bug. - Updated `apps/docs/components/github-code-block.tsx` to render via `DynamicCodeBlock` from `fumadocs-ui/components/dynamic-codeblock` (proper shiki highlighting) instead of raw `CodeBlock` + `Pre` (which produced unhighlighted output). Also fixed language detection so a URL hash like `#L10-L20` no longer pollutes the language token. - Registered `GithubCodeBlock` globally in `apps/docs/mdx-components.tsx`, matching how every other shared component (`APIPage`, `Callout`, `Tab/Tabs`, `Step/Steps`, `Admonition`, `TerminologyUpdate`) is exposed. MDX files no longer need a local `import`. # Additional Changes - Normalized the two MDX files that were already using the JSX form (`examples/secure-api/python-django.mdx`, `examples/secure-api/java-spring.mdx`): removed their now-redundant local `import { GithubCodeBlock }` and rewrote 9 long-form `<GithubCodeBlock url="..."></GithubCodeBlock>` tags to self-closing for consistency. # Additional Context Verified locally with `pnpm --filter @zitadel/docs dev`: - `/docs/apis/actions/code-examples` — 20 shiki-highlighted code blocks rendered inside the `<details>` collapsibles (was 0). - `/docs/apis/openidoauth/claims` — line-range hashes (`#L9-L11`) honored. - `/docs/examples/login/flutter` — mixed languages (xml/dart/html) detected and highlighted. - `/docs/guides/integrate/external-audit-log` — edge case of fenced reference indented inside a numbered list also converted and rendered. Greps: - `^[ \t]*\`\`\`[a-zA-Z0-9]+ reference` in `apps/docs/content/**/*.mdx` → 0 matches. - `<GithubCodeBlock url="` in `apps/docs/content/**/*.mdx` → 55 matches. - `from '@/components/github-code-block'` in `apps/docs/content/**/*.mdx` → 0 matches. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 4.7 (1M context) <[email protected]>
309 lines
10 KiB
Plaintext
309 lines
10 KiB
Plaintext
---
|
|
title: Code examples
|
|
description: "Practical code examples for ZITADEL Actions, from custom claims to external API integration."
|
|
---
|
|
|
|
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 a hardcoded claim
|
|
|
|
Extend the claims by a hardcoded value.
|
|
|
|
<details open="">
|
|
<summary>Code example</summary>
|
|
|
|
<GithubCodeBlock url="https://github.com/zitadel/actions/blob/main/examples/add_claim.js" />
|
|
|
|
</details>
|
|
|
|
### Set dynamic claim from user metadata
|
|
|
|
Extend the claims by dynamically reading 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>
|
|
|
|
<GithubCodeBlock url="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 reading metadata from an organization and sets the present metadata.
|
|
|
|
<details open="">
|
|
<summary>Code example</summary>
|
|
|
|
<GithubCodeBlock url="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>
|
|
|
|
<GithubCodeBlock url="https://github.com/zitadel/actions/blob/main/examples/custom_roles.js" />
|
|
|
|
</details>
|
|
|
|
### Custom role mapping including org metadata in claims
|
|
|
|
There's even a possibility to use the metadata of organizations the user is granted to
|
|
|
|
<details open="">
|
|
<summary>Code example</summary>
|
|
|
|
<GithubCodeBlock url="https://github.com/zitadel/actions/blob/main/examples/custom_roles_org_metadata.js" />
|
|
|
|
</details>
|
|
|
|
## Customize SAML response
|
|
|
|
Append attributes returned on SAML requests.
|
|
|
|
### Triggers
|
|
|
|
- Complement SAMLResponse
|
|
- [Pre SAMLResponse creation](./customize-samlresponse#pre-saml-response-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>
|
|
|
|
<GithubCodeBlock url="https://github.com/zitadel/actions/blob/main/examples/set_custom_attribute.js" />
|
|
|
|
</details>
|
|
|
|
### Set dynamic attribute from organization metadata
|
|
|
|
Extend the attributes by dynamically reading metadata from an organization and sets the present metadata.
|
|
|
|
<details open="">
|
|
<summary>Code example</summary>
|
|
|
|
<GithubCodeBlock url="https://github.com/zitadel/actions/blob/main/examples/org_metadata_attribute.js" />
|
|
|
|
</details>
|
|
|
|
## Manipulate user
|
|
|
|
You can automate manual tasks such as assigning default roles 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](/apis/actions/internal-authentication#pre-creation)
|
|
- External Authentication
|
|
- [Pre Creation](/apis/actions/external-authentication#pre-creation)
|
|
|
|
<details open="">
|
|
<summary>Code example</summary>
|
|
|
|
<GithubCodeBlock url="https://github.com/zitadel/actions/blob/main/examples/verify_email.js" />
|
|
|
|
</details>
|
|
|
|
### Assign roles to users
|
|
|
|
Allows you to assign default roles to a user after the user was created or federated.
|
|
|
|
#### Triggers
|
|
|
|
- Internal Authentication
|
|
- [Post Creation](/apis/actions/internal-authentication#post-creation)
|
|
- External Authentication
|
|
- [Post Creation](/apis/actions/external-authentication#post-creation)
|
|
|
|
<details open="">
|
|
<summary>Code example</summary>
|
|
|
|
<GithubCodeBlock url="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
|
|
- [Pre Creation](/apis/actions/internal-authentication#pre-creation)
|
|
- [Post Authentication](/apis/actions/internal-authentication#post-authentication)
|
|
- External Authentication
|
|
- [Pre Creation](/apis/actions/internal-authentication#pre-creation)
|
|
- [Post Authentication](/apis/actions/internal-authentication#post-authentication)
|
|
|
|
<details open="">
|
|
<summary>Code example</summary>
|
|
|
|
<GithubCodeBlock url="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 up to date, you can automatically update user fields during authentication and save time of your customers and your team.
|
|
|
|
### Trigger
|
|
|
|
- External Authentication
|
|
- [Post Authentication](./external-authentication#post-authentication)
|
|
|
|
### Fields provided by Okta as OIDC IdP
|
|
|
|
If you use [Okta as an identity provider](/guides/integrate/identity-providers/okta-oidc), you can improve the onboarding experience of new users by prefilling some basic information during authentication.
|
|
|
|
<details open="">
|
|
<summary>Code example</summary>
|
|
|
|
<GithubCodeBlock url="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>
|
|
|
|
<GithubCodeBlock url="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>
|
|
|
|
<GithubCodeBlock url="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>
|
|
|
|
<GithubCodeBlock url="https://github.com/zitadel/actions/blob/main/examples/set_idp_picture_metadata.js" />
|
|
|
|
</details>
|
|
|
|
### Attributes provided by Okta as SAML IDP
|
|
|
|
If you use [Okta as an identity provider](/guides/integrate/identity-providers/okta_saml#add-attribute-statements), you can improve the onboarding experience of new users by prefilling some basic information during authentication.
|
|
|
|
<details open="">
|
|
<summary>Code example</summary>
|
|
|
|
<GithubCodeBlock url="https://github.com/zitadel/actions/blob/main/examples/okta_saml_prefil_register_form.js" />
|
|
|
|
</details>
|
|
|
|
### Attributes provided by Microsoft Entra as SAML IDP
|
|
|
|
If you use [Microsoft Entra as SAML identity provider](/guides/integrate/identity-providers/azure-ad-saml), you can improve the onboarding experience of new users by prefilling some basic information during authentication.
|
|
|
|
<details open="">
|
|
<summary>Code example</summary>
|
|
|
|
<GithubCodeBlock url="https://github.com/zitadel/actions/blob/main/examples/entra_id_saml_prefil_register_form.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>
|
|
|
|
<GithubCodeBlock url="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](/apis/actions/internal-authentication#pre-creation)
|
|
- [Post Creation](/apis/actions/internal-authentication#post-creation)
|
|
- [Post Authentication](/apis/actions/internal-authentication#post-authentication)
|
|
- External Authentication
|
|
- [Pre Creation](/apis/actions/external-authentication#pre-creation)
|
|
- [Post Creation](/apis/actions/external-authentication#post-creation)
|
|
- [Post Authentication](/apis/actions/external-authentication#post-authentication)
|
|
|
|
<details open="">
|
|
<summary>Code example</summary>
|
|
|
|
<GithubCodeBlock url="https://github.com/zitadel/actions/blob/main/examples/execute_action_on_specific_app.js" />
|
|
|
|
</details>
|
|
|
|
This example uses [zitadel's log module](/apis/actions/modules#log)
|
|
|
|
### Check authentication error
|
|
|
|
Your action can also check for errors during the login process.
|
|
|
|
#### Triggers
|
|
|
|
- Internal Authentication
|
|
- [Post Authentication](/apis/actions/internal-authentication#post-authentication)
|
|
- External Authentication
|
|
- [Post Authentication](/apis/actions/external-authentication#post-authentication)
|
|
|
|
<details open="">
|
|
<summary>Code example</summary>
|
|
|
|
<GithubCodeBlock url="https://github.com/zitadel/actions/blob/main/examples/post_auth_log.js" />
|
|
|
|
</details>
|
|
|
|
This example uses [zitadel's log module](/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>
|
|
|
|
<GithubCodeBlock url="https://github.com/zitadel/actions/blob/main/examples/throw_error.js" />
|
|
</details>
|