> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oleria.com/llms.txt
> Use this file to discover all available pages before exploring further.

# ZITADEL

> Connect your ZITADEL instance to Oleria to discover users, service accounts and their credentials, organizations, project and administrator roles, project access, and audit events, and take remediation actions directly from Oleria.

Connect ZITADEL to Oleria to see who can sign in to which of your applications, and who can administer ZITADEL itself. Oleria reads identity, access, and audit data from the ZITADEL APIs as a ZITADEL service account, across every organization in your instance. You can then review over-provisioned access and take action directly from Oleria.

One Oleria connection maps one ZITADEL instance. ZITADEL Cloud instances, instances on a custom domain, and self-hosted instances are supported. To connect another instance, add another integration.

## What Oleria discovers

Once connected, Oleria continuously discovers and maps the following from your ZITADEL instance:

* **Users** - every human user and service account in every organization, with their state. Only active users are shown as enabled. For human users, Oleria also shows email, last password change, enrolled authentication methods, and MFA and SSO status. MFA is shown as required when the organization's login settings force it and the user has a second factor enrolled, or, whatever the settings, when the user has enrolled TOTP, U2F, an SMS one-time password, or an email one-time password, because current ZITADEL versions always ask for an enrolled second factor. A passkey alone doesn't count. Users the settings require MFA for who haven't enrolled a second factor show as enrollment required. SSO status comes from the login settings and the user's linked identity providers. When your instance or an organization signs users in through a SAML identity provider, Oleria links ZITADEL to the app in your identity provider through the SAML signing certificate. Users that hold any ZITADEL administrator role, including viewer roles, are marked as administrators.
* **Groups** - ZITADEL has no usable groups yet, so Oleria shows each **organization** as a group. Every user is a member of the organization they belong to. Users with the `ORG_OWNER` administrator role on an organization are shown as its owners. Oleria also adds a **ZITADEL system administrators (synthesized)** group with no members, linked to a synthesized `SYSTEM_OWNER` role. This group stands for the System API users and, on ZITADEL Cloud, ZITADEL's operators, who control the instance but can't be listed through its APIs.
* **Roles** - two kinds:
  * **Project roles** - the role keys defined on each project, and the users whose active authorizations carry them.
  * **Administrator roles** - ZITADEL administrator roles such as `IAM_OWNER`, `ORG_OWNER`, or `PROJECT_OWNER_VIEWER`, one per scope they apply to: the instance, an organization, a project, or a project grant. For example, `ORG_OWNER` on two organizations appears as two roles.
* **Applications** - each ZITADEL **project** is shown as an application, including the built-in ZITADEL project. The project lists the OIDC, SAML, and API applications it contains. Users get access to a project through active authorizations. If a project's **Check Role Assignment on Authentication** setting is off, users can sign in without an authorization, so Oleria also shows which organizations' users can sign in:
  * With **Check for Project on Authentication** on: the organization that owns the project, and organizations the project is granted to.
  * With it off: every organization in the instance.
* **Non-human identities (NHIs)**:

  * **Service accounts** - ZITADEL service accounts (machine users).
  * **API tokens** - personal access tokens of service accounts.
  * **Service account keys** - JSON keys of service accounts, and private keys of applications.
  * **Secrets** - client secrets of service accounts and of applications.
  * **Applications** - API applications, OIDC applications that use a client secret or private key, and SAML applications that have a key. Public clients, such as browser apps, aren't NHIs. Applications of the built-in ZITADEL project are shown as system accounts.
  * **System** - one synthesized account that stands for ZITADEL itself. Oleria uses it as the actor for events that ZITADEL writes, such as account lockouts.

  Tokens, keys, and secrets show the account they authenticate, and their creation and expiry dates when ZITADEL provides them. When the creation event is still in ZITADEL's audit log, Oleria also shows who created each NHI and makes that user its owner.
* **Activity** - events from ZITADEL's Event API, such as:

  * sign-ins and failed sign-ins (password, passkey, external identity provider, and second factors), and sign-outs
  * user creation, changes, deactivation, and lockouts
  * password changes and resets, and MFA enrollments
  * token, key, and secret creation, removal, and rotation
  * impersonation
  * authorization and administrator role changes
  * project, application, and organization changes
  * login, password, lockout, and identity provider policy changes

  Oleria leaves out the token events ZITADEL writes each time this integration's service accounts sign in. Changes those service accounts make, including remediation actions, are shown.

## Prerequisites

* A ZITADEL instance on ZITADEL Cloud (`*.zitadel.cloud`), a custom domain, or self-hosted.
* A ZITADEL instance administrator who can create service accounts and add instance administrators.
* The instance must be reachable from the internet over HTTPS on port 443. If your instance uses a custom domain or is self-hosted, Oleria must allow its host first. See [Known limitations](#known-limitations).
* Admin access on the Oleria platform to add a new integration.

### Permissions

Oleria reads with a service account that holds the **Instance Owner Viewer** (`IAM_OWNER_VIEWER`) administrator role. Each sync checks the service account's permissions first, and fails instead of saving data from lists that ZITADEL filtered by missing permissions. When you connect, Oleria refuses a service account that's missing any of these permissions and lists the missing ones:

`iam.read`, `iam.policy.read`, `iam.member.read`, `org.read`, `org.member.read`, `user.read`, `user.global.read`, `user.grant.read`, `policy.read`, `project.read`, `project.app.read`, `project.role.read`, `project.grant.read`, `project.member.read`, `project.grant.member.read`, and `events.read`.

`session.read` is optional. Without it, Oleria can't show a user's last activity, or the client IP address and browser on sign-in activity.

Remediation actions need write permissions, which `IAM_OWNER_VIEWER` doesn't grant. To use them, add a second service account with the **Instance Owner** (`IAM_OWNER`) role as the remediation credential. See [Remediation actions](#remediation-actions) for the permissions each action needs.

> [!NOTE]
>
> Use dedicated service accounts for this integration rather than a person's account. Oleria never deactivates, or removes credentials from, the service accounts it connects as.

## Create a service account in ZITADEL

**1. Create the service account**

Sign in to the ZITADEL console. In an organization, go to **Users** -> **Service Accounts** (**Service Users** in older consoles) and select **New**. Enter a username and a display name, such as `oleria-read`, and select **Create**.

**2. Grant the read role**

Open your instance from the top bar of the console. In the **Administrators** section on the right (**Managers** in older consoles), add the service account. If it's in a different organization than you're viewing, use the global search and enter its full login name. Select the **Instance Owner Viewer** (`IAM_OWNER_VIEWER`) role and save.

Grant the role on the instance, not on an organization. Only instance administrators can read users across all organizations.

**3. Create the credential**

Create the credential for the authentication method you want to use:

**Personal access token**

1. On the service account, open **Personal Access Tokens** and select **New**.
2. Optionally set an expiration date.
3. Copy the token. ZITADEL shows it only once.

**Service account key**

1. On the service account, open **Keys** and select **New**.
2. Optionally set an expiration date.
3. Download the JSON key file. ZITADEL can't show the private key again.

**Client credentials**

1. On the service account, open **Actions** in the top right corner and select **Generate Client Secret**.
2. Copy the **ClientID** and **ClientSecret**. ZITADEL shows the secret only once.

**4. Optional: create a remediation service account**

To take remediation actions from Oleria, repeat these steps for a second service account, such as `oleria-remediation`. Grant it the **Instance Owner** (`IAM_OWNER`) role, and create a credential of the same type as the first one. Oleria uses the same authentication method for both credentials.

> [!NOTE]
>
> The ZITADEL console changes over time. If these steps don't match what you see, refer to ZITADEL's guides on [accessing the ZITADEL APIs](https://zitadel.com/docs/guides/integrate/zitadel-apis/access-zitadel-apis) and [administrators](https://zitadel.com/docs/guides/manage/console/administrators).

## Connect ZITADEL to Oleria

**1. Open the integration**

Sign in to your Oleria workspace, navigate to **Integrations**, and select **ZITADEL**.

**2. Complete the connection form**

Select your authentication method, then fill in the fields for that method:

| Field | Notes |
| :- | :- |
| Instance URL | Required. The address of your ZITADEL instance, with no path, query, or credentials, for example `https://my-instance-abc123.us1.zitadel.cloud`. Custom domains and self-hosted instances are supported. Only port 443 is accepted. If you leave out `https://`, Oleria adds it. |
| Authentication method | Required. **Personal access token** (default), **Service account key**, or **Client credentials**. |
| Personal access token | Required for **Personal access token**. The token of the service account with `IAM_OWNER_VIEWER`. |
| Service account key (JSON) | Required for **Service account key**. The full contents of the JSON key file, which includes `type` (`serviceaccount`), `keyId`, `userId`, and `key`. |
| Client ID | Required for **Client credentials**. The client ID shown when you generated the service account's client secret. |
| Client secret | Required for **Client credentials**. The service account's client secret. |
| Remediation personal access token (optional) | **Personal access token** only. The token of the remediation service account. |
| Remediation service account key (optional) | **Service account key** only. The JSON key file contents of the remediation service account. |
| Remediation client ID (optional) | **Client credentials** only. The client ID of the remediation service account. Enter it together with the remediation client secret. |
| Remediation client secret (optional) | **Client credentials** only. The client secret of the remediation service account. Enter it together with the remediation client ID. |

Leave the remediation fields empty to run actions with the read credential. With an `IAM_OWNER_VIEWER` read credential, actions then aren't available.

**3. Authenticate**

Select **Authenticate**. Oleria signs in with the read credential and reads its permissions and your instance. If any required permission from [Permissions](#permissions) is missing, the connection fails with a message that lists the missing permissions.

If you entered a remediation credential, Oleria also checks that it can sign in. A remediation credential that's missing some action permissions is still saved, and those actions show as **Needs permission**.

### Edit the connection

You can change the instance URL, authentication method, and credentials of an existing connection, but you can't point it at a different ZITADEL instance. If the new credentials belong to another instance, Oleria refuses the change. To connect a different instance, add a new integration.

* **Secrets:** Leave a secret field blank to keep the stored value. Oleria keeps stored secrets only while the instance URL and authentication method stay the same. If you change either one, enter the credentials again. For **Client credentials**, also enter a new client secret if you change the client ID, and a new remediation client secret if you change the remediation client ID.
* **Removing the remediation credential:** Select **Remove stored remediation credential**, then select **Update**. Actions then run with the read credential. Leaving the remediation fields blank keeps the stored remediation credential.

## Verify the integration

Confirm the ZITADEL instance appears on the **Connected** tab of your Oleria **Integrations** page. The connection is named after your ZITADEL instance. After the first sync completes, review the discovered users, organizations, roles, projects, NHIs, and activity in your Oleria workspace.

## Remediation actions

Oleria runs actions with the remediation credential, or with the read credential if you didn't add one. Each action is available only when that credential has the action's permissions. The **Instance Owner** (`IAM_OWNER`) role grants all of them.

| Action | What it does | Revert |
| :- | :- | :- |
| Disable user accounts | Deactivates a human user or service account. | Supported - reactivates the user, if the user was active before the action. |
| Enable user accounts | Reactivates a deactivated user. A locked user, or a user who hasn't finished initial sign-up, is refused. | Supported - deactivates the user again. |
| Activate user accounts | Unlocks a locked user. A deactivated user, or a user who hasn't finished initial sign-up, is refused. | Supported - locks the user again. |
| Delete user | Permanently deletes the user. | Not supported. |
| Revoke user sessions | Deletes every session of the user. | Not supported - the user signs in again to start a new session. |
| Assign user to application entitlement | Gives the user access to a project. If the user has a deactivated authorization for the project, Oleria reactivates it, which also restores the project roles it carried. Otherwise, Oleria creates an authorization with no roles; on a project with **Check Role Assignment on Authentication** on, add a role too, because ZITADEL only lets users with a role sign in. | Supported - deactivates the reactivated authorization, or deletes the created one if it hasn't changed since. |
| Remove user from application entitlement | Deactivates every active authorization the user has on the project. ZITADEL keeps the role keys, so access can be restored. | Supported - reactivates the authorizations. |
| Add user to role | For a project role, adds the role key to the user's active authorization on the project, or creates an authorization with that role. For an administrator role, adds the role to the user's administrator roles on that scope. | Supported - restores the user's previous roles, or deletes what the action created. |
| Remove user from role | For a project role, removes the role key from every active authorization of the user on the project. For an administrator role, removes the role, and removes the user as an administrator of that scope if it was their last role. | Supported - restores the user's previous roles. |
| Disable NHI accounts - service account | Deactivates the service account. | Supported - reactivates the service account, if it was active before the action. |
| Disable NHI accounts - API token | Permanently deletes the personal access token. | Not supported. |
| Disable NHI accounts - service account key | Permanently deletes a service account's key or an application's key. | Not supported. |
| Disable NHI accounts - application | Deactivates the application. | Supported - reactivates the application. |

Each action needs these ZITADEL permissions:

| Action | Required permissions |
| :- | :- |
| Disable user accounts, Enable user accounts, Activate user accounts | `user.read`, `user.write`, `iam.member.read` |
| Delete user | `user.read`, `user.delete`, `iam.member.read` |
| Revoke user sessions | `user.read`, `session.read`, `session.delete` |
| Assign user to application entitlement | `user.read`, `user.grant.read`, `user.grant.write`, `user.grant.delete`, `project.read` |
| Remove user from application entitlement | `user.read`, `user.grant.read`, `user.grant.write`, `project.read` |
| Add user to role, Remove user from role | `user.read`, `user.grant.read`, `user.grant.write`, `user.grant.delete`, `project.read`, `project.role.read`, and `read`, `write`, and `delete` on `iam.member`, `org.member`, `project.member`, and `project.grant.member` |
| Disable NHI accounts | `user.read`, `user.write`, `iam.member.read`, `project.read`, `project.app.read`, `project.app.write` |

> [!WARNING]
>
> Deleting a personal access token or a key is permanent in ZITADEL. Anything that uses it stops working, and you have to create a new credential in ZITADEL.

Oleria refuses these actions and sends no change to ZITADEL:

* Any change to the service accounts this integration connects as, including deleting their tokens, keys, or secrets.
* Deactivating or deleting the last active user with the `IAM_OWNER` role, or removing `IAM_OWNER` from them, because that would lock out the instance's administrators. The service accounts this integration connects as don't count as other owners.
* Deactivating or deleting a user with the instance `IAM_LOGIN_CLIENT` role, removing that role, or deleting that user's tokens, keys, or secrets, because ZITADEL's hosted login depends on them.
* Changing access or project roles on the built-in ZITADEL project, deactivating its applications, or deleting their keys. These control access to the ZITADEL console and APIs.
* Changing a deleted user.
* Adding a project role for a user whose access to the project is deactivated. Assign the application to the user first, then add the role.
* Adding users to, or removing users from, the synthesized `SYSTEM_OWNER` role.
* Disabling the synthesized system account.

Keep these points in mind:

* If the user is already in the requested state, the action succeeds without making a change, and there's nothing to revert.
* If ZITADEL returns an error but the change was applied, the action is reported as successful and can still be reverted.
* **Revoke user sessions** deletes the user's sessions one at a time. If ZITADEL fails partway, the action fails and reports how many sessions it revoked. Run it again to revoke the rest.
* Reverting a user state, role, or created authorization checks the target first. If it changed after the action ran, Oleria leaves it as is; restore it manually in ZITADEL instead. Reverting an entitlement removal or reactivation switches the authorization's state back without comparing its roles.
* **Remove user from application entitlement** doesn't block sign-in to a project whose **Check Role Assignment on Authentication** setting is off. The user can still sign in if their organization has access to the project. Check the project's settings in ZITADEL before relying on this action to cut access.

## Known limitations

* **No native ZITADEL groups.** ZITADEL's Group API is still under development, so Oleria shows organizations as groups instead. Users can't be moved between organizations through the API, so there are no group membership actions.
* **Last activity comes from recent sessions only.** ZITADEL keeps no last sign-in date, so Oleria sets a user's last activity from their sessions created in the last 90 days. Users who haven't signed in during that time show no last activity. Sign-ins also appear as activity.
* **No last-used date for non-human identities.** ZITADEL doesn't record when a service account, token, key, or secret was last used.
* **No authenticator objects.** ZITADEL's factor APIs don't record when a user enrolled a second factor or passkey, so Oleria shows enrolled factors as the user's authentication methods instead of as separate authenticators.
* **IP address and browser on sign-ins only.** Oleria reads them from the ZITADEL Session API. Sign-in activity shows the browser and operating system, and the client IP address when ZITADEL stored one on the sign-in's session. ZITADEL deletes sessions at logout or expiry, so older sign-ins may have neither. ZITADEL Cloud's hosted login doesn't store the client IP address on the session, so sign-ins there usually show only the browser and operating system. Admin change activity has no IP address, because ZITADEL events don't record one.
* **Activity history depends on your ZITADEL plan.** ZITADEL returns events only within your plan's audit log retention. This also limits which NHIs show their creator and owner.
* **Oleria's own sign-ins aren't shown as activity.** The token events ZITADEL writes each time the integration's service accounts sign in are excluded. Changes those service accounts make, including remediation actions, are shown.
* **Custom domains and self-hosted instances need allowlisting.** Oleria can connect to `*.zitadel.cloud` and `*.zitadel.com` hosts. For any other host, contact [support@oleria.com](mailto:support@oleria.com) to add it before you connect. The instance must be reachable from the internet over HTTPS on port 443. If ZITADEL listens on another port, such as its default 8080, publish it on 443 through a reverse proxy or load balancer first. Addresses that resolve to private or loopback IP addresses are refused.
* **Client secrets can't be disabled from Oleria.** ZITADEL can only rotate an application's client secret, which creates a new secret. To stop an application from authenticating, use **Disable NHI accounts - application**. To revoke a service account's client secret, disable the service account.
* **System administrators can't be listed.** System API users and, on ZITADEL Cloud, ZITADEL's operators don't appear in any instance API. Oleria represents them with the synthesized system administrators group, which has no members.
* **Account creation isn't supported.** Oleria changes existing users and their access, but doesn't create users in ZITADEL.

## Contact us

For questions about this integration, contact us at [support@oleria.com](mailto:support@oleria.com).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.