---
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>