diff --git a/docs/products/catalog/basic-concepts/10_items.md b/docs/products/catalog/basic-concepts/10_items.md index 3a23167b21..caeca926c3 100644 --- a/docs/products/catalog/basic-concepts/10_items.md +++ b/docs/products/catalog/basic-concepts/10_items.md @@ -146,7 +146,7 @@ customFields: resourceVersion: 1 ``` -Each key in `customFields` corresponds to the `spec.key` of a separate `CustomField` catalog entity (kind `CustomField`, family `custom-fields`, group `mia-platform.eu/v1alpha1`). The `CustomField` declares: +Each key in `customFields` corresponds to the `spec.key` of a separate `CustomField` catalog entity (kind `CustomField`, family `custom-fields`, group `mia-platform.eu/v1alpha1`). Custom fields are only manageable through the [Catalog API](/products/catalog/usage/catalog-api.md) — declaring a `CustomField` and setting values on items — the Catalog App does not currently expose any UI for them. The `CustomField` declares: - **`spec.key`** — the unique key used in items' `customFields` map. May be plain (e.g. `sensitivity`) or prefixed (e.g. `runtime/java-version`). - **`spec.schema`** — a JSON Schema (Draft 2020-12) that validates the value of the field on items. @@ -201,10 +201,14 @@ Because the lifecycle of `CustomField` entities is independent from the items th ## Ownership and followers -Two relationships are central to the way the catalog associates people with items. Both Users and Teams are themselves first-class items in the catalog (built-in kinds under the `mia-platform.eu` group), so the relationships below are just ordinary Relationship objects between items, there is no special "principal" concept. +Two fields are central to the way the catalog associates people with items. -- **Owner.** Every item can have an *owner*, which is either a User or a Team. Ownership is modeled as a built-in relationship of type `ownership.mia-platform.eu` between the item and the User/Team. The Catalog App exposes ownership as a first-class field on the item form, but on the wire it is just a Relationship object — see [Relationships](/products/catalog/basic-concepts/60_relationships.md). -- **Follower.** Any user can additionally *follow* an item to be notified about compliance events that involve it. Following is modeled as a built-in relationship of type `follow.mia-platform.eu` between the User and the item. Owners are implicitly considered followers. +- **Owner.** Every item can have an *owner*, identified by an email address stored in `metadata.owner`. The Catalog App exposes ownership as a first-class field on the item form. +- **Follower.** Any number of people can additionally *follow* an item to be notified about compliance events that involve it, identified by the email addresses stored in `metadata.followers`. Owners are implicitly considered followers. + +:::note +Owner and follower are plain email fields, not relationships, so they are not navigable in the [relationship graph](/products/catalog/basic-concepts/60_relationships.md). The plan is to eventually resolve these emails to first-class User items and surface them in the relationship graph. +::: ## Primary key and Item URN diff --git a/docs/products/catalog/basic-concepts/60_relationships.md b/docs/products/catalog/basic-concepts/60_relationships.md index e1da45f256..573ac6737c 100644 --- a/docs/products/catalog/basic-concepts/60_relationships.md +++ b/docs/products/catalog/basic-concepts/60_relationships.md @@ -6,7 +6,11 @@ sidebar_label: Relationships # Relationships -A **relationship** is a typed, directed link between a *source* item and a *target* item. Relationships form a graph layered on top of the catalog's items: they let you traverse from a service to its owners, from a deployment to the environment it targets, from a vulnerability to the artifacts it affects, and so on. +A **relationship** is a typed, directed link between a *source* item and a *target* item. Relationships form a graph layered on top of the catalog's items: they let you traverse from a deployment to the environment it targets, from a vulnerability to the artifacts it affects, and so on. + +:::note +Item ownership and followers (see [Items](/products/catalog/basic-concepts/10_items.md#ownership-and-followers)) are **not** modeled as relationships: they are plain email fields on the item. They used to be built-in relationship types (`ownership.mia-platform.eu` and `follow.mia-platform.eu`) navigable in this graph, and are expected to return here once owners/followers are resolved to first-class User items. +::: The catalog models relationships with three built-in kinds: @@ -44,11 +48,11 @@ A `RelationshipConstraint` declares which item kinds may legitimately participat apiVersion: mia-platform.eu/v1alpha1 kind: RelationshipConstraint metadata: - name: ownership-team-owns-service + name: part-of-service-in-domain spec: - relationshipTypeRef: urn:mia-platform-catalog:mia-platform.eu:v1alpha1:RelationshipType:ownership.mia-platform.eu - sourceType: urn:mia-platform-catalog:mia-platform.eu:v1:Team - targetType: urn:mia-platform-catalog:mia-platform.eu:v1:Service + relationshipTypeRef: urn:mia-platform-catalog:mia-platform.eu:v1alpha1:RelationshipType:part-of.mia-platform.eu + sourceType: urn:mia-platform-catalog:mia-platform.eu:v1:Service + targetType: urn:mia-platform-catalog:mia-platform.eu:v1:Domain ``` Required fields: @@ -71,11 +75,11 @@ A `Relationship` is the actual edge: it pairs a source item URN with a target it apiVersion: mia-platform.eu/v1alpha1 kind: Relationship metadata: - name: api-gateway-owned-by-platform-team + name: api-gateway-part-of-platform-domain spec: - typeRef: urn:mia-platform-catalog:mia-platform.eu:v1alpha1:RelationshipType:ownership.mia-platform.eu - sourceRef: urn:mia-platform-catalog:mia-platform.eu:v1:Team:platform-team - targetRef: urn:mia-platform-catalog:console.mia-platform.eu:v1:Service:api-gateway + typeRef: urn:mia-platform-catalog:mia-platform.eu:v1alpha1:RelationshipType:part-of.mia-platform.eu + sourceRef: urn:mia-platform-catalog:console.mia-platform.eu:v1:Service:api-gateway + targetRef: urn:mia-platform-catalog:mia-platform.eu:v1:Domain:platform-domain ``` Required fields: @@ -93,7 +97,7 @@ When a `Relationship` is created or updated, the catalog validates only the **UR Once relationships exist, you can navigate them through: - the **Relationships** tab of any item in the [Catalog App](/products/catalog/usage/catalog-app.md), as a table or as a visual graph; -- the `related` operator of the Catalog [Query Language](/products/catalog/basic-concepts/70_query-language.md), to express queries such as *"all services owned by team X"* or *"all items affected by vulnerability Y"*. +- the `related` operator of the Catalog [Query Language](/products/catalog/basic-concepts/70_query-language.md), to express queries such as *"all services part of domain X"* or *"all items affected by vulnerability Y"*. ## See also diff --git a/docs/products/catalog/basic-concepts/70_query-language.md b/docs/products/catalog/basic-concepts/70_query-language.md index 87ab50c4f0..a21b96e407 100644 --- a/docs/products/catalog/basic-concepts/70_query-language.md +++ b/docs/products/catalog/basic-concepts/70_query-language.md @@ -91,18 +91,22 @@ The `related` operator selects items that are connected to a given item through - `as` declares the role the *matched item* plays in the relationship: `source` means "match items that are the source of a relationship pointing to `where.ref`"; `target` means "match items that are the target of a relationship coming from `where.ref`". - `where.ref` is the URN of the *other* endpoint. -For example, *"all items owned by the team `platform-team`"* — i.e. items that are the *target* of an `ownership` relationship whose source is `platform-team`: +For example, *"all services part of the `platform-domain` domain"* — i.e. items that are the *source* of a `part-of` relationship whose target is `platform-domain`: ```json { "related": { - "type": "urn:mia-platform-catalog:mia-platform.eu:v1alpha1:RelationshipType:ownership.mia-platform.eu", - "as": "target", - "where": { "ref": "urn:mia-platform-catalog:mia-platform.eu:v1:Team:platform-team" } + "type": "urn:mia-platform-catalog:mia-platform.eu:v1alpha1:RelationshipType:part-of.mia-platform.eu", + "as": "source", + "where": { "ref": "urn:mia-platform-catalog:mia-platform.eu:v1:Domain:platform-domain" } } } ``` +:::note +Ownership is not modeled as a relationship type — it's a plain `metadata.owner` email field on the item (see [Items](/products/catalog/basic-concepts/10_items.md#ownership-and-followers)), so filter on it directly (e.g. `{ "metadata.owner": { "eq": "..." } }`) instead of `related`. +::: + ## Example: complex query A non-trivial query that combines AND / OR and a regex: diff --git a/docs/products/catalog/basic-concepts/99_glossary.md b/docs/products/catalog/basic-concepts/99_glossary.md index 687996f3be..b7bc35d6f5 100644 --- a/docs/products/catalog/basic-concepts/99_glossary.md +++ b/docs/products/catalog/basic-concepts/99_glossary.md @@ -65,7 +65,7 @@ See [Items](/products/catalog/basic-concepts/10_items.md#tags-labels-annotations ## Owner and follower -An **owner** is a User or Team responsible for an item, modeled as a built-in `ownership` relationship. A **follower** is any User who wants to receive compliance notifications about an item, modeled as a built-in `follow` relationship. Both relationships are surfaced in the UI and queried like any other relationship. See [Items](/products/catalog/basic-concepts/10_items.md#ownership-and-followers). +An **owner** is the email address responsible for an item, stored in `metadata.owner`. A **follower** is any email address that wants to receive compliance notifications about an item, stored in `metadata.followers`. Neither is modeled as a relationship, so neither is navigable in the relationship graph — a future migration to first-class User items is planned. See [Items](/products/catalog/basic-concepts/10_items.md#ownership-and-followers). ## View diff --git a/docs/products/catalog/getting-started.md b/docs/products/catalog/getting-started.md index e7e3ec6eb0..a7ae68ab64 100644 --- a/docs/products/catalog/getting-started.md +++ b/docs/products/catalog/getting-started.md @@ -55,7 +55,7 @@ You can do the same thing via API by sending a `POST` request to the resource pa ## 4. Connect items with a relationship -Open the detail page of an item, jump to the **Relationships** tab, and link it to another item using one of the [built-in relationship types](/products/catalog/basic-concepts/60_relationships.md#built-in-relationship-types) (e.g. `ownership`, `part-of`, `dependency`) or one you have defined yourself. From now on, you can navigate that connection from either endpoint, both in the table view and in the graph view. +Open the detail page of an item, jump to the **Relationships** tab, and link it to another item using one of the [built-in relationship types](/products/catalog/basic-concepts/60_relationships.md#built-in-relationship-types) (e.g. `part-of`, `dependency`) or one you have defined yourself. From now on, you can navigate that connection from either endpoint, both in the table view and in the graph view. ## 5. Run a compliance check diff --git a/docs/products/catalog/usage/catalog-app.md b/docs/products/catalog/usage/catalog-app.md index b7d6b3ce17..1bbbb490d5 100644 --- a/docs/products/catalog/usage/catalog-app.md +++ b/docs/products/catalog/usage/catalog-app.md @@ -54,7 +54,7 @@ Items are presented in a paginated table that loads more entries as you scroll. Click **Create item** to open a guided three-step wizard: 1. **Item Type** — choose an Item Type Definition (the kind of item you want to create). -2. **Metadata** — provide a title, name, description, tags, and optionally an owner (a User or Team). +2. **Metadata** — provide a title, name, description, tags, and optionally an owner (an email address). 3. **Specification** — fill in the item's `spec` as a JSON document, guided by the schema defined in the selected Item Type Definition. ### View an item @@ -75,8 +75,8 @@ Clicking an item opens its detail page, which is organized into tabs: From the detail page you can also: -- **Edit metadata** — from the actions menu, update the title, description, tags, and owner (a User or Team). For Connector-kind items, you can also update the icon. -- **Manage followers** — from the **Overview** tab (not the actions menu), add or remove users following this item. +- **Edit metadata** — from the actions menu, update the title, description, tags, and owner (an email address). For Connector-kind items, you can also update the icon. +- **Manage followers** — from the **Overview** tab (not the actions menu), add or remove the email addresses following this item. - **View manifest** — inspect the full raw manifest of the item in a modal, and download it as a JSON file. - **Delete** — permanently remove the item from the catalog. diff --git a/docs/products/mia-platform-suite/rbac_management.md b/docs/products/mia-platform-suite/rbac_management.md index 39d9b14328..4ba01d3b95 100644 --- a/docs/products/mia-platform-suite/rbac_management.md +++ b/docs/products/mia-platform-suite/rbac_management.md @@ -22,6 +22,7 @@ Mia-Platform's RBAC system is a centralized service designed for granular access - **Input schema** — a JSON Schema file in the *schemas/* directory that defines the structure of *input.rbac*, used for validating and type-checking policy inputs. - **Super Admin** — a global administrative role (*...authz:Super Admin*) with full privileges to manage the entire platform. - **Organization Admin** — an administrative role (*...organization-Super Admin:\*) with full privileges limited to a specific organization. +- **Tenant Admin** — an administrative role with full privileges limited to a specific tenant. - **Scope** — defines the extent of a permission: it can be global ('/') or restricted to a specific path (e.g., */\*). - **Decision helper** — a function (*helpers.decision(input)* in *authz/helpers/acl_context.rego*) that evaluates policies and generates the final decision, attaching the *x-mia-acl-context* header. - **Allowed resource actions** — a list of URN permissions assigned to a principal's role within *input.rbac.roles[]*. @@ -51,6 +52,8 @@ Below is the specific behavior for each product. For Console, roles and permissions are chosen from a **fixed, predefined list**, they cannot be customized or extended. Admins can assign these predefined roles to users, service accounts, or groups. +Console tenants and the tenants of the new products do not interact with each other: they are managed independently, and RBAC roles assigned in one cannot be managed from the Administration page of the other. + See organization's detail at [Manage users](/products/console/identity-and-access-management/manage-users.md). ### AI Foundry @@ -85,10 +88,10 @@ Alice's effective permissions are the combination of these two groups' roles. Fr ## What can be managed via API - **Groups**: creation, modification, deletion; member management; role assignment to the group. -- **Users**: creation, modification, deletion, consultation. +- **Users**: creation, invitation, modification, deletion, consultation. - **Roles**: creation, modification, deletion, consultation. - **Tenant**: creation and edit of tenants, also at the individual organization level. -- **Configuration**: reading and updating an organization's settings. +- **Configuration**: reading and updating tenant's settings. - **Service accounts**: registration and deletion — see [Registering a service account](#registering-a-service-account) below. ## Permission matrix @@ -135,10 +138,10 @@ Access legend: In this v15 release, Catalog RBAC management has the following constraints: -- **Roles**: cannot be created, modified, or deleted. The available roles are fixed and correspond to those defined in the [Permission Matrix](#permission-matrix) above. +- **Roles**: cannot be created, modified, or deleted via UX. The available roles are fixed and correspond to those defined in the [Permission Matrix](#permission-matrix) above. - **Groups**: can be created. Groups are the only entity that admins can define in this version, to combine users under a shared set of role assignments. - **Users**: cannot be created. Users can only be **assigned** to existing roles and groups. -- **Permissions**: not yet customizable in this phase — permissions are tied to roles as defined in the matrix and cannot be edited individually. +- **Permissions**: not yet customizable in this phase permissions are tied to roles as defined in the matrix and cannot be edited individually. - **Group scope**: the only scope that can currently be assigned to a group is the **entire tenant**; scoping a group to a specific path or sub-resource is not yet available. ## Detail views @@ -156,7 +159,7 @@ Service accounts are the non-human identities that let external tools and pipeli ### 1. Reach the API -The registration endpoint is reachable through the api-portal published alongside your Mia Platform Suite Home instance — typically at `/documentations/api-portal/`. Only a Super Admin can complete the registration. +The registration endpoint is reachable through the api-portal published alongside your Mia-Platform Suite Home instance — typically at `/documentations/api-portal/`. Only a Super Admin can complete the registration of users in tenant by using this tool. ### 2. Generate a key pair @@ -289,13 +292,39 @@ A successful response looks like: Use the resulting `access_token` in the `Authorization: Bearer ` header of every API call. Once it expires (`expires_in`), repeat the token request. -## Advantages of adoption +## FAQ + +### Who is the Organization Admin and how is this role acquired? + +- **PaaS**: the Super Admin is designated via Keycloak (during installation but also afterwards). Organization Admin permissions can instead be assigned at a later stage via the front-end, from the Administration panel, but only after the organization has already been created. +- **On-Premise**: the Super Admin is appointed at the creation of the organization in Keycloak. Only one organization is possible, so the Super Admin and the Organization Admin roles coincide. + +### How and where are tenants managed? + +Currently, tenant management (creation and modification, but not deletion) occurs via the API Portal, and only Super Admins and Org Admins can perform these actions. + +### How are new users added, and who is authorized to do so? + +- **Keycloak Admin** — adds users to the organization (via their personal Keycloak console). +- **Org Admin** — adds users to a tenant (via API Portal). + +### Is it possible to add users, groups, or roles in "bulk" mode to speed up onboarding? + +At the moment, bulk user addition is not supported. + +### How does the user offboarding procedure work? + +From the interface, the Organization Admin can delete a user directly from the user management page in the organization's dedicated Keycloak instance. + +### How does combined permission assignment work when a user belongs to multiple groups? + +A user's effective permissions are the union of all roles granted by each group they belong to. For example, if a user belongs to Group A (with Role X) and Group B (with Role Y), they will have both Role X and Role Y — see the [practical example of Alice Parker](#practical-example-of-granularity-and-access-management) above. Role assignment follows a deny-by-default model, meaning permissions must be explicitly granted: nothing is accessible by default. + +### How is a service account registered? + +It cannot be created from the Administration interface. A Super Admin must call the dedicated API — see [Registering a service account](#registering-a-service-account) above. -The integration of RBAC ensures high standards of security and efficiency: +### Tenants of new products vs. Console: what is the difference, and how do they interact? -- **Reusability**: use of predefined policy templates to accelerate the setup of organizational roles. -- **Configuration integrity**: drastic reduction of manual errors thanks to centralized governance. -- **Least privilege**: technical guarantee that each principal accesses only the minimum set of necessary resources. -- **Operational efficiency**: reduction of management times by eliminating the need for custom configurations on individual APIs. +Currently, tenants from new products and Console tenants do not interact with each other. The same limitation applies to RBAC roles: they cannot be managed from the Administration page on the home page for one from the other. See [Accessing the Administration section](#accessing-the-administration-section) above for more details. -Overall, the RBAC model provides a scalable, secure, and maintainable authorization framework, enabling fine-grained access control while simplifying administrative operations across the platform.