diff --git a/docs/admin/security/roles-rbac.md b/docs/admin/security/roles-rbac.md index 702b63b7..c0e87eef 100644 --- a/docs/admin/security/roles-rbac.md +++ b/docs/admin/security/roles-rbac.md @@ -14,13 +14,14 @@ The platform roles and their mapping to Keycloak realm roles and user attributes ## Roles in CodeMie -Five role levels are defined in CodeMie: +Six role levels are defined in CodeMie: 1. **Maintainer** 2. **Admin** 3. **Project Admin** 4. **Regular User** -5. **External User** +5. **Invoker** +6. **External User** ## How Keycloak Access Is Interpreted @@ -52,28 +53,49 @@ Five role levels are defined in CodeMie: ## Role Descriptions -| Capability / Scope | Maintainer | Admin | Project Admin | Regular User | External User | -| -------------------------------------------------------- | ----------------------------------------------------------------- | --------------------------------------- | ------------------------------------------------------------ | ---------------------------------------- | ------------------------------------------------------ | -| Role level | Highest operational role | Platform-wide administrative role | Project-scoped administrative role | Standard user role | Special user type for guest/external scenarios | -| Platform-wide admin access | ✅ | ✅ | ❌ | ❌ | ❌ | -| Manage users and access assignments across the platform | ✅ | ✅ | ❌ | ❌ | ❌ | -| Manage key platform settings and operational views | ✅ | ✅ | ❌ | ❌ | ❌ | -| Manage budget and billing controls | ✅ (exclusive) | ❌ | ❌ | ❌ | ❌ | -| Manage members and project-level access | ✅ | ✅ | ✅ (managed projects only) | ❌ | ❌ | -| View project-level analytics (including spending trends) | ✅ | ✅ | ✅ (managed projects only) | ❌ | ❌ | -| View own usage and spending analytics | ✅ | ✅ | ✅ | ✅ | ✅ (where access is allowed) | -| Access scope | Platform-wide | Platform-wide | Assigned projects only | Assigned projects and knowledge sources | Regular-user scope with stricter limits where required | -| Assignment model | Assigned in CodeMie directly (not a separate Keycloak realm role) | Granted via Keycloak `admin` realm role | Derived from project attributes such as `applications_admin` | Derived from standard access assignments | Determined by external/guest user classification | +| Capability / Scope | Maintainer | Admin | Project Admin | Regular User | Invoker | External User | +| -------------------------------------------------------- | ----------------------------------------------------------------- | --------------------------------------- | ------------------------------------------------------------ | ---------------------------------------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------------ | +| Role level | Highest operational role | Platform-wide administrative role | Project-scoped administrative role | Standard user role | Run-only, least-privileged role | Special user type for guest/external scenarios | +| Platform-wide admin access | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | +| Manage users and access assignments across the platform | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | +| Manage key platform settings and operational views | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | +| Manage budget and billing controls | ✅ (exclusive) | ❌ | ❌ | ❌ | ❌ | ❌ | +| Manage members and project-level access | ✅ | ✅ | ✅ (managed projects only) | ❌ | ❌ | ❌ | +| View project-level analytics (including spending trends) | ✅ | ✅ | ✅ (managed projects only) | ❌ | ❌ | ❌ | +| View own usage and spending analytics | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ (where access is allowed) | +| Create and configure assistants, workflows, and skills | ✅ | ✅ | ✅ | ✅ | ❌ (run shared ones and clone from Marketplace only) | ✅ (where access is allowed) | +| View assistant and workflow configuration | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ (where access is allowed) | +| Change the LLM model in a chat | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ (where access is allowed) | +| Manage personal integrations | ✅ | ✅ | ✅ | ✅ | ✅ (only credential types required by an accessible assistant) | ✅ (where access is allowed) | +| Access scope | Platform-wide | Platform-wide | Assigned projects only | Assigned projects and knowledge sources | Assigned projects only; every action is audited | Regular-user scope with stricter limits where required | +| Assignment model | Assigned in CodeMie directly (not a separate Keycloak realm role) | Granted via Keycloak `admin` realm role | Derived from project attributes such as `applications_admin` | Derived from standard access assignments | Assigned in CodeMie directly (`is_invoker` flag); exclusive with all administrative roles | Determined by external/guest user classification | ## Role Hierarchy ``` -Maintainer ──► Admin ──► Project Admin ──► Regular User - │ │ - │ └── Full platform access - └── Budget/billing management (exclusive) +Maintainer ──► Admin ──► Project Admin ──► Regular User ──► Invoker + │ │ │ + │ └── Full platform access └── Run-only: no configuration + └── Budget/billing management (exclusive) visibility, no authoring ``` +## Invoker Role + +The **Invoker** sits below the Regular User. It is meant for people who should run assistants +and workflows that others have built, without seeing prompts, tools, models, data sources, or +any platform configuration. The interface is reduced to a chat-first experience. + +- **Assignment**: set directly in CodeMie from Users Management (`is_invoker` flag on the user + account). It is not derived from Keycloak roles or attributes. +- **Exclusivity**: cannot be combined with Maintainer, Admin, Auditor, or Project Admin. +- **Prerequisite**: activity events (`ACTIVITY_EVENTS_ENABLED=True`) must be enabled; every + Invoker action and every denied request is written to the audit trail. +- **Enforcement**: the backend denies every API route outside the Invoker allow-list with + **Access denied**, so the restriction holds for direct API access as well as for the UI. + +See [Invoker Role](../../user-guide/project-user-management/invoker-role.md) for the full list +of permitted and restricted actions. + :::info For step-by-step instructions on assigning roles and attributes in Keycloak, see the [Access Control](../configuration/access-control/index.md) section. diff --git a/docs/user-guide/getting-started/glossary.md b/docs/user-guide/getting-started/glossary.md index 32297e8e..e9917278 100644 --- a/docs/user-guide/getting-started/glossary.md +++ b/docs/user-guide/getting-started/glossary.md @@ -139,6 +139,10 @@ A configured connection between the CodeMie platform and an external service or See [Default Integration](#default-integration) for how CodeMie selects one automatically when none is explicitly chosen. +### Invoker + +The least-privileged platform role, identified by the `is_invoker` flag on the user account. An Invoker can chat with assistants and run workflows shared with their projects, clone Marketplace assistants into their personal project, and manage personal integrations, but cannot view or edit any assistant or workflow configuration, change the LLM model, author anything, or open administration screens. The role is assigned in Users Management, is mutually exclusive with Admin, Maintainer, Auditor, and Project Admin, and requires activity events to be enabled because every Invoker action is audited. See [Invoker Role](../project-user-management/invoker-role.md). + --- ## J diff --git a/docs/user-guide/project-user-management/index.mdx b/docs/user-guide/project-user-management/index.mdx index a9ea8be1..74cd22d1 100644 --- a/docs/user-guide/project-user-management/index.mdx +++ b/docs/user-guide/project-user-management/index.mdx @@ -46,16 +46,27 @@ for setup instructions. description="View all platform users, inspect individual user details, manage project assignments. Available to Platform Admins." link="/user-guide/project-user-management/users" /> + ## Access by Role -| Feature | Regular User (Project Admin) | Platform Admin | -| ----------------------------- | ---------------------------- | -------------- | -| Create a project | ✅ | ✅ | -| View own projects | ✅ | ✅ | -| Edit own project | ✅ | ✅ | -| Delete own empty project | ✅ | ✅ | -| Manage members in own project | ✅ | ✅ | -| View and manage all projects | ❌ | ✅ | -| Access Users Management | ❌ | ✅ | +| Feature | Invoker | Regular User (Project Admin) | Platform Admin | +| ----------------------------- | ------- | ---------------------------- | -------------- | +| Create a project | ❌ | ✅ | ✅ | +| View own projects | ✅ | ✅ | ✅ | +| Edit own project | ❌ | ✅ | ✅ | +| Delete own empty project | ❌ | ✅ | ✅ | +| Manage members in own project | ❌ | ✅ | ✅ | +| View and manage all projects | ❌ | ❌ | ✅ | +| Access Users Management | ❌ | ❌ | ✅ | + +An **Invoker** is a run-only user who can use what is shared with them but cannot manage +projects, members, or any AI configuration. See [Invoker Role](./invoker-role.md). diff --git a/docs/user-guide/project-user-management/invoker-role.md b/docs/user-guide/project-user-management/invoker-role.md new file mode 100644 index 00000000..e9c33265 --- /dev/null +++ b/docs/user-guide/project-user-management/invoker-role.md @@ -0,0 +1,153 @@ +--- +id: invoker-role +title: Invoker Role +sidebar_label: Invoker Role +sidebar_position: 4 +pagination_prev: user-guide/project-user-management/index +pagination_next: null +description: The Invoker is a run-only, least-privileged role in AI/Run CodeMie. Learn what an Invoker can and cannot do, how the role is assigned, and how it differs from other roles. +--- + +# Invoker Role + +The **Invoker** is the least-privileged role on the platform. An Invoker uses the assistants +and workflows that other people have built and shared, but never sees or changes how they are +configured. The Invoker interface is deliberately reduced to a chat-first experience, similar to +a general-purpose AI chat product. + +The role is intended for people who need to _run_ AI assistants without being able to +_author_ them: business users, support staff, reviewers, or anyone who should not have access +to prompts, tools, models, data sources, or platform configuration. + +:::info Admin configuration required +The Invoker role is assigned from Users Management, which requires **Platform-managed mode** +(`ENABLE_USER_MANAGEMENT=True`). The role also requires **activity events** to be enabled +(`ACTIVITY_EVENTS_ENABLED=True`), because every Invoker action is recorded in the audit trail. +If auditing is disabled, assigning the role is rejected with the message +**Invoker role unavailable**. +::: + +## What an Invoker Can Do + +| Area | Allowed | +| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Assistants | Chat with assistants shared with the projects the Invoker belongs to, and with the Invoker's own clones. Browse the **Project**, **Marketplace**, and **Favorites** lists. Like, favorite, and pin assistants. | +| Marketplace | Clone a Marketplace assistant into the personal project and chat with the clone. | +| Workflows | Browse shared workflows and run them. View, abort, resume, and delete the Invoker's **own** executions. | +| Chats | Full conversation history: rename, move to folders, delete, attach files, export a single message, and open conversation links shared by other users. | +| Personal integrations | Create, edit, test, and delete personal integrations, including Google and SharePoint OAuth flows. Only credential types that some accessible assistant actually needs can be created. Bind a personal integration to an assistant's tool slot. | +| Profile | View and edit the own profile and preferences. | + +## What an Invoker Cannot Do + +| Area | Restricted | +| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Configuration | View or edit any assistant or workflow configuration: system prompt, tools, toolkits, MCP servers, skills, model settings, data source bindings, or workflow YAML. Assistant and workflow pages show a reduced, read-only view. | +| Models | Change the LLM model in a chat or influence any AI configuration. The model configured by the assistant's author is always used. | +| Authoring | Create, edit, delete, publish, or share assistants, workflows, skills, or templates. This includes the Invoker's own clones, which are run-only. | +| Platform features | Data Sources, AI Katas, Analytics, Skills, project integrations, and all administration screens. These entries are removed from the navigation, and direct links open an **Access denied** page. | +| Sharing and export | Create shared conversation links or export a full conversation. Opening a link shared by someone else is allowed. | +| Direct API access | Call any API route outside the allowed set. Such requests are rejected with **Access denied** and recorded in the audit trail. | + +:::note +Restrictions are enforced by the backend, not only hidden in the interface. An Invoker who +calls the API directly is denied in exactly the same way as in the UI. +::: + +## The Invoker Interface + +When a user with the Invoker role signs in, the interface switches to a reduced layout: + +- **Navigation** shows **Chats**, **Assistants**, **Workflows**, **Applications** (when + configured), **Favorites**, **Integrations**, and **Help**. **Skills**, **Data Sources**, + **AI Katas**, **Analytics**, and administration settings are not shown. +- **Assistant pages** show the name, description, categories, and conversation starters. When an + assistant needs a personal integration, an **Integration needed** section lists the required + credential types. When it depends on MCP servers, an **MCP server needed** notice is shown. +- **Marketplace cards** offer **Clone** instead of **Chat**. A Marketplace assistant is chatted + with only after it has been cloned. +- **Chat** has no model selector and no advanced options. The assistant's configured model is + used for every message. +- **Integrations** shows only the **Personal** integrations of the current user. The **Project** + tab is not available. +- **Help** hides deployment-specific information such as the available models catalog. + +## Cloning a Marketplace Assistant + +1. Open **Assistants → Marketplace**. +2. Click **Clone** on the assistant card. +3. Enter a name in the **Clone assistant** dialog and confirm. +4. The clone is created in the Invoker's personal project and a chat with it opens + immediately. + +:::warning +A clone created by an Invoker does **not** carry over the source assistant's MCP servers or +skills. If a Marketplace assistant relies on MCP tools, the clone loses that capability. Ask +the assistant's author to share the original assistant with the project instead. +::: + +Clones are run-only: an Invoker cannot edit or delete a clone after it is created. Personal +credentials are attached through the **Integration needed** section, not by editing the +assistant. + +## Personal Integrations for Invokers + +An Invoker can create only the credential types that at least one accessible assistant +requires. When a type is not needed by any assistant, the integration form shows guidance +instead of saving: + +> No assistant or workflow accessible to you currently needs ``. Pick a type +> one of your assistants needs, or add the integration directly from that assistant's own +> "Integration needed" section. + +The recommended flow is to start from the assistant: + +1. Open the assistant page. The **Integration needed** section lists every credential type the + assistant requires and whether the author already provided it. +2. Select an existing personal integration for each tool, or create a new one from the same + section. +3. Click **Save**. The binding applies only to the current user; other users of the same + assistant are not affected. + +Integrations created by an Invoker are always personal. An Invoker cannot create project +integrations or make a personal integration global. + +## Assigning the Role + +The Invoker role is a platform-wide flag on the user account, not a per-project setting. Project +membership still decides _which_ projects the Invoker sees; the role only limits what the user +can do inside them. + +The role is assigned from the **User Details** panel in +[Users Management](./users.md#assign-the-invoker-role). The following rules apply: + +- Invoker is mutually exclusive with **Admin**, **Maintainer**, **Auditor**, and **Project + Admin**. Enabling Invoker clears the Admin, Maintainer, and Auditor switches. If the user is + a Project Admin in any project, the assignment is rejected until that role is removed. +- The account can still be added to projects as a regular member by any Project Admin. The + Invoker restriction follows the account into every project. +- Existing assistants, workflows, or integrations owned by the user remain in place, but the + user can no longer edit them while the role is active. + +## Audit Trail + +Every action performed by an Invoker is recorded as an activity event, including chat turns, +workflow executions, clones, integration changes, tool-slot bindings, file uploads, and every +denied request. This makes the role suitable for environments where run-only access must be +provable. + +## Comparison with Other Roles + +| Capability | Invoker | Regular User | Project Admin | Admin / Maintainer | +| -------------------------------------------- | ------- | ------------ | ------------- | ------------------ | +| Chat with shared assistants | ✅ | ✅ | ✅ | ✅ | +| Run shared workflows | ✅ | ✅ | ✅ | ✅ | +| View assistant and workflow configuration | ❌ | ✅ | ✅ | ✅ | +| Create and edit assistants and workflows | ❌ | ✅ | ✅ | ✅ | +| Change the LLM model in a chat | ❌ | ✅ | ✅ | ✅ | +| Manage personal integrations | ✅ | ✅ | ✅ | ✅ | +| Manage project integrations and data sources | ❌ | ❌ | ✅ | ✅ | +| Manage project members | ❌ | ❌ | ✅ | ✅ | +| Access administration and analytics | ❌ | ❌ | ❌ | ✅ | + +For the complete platform role model, see [CodeMie Roles Overview](../../admin/security/roles-rbac.md). diff --git a/docs/user-guide/project-user-management/users.md b/docs/user-guide/project-user-management/users.md index f3be3545..e99bdb4b 100644 --- a/docs/user-guide/project-user-management/users.md +++ b/docs/user-guide/project-user-management/users.md @@ -52,7 +52,7 @@ Use the filter bar at the top of the list to narrow results: - **Search** — filter by name - **Project** — show only users assigned to a specific project -- **Platform Role** — filter by `User`, `Project Admin`, or `Super Admin` +- **Platform Role** — filter by `User`, `Project Admin`, `Super Admin`, `Auditor`, or `Invoker` Click **Clear All** to reset all active filters. @@ -73,6 +73,37 @@ The panel shows: ![User Details panel for an External user](./images/user-details-external.png) +### Assign the Invoker Role + +The **User Details** panel contains the platform role switches: **Auditor**, **Admin**, +**Maintainer**, and **Invoker**. The **Invoker** switch turns the selected user into a run-only +user who can chat with shared assistants, run shared workflows, clone Marketplace assistants, +and manage personal integrations, but cannot view or change any AI configuration. See +[Invoker Role](./invoker-role.md) for the full list of permissions and restrictions. + +To assign the role: + +1. Open the **User Details** panel for the user. +2. Turn on the **Invoker** switch. The change is saved immediately. + +The following rules apply: + +- Invoker is mutually exclusive with **Admin**, **Maintainer**, and **Auditor**. Turning on + **Invoker** clears those switches for the user. +- Invoker cannot be combined with the **Project Admin** role. If the user is a Project Admin in + any project, the switch is rejected and an error is shown under the switches. Change the + user's role to **User** in every project first, then assign Invoker. +- A user cannot change their own platform roles. + +:::info Prerequisites +The Invoker role requires **activity events** to be enabled on the platform +(`ACTIVITY_EVENTS_ENABLED=True`), because every Invoker action is written to the audit trail. +When auditing is disabled, the switch is rejected with the message **Invoker role unavailable**. +::: + +To revoke the role, turn the **Invoker** switch off. The user immediately regains the regular +user interface and permissions. + ### Budget Spending The **Budget Spending** widget is displayed at the bottom of the User Details panel and shows diff --git a/faq/how-do-i-assign-the-invoker-role-to-a-user.md b/faq/how-do-i-assign-the-invoker-role-to-a-user.md new file mode 100644 index 00000000..2c6ee82c --- /dev/null +++ b/faq/how-do-i-assign-the-invoker-role-to-a-user.md @@ -0,0 +1,10 @@ +# How do I assign the Invoker role to a user? + +Open **Profile → Settings → Administration → Users management**, open the **User Details** panel for the user, and turn on the **Invoker** switch. The change is saved immediately and the user gets the restricted, chat-first interface on their next page load. + +Invoker is mutually exclusive with Admin, Maintainer, Auditor, and Project Admin: turning it on clears the Admin, Maintainer, and Auditor switches, and it is rejected while the user is a Project Admin in any project. The role also requires activity events (`ACTIVITY_EVENTS_ENABLED=True`) to be enabled on the platform; otherwise the switch is rejected with **Invoker role unavailable**. Users Management itself is available only in Platform-managed mode. + +## Sources + +- [Users Management](https://docs.codemie.ai/user-guide/project-user-management/users/) +- [Invoker Role](https://docs.codemie.ai/user-guide/project-user-management/invoker-role/) diff --git a/faq/what-can-an-invoker-do-in-codemie.md b/faq/what-can-an-invoker-do-in-codemie.md new file mode 100644 index 00000000..2f5a6461 --- /dev/null +++ b/faq/what-can-an-invoker-do-in-codemie.md @@ -0,0 +1,10 @@ +# What can an Invoker do in CodeMie? + +An **Invoker** is the least-privileged, run-only role. An Invoker can chat with assistants shared with their projects, run shared workflows, clone Marketplace assistants into their personal project, keep a full conversation history, and create personal integrations for the credential types those assistants need. + +An Invoker cannot view or edit any assistant or workflow configuration (not even the system prompt), change the LLM model in a chat, create or edit assistants, workflows, skills, or data sources, share conversations, or open administration and analytics screens. The interface is reduced to a chat-first layout, and the backend rejects any request outside the allowed set with **Access denied**. Every Invoker action is recorded in the audit trail. + +## Sources + +- [Invoker Role](https://docs.codemie.ai/user-guide/project-user-management/invoker-role/) +- [CodeMie Roles Overview](https://docs.codemie.ai/admin/security/roles-rbac/) diff --git a/sidebars.ts b/sidebars.ts index 3fae6a0d..b96be1d4 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -357,6 +357,7 @@ const sidebars: SidebarsConfig = { items: [ 'user-guide/project-user-management/projects', 'user-guide/project-user-management/users', + 'user-guide/project-user-management/invoker-role', ], }, {