diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 000000000..48a8ce1b6 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1 @@ +Always respect the terminology defined in the 'Technical Glossary' section of agents.md when generating UI text or documentation. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fe79cd639..cd027016c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -423,7 +423,7 @@ If you don't want to build and run a local API, you can just run the Login devel ```env ZITADEL_API_URL=https://[your-cloud-instance-domain] -ZITADEL_SERVICE_USER_TOKEN=[personal access token for an IAM Login Client] +ZITADEL_SERVICE_USER_TOKEN=[personal access token for an instance Login Client] ``` 3. Start the development server. diff --git a/agents.md b/agents.md new file mode 100644 index 000000000..4b162a8f0 --- /dev/null +++ b/agents.md @@ -0,0 +1,45 @@ +## ZITADEL Domain & Multi-Tenancy Logic + +### 1. Hierarchy & Ownership + +ZITADEL follows a strict hierarchical containment model. When generating code, logic, or translations, adhere to this structure: + +- **System (Installation):** The entire ZITADEL deployment. Global settings are applied through runtime configuration files or environment variables. See `cmd/defaults.yaml`. +- **Instance (The "Identity System"):** + - **Definition:** A logical partition/virtual tenant. It is a "System inside a System." + - **Isolation:** Data and configurations are strictly isolated between instances. + - **Translation Rule:** NEVER translate as "Example" or "Case." Use technical terms like "Tenant," "Environment," or the local equivalent of "Logical System Entity." +- **Organization:** A group within an Instance. It owns Users, Projects, and Roles. +- **Project:** A collection of Applications and Auth Policies within an Org. + +### 2. Permission Scoping (The "Administrative" Context) + +- **System User:** Manages the entire Installation and creates Instances over the system API. +- **Instance Admin:** Manages Instance-wide policies (Password complexity, Identity Providers, Organizations). +- **Organization Admin:** Manages users and access within a specific Organization. + +### 3. Language & Tone Guidelines + +- **Avoid Ambiguity:** When referring to an 'Instance', the context is always infrastructure/tenancy. +- **Technical Precision:** In UI strings, prefer clarity over brevity if "Instance" is likely to be misinterpreted in the target language. + +### 4. Technical Glossary & Localization Mapping + +| Language | Technical Term (SaaS/Cloud) | Why this term? | "Avoid this (The ""Example"" Trap)" | +| -------------------- | --------------------------- | --------------------------------------------------------- | ----------------------------------- | +| Chinese (Simplified) | 实例 (Shílì) | Standard for a cloud resource/entity. | 例子 (Lìzi) | +| Japanese | インスタンス (Insutansu) | Katakana transliteration; industry standard. | 例 (Rei) | +| Korean | 인스턴스 (Inseuteonseu) | Hangul transliteration; industry standard. | 예 (Ye) | +| German | Instanz | Matches English but implies a technical occurrence. | Beispiel | +| French | Instance | "Standard but often requires ""de ZITADEL"" for clarity." | Exemple | +| Spanish | Instancia | Technical entity in software architecture. | Ejemplo | +| Portuguese | Instância | Standard technical terminology. | Exemplo | +| Russian | Инстанс (Instans) | Modern SaaS jargon (transliterated). | Пример (Primer) | + +#### Translation Guardrails +If a translation is requested for a language not listed above, follow these priority rules for the word 'Instance': + +1. **Priority 1 (Transliteration):** Use the phonetic transliteration into the local script (common in Japanese/Korean/Russian). +2. **Priority 2 (System Entity):** Use a term that implies a "running process" or "logical environment." +3. **Priority 3 (Tenant):** If 'Instance' is ambiguous, use the local word for 'Tenant' (e.g., 租户 in Chinese). +4. **Strict Ban:** NEVER use words that mean "an illustration", "a case", "a sample", or "an example." diff --git a/apps/api/prod-default.yaml b/apps/api/prod-default.yaml index 406eae4c9..078befae7 100644 --- a/apps/api/prod-default.yaml +++ b/apps/api/prod-default.yaml @@ -16,11 +16,11 @@ FirstInstance: LoginClient: Machine: Username: login-client - Name: Automatically Initialized IAM Login Client + Name: Automatically Initialized instance Login Client Pat.ExpirationDate: 2099-01-01T00:00:00Z Machine: Machine: Username: admin - Name: Automatically Initialized IAM admin Client + Name: Automatically Initialized instance admin Client Pat.ExpirationDate: 2099-01-01T00:00:00Z DefaultInstance.Features.LoginV2.BaseURI: http://localhost:3000/ui/v2/login diff --git a/apps/docs/content/apis/introduction.mdx b/apps/docs/content/apis/introduction.mdx index 4e963407d..4e5b42ada 100644 --- a/apps/docs/content/apis/introduction.mdx +++ b/apps/docs/content/apis/introduction.mdx @@ -111,7 +111,7 @@ API Reference: ### Management -The management API is as the name states the interface where systems can mutate IAM objects like, organizations, projects, applications, users and so on if they have the necessary access rights. +The management API is as the name states the interface where systems can mutate instance objects like, organizations, projects, applications, users and so on if they have the necessary access rights. To identify the current organization you can send a header `x-zitadel-orgid` or if no header is set, the organization of the authenticated user is set. diff --git a/apps/docs/content/apis/openidoauth/scopes.mdx b/apps/docs/content/apis/openidoauth/scopes.mdx index 3cf16e83f..4e433d861 100644 --- a/apps/docs/content/apis/openidoauth/scopes.mdx +++ b/apps/docs/content/apis/openidoauth/scopes.mdx @@ -3,7 +3,7 @@ title: Scopes in ZITADEL sidebar_label: Scopes --- -ZITADEL supports the usage of scopes as way of requesting information from the IAM and also instruct ZITADEL to do certain operations. +ZITADEL supports the usage of scopes as way of requesting information from the instance and also instruct ZITADEL to do certain operations. ## Standard Scopes diff --git a/apps/docs/content/apis/scim2.mdx b/apps/docs/content/apis/scim2.mdx index 2f0fc0f9c..de062b767 100644 --- a/apps/docs/content/apis/scim2.mdx +++ b/apps/docs/content/apis/scim2.mdx @@ -3,9 +3,9 @@ title: SCIM v2.0 (Preview) --- The Zitadel [SCIM v2](https://scim.cloud/) service provider interface enables seamless integration of identity and -access management (IAM) systems with Zitadel, +access management (instance) systems with Zitadel, following the System for Cross-domain Identity Management (SCIM) v2.0 specification. -This interface allows standardized management of IAM resources, making it easier to automate user provisioning and +This interface allows standardized management of instance resources, making it easier to automate user provisioning and deprovisioning. ## Supported endpoints diff --git a/apps/docs/content/concepts/architecture/solution.mdx b/apps/docs/content/concepts/architecture/solution.mdx index 364bb202a..08c72b78b 100644 --- a/apps/docs/content/concepts/architecture/solution.mdx +++ b/apps/docs/content/concepts/architecture/solution.mdx @@ -31,7 +31,7 @@ Simply steer traffic by path, hostname, IP address or any other metadata to the ### Single Cluster / Region -A Zitadel Cluster is a highly available IAM system with each component critical for serving traffic laid out at least three times. +A Zitadel Cluster is a highly available instance system with each component critical for serving traffic laid out at least three times. Our storage layer (Postgres) is built for single region deployments. Hence our reference design for Kubernetes is to have three application nodes and one storage node. diff --git a/apps/docs/content/concepts/structure/_org_description.mdx b/apps/docs/content/concepts/structure/_org_description.mdx index 255968d55..accd77110 100644 --- a/apps/docs/content/concepts/structure/_org_description.mdx +++ b/apps/docs/content/concepts/structure/_org_description.mdx @@ -1,7 +1,7 @@ ZITADEL is organized around the idea that: * Multiple organizations can be managed within one [instance](/concepts/structure/instance). -* organizations can grant each other rights to self-manage certain aspects of the IAM (eg, roles for access management) +* organizations can grant each other rights to self-manage certain aspects of the instance (eg, roles for access management) * organizations are vessels for users and projects ![](../../../public/img/concepts/objects/organization.png) diff --git a/apps/docs/content/guides/integrate/token-exchange.mdx b/apps/docs/content/guides/integrate/token-exchange.mdx index f95ed6339..ea21c043b 100644 --- a/apps/docs/content/guides/integrate/token-exchange.mdx +++ b/apps/docs/content/guides/integrate/token-exchange.mdx @@ -433,7 +433,7 @@ This gives us a response with the ID token in the `access_token` field and the ` With impersonation we can let one user assume the role of another user. -Currently impersonated tokens cannot be used for the ZITADEL API. This is to prevent privilege escalation where a impersonator could become an IAM owner, for example. We might enable the use of impersonated tokens in the future. +Currently impersonated tokens cannot be used for the ZITADEL API. This is to prevent privilege escalation where a impersonator could become an instance owner, for example. We might enable the use of impersonated tokens in the future. ### Preparation @@ -452,8 +452,8 @@ Next we need to configure which users are allowed to impersonate other users. ZI | Name | Role | Description | | ---------------------- | ------------------------- | ----------------------------------------------------------------- | -| IAM Admin Impersonator | IAM_ADMIN_IMPERSONATOR | Allow impersonation of admin and end users from all organizations | -| IAM Impersonator | IAM_END_USER_IMPERSONATOR | Allow impersonation of end users from 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 | | 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 | diff --git a/apps/docs/content/guides/integrate/zitadel-apis/access-zitadel-apis.mdx b/apps/docs/content/guides/integrate/zitadel-apis/access-zitadel-apis.mdx index 71c8e0325..9082be8a7 100644 --- a/apps/docs/content/guides/integrate/zitadel-apis/access-zitadel-apis.mdx +++ b/apps/docs/content/guides/integrate/zitadel-apis/access-zitadel-apis.mdx @@ -65,7 +65,7 @@ Via APIs23: * [Create User (Machine)](/reference/api/management/zitadel.manageme ZITADEL Managers are Users who have permission to manage ZITADEL itself. There are some different levels for managers. -- **IAM Managers**: This is the highest level. Users with IAM Administrator roles are able to manage the whole instance. +- **Instance Managers**: This is the highest level. Users with IAM Administrator roles are able to manage the whole instance. - **Org Managers**: Managers in the Organization Level are able to manage everything within the granted Organization. - **Project Managers**: At this level, the user is able to manage a project. - **Project Grant Manager**: The project grant manager is for projects, which are granted of another organization. diff --git a/apps/docs/content/guides/manage/console/managers.mdx b/apps/docs/content/guides/manage/console/managers.mdx index b1dbedad4..2cad7473a 100644 --- a/apps/docs/content/guides/manage/console/managers.mdx +++ b/apps/docs/content/guides/manage/console/managers.mdx @@ -21,13 +21,13 @@ In the right part of the management console you can find **MANAGERS** in the det | Name | Role | Description | | ----------------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------ | -| IAM Owner | IAM_OWNER | Manage the IAM, manage all organizations with their content | -| IAM Owner Viewer | IAM_OWNER_VIEWER | View the IAM and view all organizations with their content | -| IAM Org Manager | IAM_ORG_MANAGER | Manage all organizations including their policies, projects and users | -| IAM User Manager | IAM_USER_MANAGER | Manage all users and their authorizations over all organizations | -| IAM Admin Impersonator | IAM_ADMIN_IMPERSONATOR | Allow impersonation of admin and end users from all organizations | -| IAM Impersonator | IAM_END_USER_IMPERSONATOR | Allow impersonation of end users from all organizations | -| IAM Login Client | IAM_LOGIN_CLIENT | Get all permissions needed to implement your own Login UI. | +| 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 | diff --git a/apps/docs/content/guides/manage/user/scim2.mdx b/apps/docs/content/guides/manage/user/scim2.mdx index 515e270f8..380630ae9 100644 --- a/apps/docs/content/guides/manage/user/scim2.mdx +++ b/apps/docs/content/guides/manage/user/scim2.mdx @@ -2,7 +2,7 @@ title: SCIM v2.0 --- -Zitadel’s **[SCIM v2](https://scim.cloud/) service provider interface** enables standardized provisioning and lifecycle management of users and other IAM resources. +Zitadel’s **[SCIM v2](https://scim.cloud/) service provider interface** enables standardized provisioning and lifecycle management of users and other instance resources. By implementing the official *System for Cross-domain Identity Management (SCIM) v2.0* specification, Zitadel allows seamless and automated user creation, updates, deactivation, and deprovisioning across systems. ## API diff --git a/apps/docs/content/guides/migrate/sources/zitadel.mdx b/apps/docs/content/guides/migrate/sources/zitadel.mdx index 5da5d2c7e..e067546d4 100644 --- a/apps/docs/content/guides/migrate/sources/zitadel.mdx +++ b/apps/docs/content/guides/migrate/sources/zitadel.mdx @@ -14,7 +14,7 @@ This guide explains how to migrate from ZITADEL, this includes The following scripts don't include: - Global policies -- IAM members +- Instance members - Global IDPs - Global second factor / multi-factors - Machine keys @@ -30,7 +30,7 @@ Note that the resources will be migrated without the event stream. This means th ## Authorization -You need a PAT from a service user with IAM Owner permissions in both the source and target system. +You need a PAT from a service user with instance Owner permissions in both the source and target system. ### Source system @@ -38,7 +38,7 @@ You need a PAT from a service user with IAM Owner permissions in both the source 2. Create a service user "import_user" with Access Token Type "Bearer" 3. Create a [personal access token](/guides/integrate/service-accounts/personal-access-token) 4. Go to the Default settings -5. Add the import_user as [manager](/guides/manage/console/managers) with the role "IAM Owner" +5. Add the import_user as [manager](/guides/manage/console/managers) with the role "instance Owner" Save the PAT to the environment variable `PAT_EXPORT_TOKEN` and the source domain as `ZITADEL_EXPORT_DOMAIN` to run the following scripts. @@ -48,7 +48,7 @@ Save the PAT to the environment variable `PAT_EXPORT_TOKEN` and the source domai 2. Create a service user "export_user" with Access Token Type "Bearer" 3. Create a [personal access token](/guides/integrate/service-accounts/personal-access-token) 4. Go to the Default settings -5. Add the export_user as [manager](/guides/manage/console/managers) with the role "IAM Owner" +5. Add the export_user as [manager](/guides/manage/console/managers) with the role "instance Owner" Save the PAT to the environment variable `PAT_IMPORT_TOKEN` and the source domain as `ZITADEL_IMPORT_DOMAIN` to run the following scripts. diff --git a/apps/docs/content/legal/service-description/support-services.mdx b/apps/docs/content/legal/service-description/support-services.mdx index 451b28357..ebc6cddca 100644 --- a/apps/docs/content/legal/service-description/support-services.mdx +++ b/apps/docs/content/legal/service-description/support-services.mdx @@ -171,7 +171,7 @@ Topics of the onboarding term may include