mirror of
https://github.com/andwati/zitadel.git
synced 2026-10-18 05:52:51 +00:00
8dac4e2b54
# Which Problems Are Solved - Operators lack a single guide for separating instance-level principals (break-glass, login client) from tenant organizations. - Login policy and IdP behavior for platform accounts is easy to conflate with customer org settings when admins share one organization. - There is no documented procedure to inventory instance administrators or detect unexpected grants over time. # How the Problems Are Solved - Add Hardening instance administrators covering: - Dedicated platform organization layout and why login, password, and lockout policies matter for operator accounts. - Login client (`IAM_LOGIN_CLIENT`) and break-glass (`IAM_OWNER`) hygiene. - Periodic review with Internal Permission Service v2 `ListAdministrators` (instance and platform org filters). - Actions v2 webhooks for `instance.member.*` and `org.member.*` events (with payload interpretation and alert hints). - Event API polling alternative for SIEM/batch pipelines (`instance.member.*` and platform-org `org.member.*`). - Register the page in the docs sidebar under Roles & Permissions. - Cross-link from administrators, production checklists, login-client setup, and service account authentication guides. # Additional Changes - Clarify instance vs org IdP availability depends on effective login policy and linked providers (not automatic for all orgs). - Note deprecated Admin API `POST /admin/v1/members/_search` vs v2 `ListAdministrators`. # Additional Context - Operational hardening guide only (no product authz changes). --------- Co-authored-by: Cursor <[email protected]>
79 lines
6.2 KiB
Plaintext
79 lines
6.2 KiB
Plaintext
---
|
|
title: ZITADEL Administrators
|
|
description: "Manage administrators and their roles within ZITADEL instances and organizations."
|
|
sidebar_label: Administrators
|
|
---
|
|
|
|
import AdministratorDescription from "../../../concepts/structure/_administrator_description.mdx";
|
|
import AddAdministrator from "./_add_administrator.mdx";
|
|
import PermissionTable from '@/components/PermissionTable';
|
|
import permissionData from "../../../../../../cmd/defaults.yaml";
|
|
|
|
<TerminologyUpdate
|
|
newTerm="Administrators"
|
|
oldTerms={["Members", "Memberships", "Managers"]}
|
|
/>
|
|
|
|
<AdministratorDescription components={props.components} name="AdministratorDescription" />
|
|
|
|
To configure administrators in ZITADEL, go to the resource where you like to add it (e.g., Instance, Organization, Project, GrantedProject).
|
|
In the right part of the management console you can find **ADMINISTRATORS** in the details part. Here you have a list of the current administrators and can add a new one.
|
|
|
|
<img alt="Administrators" src="/docs/img/guides/console/administrators.png" width="200px" />
|
|
|
|
<AddAdministrator components={props.components} name="AddAdministrator" />
|
|
|
|
<Callout type="info">
|
|
For separation of instance administrators from application organizations, login settings alignment, and login client hygiene, see [Hardening instance administrators](/guides/manage/console/administrator-hardening).
|
|
</Callout>
|
|
|
|
## Roles
|
|
|
|
| Name | Role | Description |
|
|
|-------------------------------|-------------------------------|--------------------------------------------------------------------------------------------------------------|
|
|
| Instance Owner | IAM_OWNER | Manage the Instance, manage all organizations with their content |
|
|
| Instance Owner Viewer | IAM_OWNER_VIEWER | View the Instance and view all organizations with their content |
|
|
| Instance Org Manager | IAM_ORG_MANAGER | Manage all organizations including their policies, projects and users |
|
|
| Instance User Manager | IAM_USER_MANAGER | Manage all users and their authorizations over all organizations |
|
|
| Instance Admin Impersonator | IAM_ADMIN_IMPERSONATOR | Allow impersonation of admin and end users from all organizations |
|
|
| Instance Impersonator | IAM_END_USER_IMPERSONATOR | Allow impersonation of end users from all organizations |
|
|
| Instance Login Client | IAM_LOGIN_CLIENT | Get all permissions needed to implement your own Login UI. |
|
|
| Org Owner | ORG_OWNER | Manage everything within an organization |
|
|
| Org Owner Viewer | ORG_OWNER_VIEWER | View everything within an organization |
|
|
| Org User Manager | ORG_USER_MANAGER | Manage users and their authorizations within an organization |
|
|
| Org User Permission Editor | ORG_USER_PERMISSION_EDITOR | Manage user grants and view everything needed for this |
|
|
| Org Project Permission Editor | ORG_PROJECT_PERMISSION_EDITOR | Grant Projects to other organizations and view everything needed for this |
|
|
| Org Project Creator | ORG_PROJECT_CREATOR | This role is used for users in the global organization. They are allowed to create projects and manage them. |
|
|
| Org Dynamic Client Registrar | ORG_DYNAMIC_CLIENT_REGISTRAR | Register OAuth 2.0 clients through the [dynamic client registration](/guides/integrate/dynamic-client-registration) endpoint, and nothing else |
|
|
| Org Admin Impersonator | ORG_ADMIN_IMPERSONATOR | Allow impersonation of admin and end users from the organization |
|
|
| Org Impersonator | ORG_END_USER_IMPERSONATOR | Allow impersonation of end users from the organization |
|
|
| Project Owner | PROJECT_OWNER | Manage everything within a project. This includes to grant users for the project. |
|
|
| Project Owner Viewer | PROJECT_OWNER_VIEWER | View everything within a project. |
|
|
| Project Owner Global | PROJECT_OWNER_GLOBAL | Same as PROJECT_OWNER, but in the global organization. |
|
|
| Project Owner Viewer Global | PROJECT_OWNER_VIEWER_GLOBAL | Same as PROJECT_OWNER_VIEWER, but in the global organization. |
|
|
| Project Grant Owner | PROJECT_GRANT_OWNER | Same as PROJECT_OWNER but for a granted project. |
|
|
| Org User Self Manager | ORG_USER_SELF_MANAGER | Grants a user permission to read policies and delete their own account. |
|
|
| Self Management Global | SELF_MANAGEMENT_GLOBAL | Grants a user permission to create organizations, read policies, and delete their own account, in the global organization. |
|
|
|
|
## Configure roles
|
|
|
|
If you run a self-hosted ZITADEL instance, you can define your custom roles by overwriting the defaults.yaml
|
|
In the InternalAuthZ section you will find all the roles and which permissions they have.
|
|
|
|
Example:
|
|
|
|
```bash
|
|
InternalAuthZ:
|
|
RolePermissionMappings:
|
|
- Role: "IAM_OWNER"
|
|
Permissions:
|
|
- "iam.read"
|
|
- "iam.write"
|
|
```
|
|
|
|
## Administrator Permission Matrix
|
|
|
|
This table is generated dynamically from our settings file.
|
|
|
|
<PermissionTable data={permissionData} />
|