Skip to main content
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.
  • 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 for the permissions each action needs.
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:
  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.
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.
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 and 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: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 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. Each action needs these ZITADEL permissions:
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 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.