From 118815060f3a37d3db7d4ae8222fc1b6a25302ce Mon Sep 17 00:00:00 2001 From: katarzyna_koltun Date: Wed, 21 Oct 2026 18:05:22 +0200 Subject: [PATCH 01/12] PMP DRM --- .../private-platform/pmp-role-management.md | 141 --------- .../en/docs/private-platform/roles/_index.md | 43 +++ .../roles/pmp-access-administration.md | 187 ++++++++++++ .../roles/pmp-access-model.md | 280 ++++++++++++++++++ .../roles/pmp-groups-and-app-teams.md | 110 +++++++ 5 files changed, 620 insertions(+), 141 deletions(-) delete mode 100644 content/en/docs/private-platform/pmp-role-management.md create mode 100644 content/en/docs/private-platform/roles/_index.md create mode 100644 content/en/docs/private-platform/roles/pmp-access-administration.md create mode 100644 content/en/docs/private-platform/roles/pmp-access-model.md create mode 100644 content/en/docs/private-platform/roles/pmp-groups-and-app-teams.md diff --git a/content/en/docs/private-platform/pmp-role-management.md b/content/en/docs/private-platform/pmp-role-management.md deleted file mode 100644 index 99c53817aae..00000000000 --- a/content/en/docs/private-platform/pmp-role-management.md +++ /dev/null @@ -1,141 +0,0 @@ ---- -title: "Dynamic Role Management in Private Mendix Platform" -linktitle: "Dynamic Role Management" -url: /private-mendix-platform/dynamic-role-management/ -description: "Documents the dynamic role management functionality of the Private Mendix Platform." -weight: 55 ---- - -## Introduction - -Starting from version 2.0, Private Mendix Platform offers dynamic role management to strengthen governance, improve flexibility, and streamline access control. This feature ensures that organizations can manage roles and permissions dynamically, aligning with evolving business and compliance requirements. - -To access the **Role Management** page, go to the **Admin > Manage** section of the Mendix Private Platform. This page centralizes all role-related governance and permissions. - -{{< figure src="/attachments/private-platform/pmp-roles1.png" class="no-border" >}} - -Private Mendix Platform 2.0 ships with a set of predefined roles to cover common responsibilities: - -* **Developer** - Full access to application development features -* **Contributor** - Limited access, typically for business users or domain experts contributing to projects -* **Operator** - Focused on operational tasks such as deployments, monitoring, and cluster management -* **Administrator** - Highest level of access, with full governance and configuration rights - -Admins can create new custom roles tailored to organizational needs. - -## Role Editing - -Admins can edit any default or custom role to adjust the following permissions dynamically: - -* Project permissions -* Cluster permissions -* CI/CD permissions - -## Group Management - -To access the **Group Management** page, go to the **Admin > Manage** section of the Mendix Private Platform. It provides a hierarchical structure for managing user roles and resource access across applications, clusters, and namespaces. - -{{< figure src="/attachments/private-platform/pmp-roles2.png" class="no-border" >}} - -Groups are organized in a hierarchical tree. The root group is created by Private Mendix Platform automatically and serves as the foundation for all user-created groups. - -Admins can customize root group information to align with organizational needs. The hierarchy depth is theoretically unlimited, supporting complex organizational structures. - -Every new group must be assigned a parent group. This ensures proper inheritance of governance and permissions. - -{{< figure src="/attachments/private-platform/pmp-roles3.png" class="no-border" >}} - -### Group Ownership and Resources - -Each group can own or associate resources, and permissions are applied to its members through assigned roles. - -The following resources are currently supported: - -* Apps - Application-level access control. -* Namespace purposes - Permissions tied to namespaces for deployment or operational segregation. - -The following ownership and association rules apply: - -* Apps - An app can only be owned by one group. Ownership is exclusive to ensure clear accountability. -* Namespaces - A namespace can be associated with multiple groups non-exclusively, allowing flexible sharing of operational responsibilities across teams. - -### Role Assignment Model - -Roles are assigned to group members, not to the group itself. If a group has a subgroup, then members of the main group are automatically inherited into the subgroup with the same roles they hold in the main group. This ensures consistency of permissions across hierarchical structures and reduces duplication of role assignments. - -{{< figure src="/attachments/private-platform/pmp-roles5.png" class="no-border" >}} - -### Group Creation - -When creating a new group, admins must provide the following information: - -* **Description** - A clear explanation of the group's purpose. -* **Group Admins** - One or more administrators responsible for managing the group. -* **Parent Group** - Defines the group's place in the hierarchy. - -### Statistics Dashboard - -The Group Management page also provides real-time statistics to help administrators monitor governance: - -* **Number of Groups** - Total number of groups created under the hierarchy. -* **Number of Resources Owned** - Count of Apps and namespace purposes associated with groups. -* **Namespaces Assigned to Groups** - Total namespaces linked to groups for operational control. -* **Average Number of Members per Group** - Helps track group size and distribution of users. - -{{< figure src="/attachments/private-platform/pmp-roles6.png" class="no-border" >}} - -## Permission Synchronization - -Permission synchronization ensures that role changes in groups are automatically applied to the resources owned or associated with those groups. This mechanism guarantees consistency between governance configurations and actual user access. - -### Role Change Propagation - -When a member's role changes in a specific group through admin mode, the update is immediately synchronized across all resources owned by or associated with that group (for example, apps, or namespaces). This synchronization eliminates manual updates and ensures governance policies are enforced consistently. - -### Combined Permission Calculation - -When multiple roles apply to a member, Private Mendix Platform calculates a combined permission set based on all assigned and inherited roles. - -This ensures that the member's effective permissions cover all capabilities granted by any of the roles. - -## Roles for Users - -When a user logs in, they can create a new app in Private Mendix Platform. - -The **Teams** page provides visibility into all members associated with the app, along with their roles. - -### Teams Page Overview - -The Teams page displays two categories of members: - -* Direct members -* Owner - -The user who created the app automatically becomes the owner. Owners have full control over the app, including inviting new members and assigning roles. - -#### Invited Members - -Owners can invite additional users into the App. These members are assigned specific roles such as: - -* Operator -* Contributor -* Developer - -#### Inherited Members - -Inherited memberships are derived from group memberships defined in the **Group Management** page. - -The folowing inheritance paths are available: - -* Owner's group - Members of the group to which the owner belongs are automatically inherited into the app. -* Parent group - Members of the parent group in the hierarchy are also inherited. - -Roles for inherited members are determined by the **Group Management** page and applied automatically. - -{{< figure src="/attachments/private-platform/pmp-roles7.png" class="no-border" >}} - -### Role Assignment for Users - -Direct members receive roles explicitly assigned by the app owner. Inherited members retain the roles defined in their group context. - -This approach ensures consistency. Direct roles can be managed with app-specific assignments, while inherited roles can have governance-driven assignments from group hierarchy. diff --git a/content/en/docs/private-platform/roles/_index.md b/content/en/docs/private-platform/roles/_index.md new file mode 100644 index 00000000000..9b375a9c771 --- /dev/null +++ b/content/en/docs/private-platform/roles/_index.md @@ -0,0 +1,43 @@ +--- +title: "Access Management in Private Mendix Platform" +url: /private-mendix-platform/access-management/ +aliases: + - /private-mendix-platform/dynamic-role-management/ +weight: 55 +description: "Documents how Private Mendix Platform controls what users can do on the platform and to individual apps, namespaces, and Marketplace content." +--- + +## Introduction + +Private Mendix Platform controls access along the following independent: + +* What a user can do on the platform as a whole +* what a user can do to a specific app, deployment namespace, or Marketplace item. + +Both axes are configured by administrators at runtime through Dynamic Role Management, without a code change and without redeploying the platform. + +This document explains the two axes. Other articles in this section describe the model, the administrative tasks that configure it, and the day-to-day tasks that users, group administrators, and app owners perform within it. + +## Understanding the Two Role Systems + +Instead of a single ladder of roles, with an administrator at the top who can do everything, Private Mendix Platform has two role systems, that is, [platform roles](#platform-role) and [resource roles](#resource-role). Each role system has its own permission schema, its own assignment mechanism, and its own scope. + +The two systems are independent of each other. That is, a platform role does not grant the user any resource roles, and a resource role does not grant the user any platform roles. The resource role named **Administrator** and the platform role named **CompanyAdmin** are unrelated. They share no permissions, and the resource role only has access to the resources owned by its holder's group. + +The following sections contain more information about platform and resource roles. For the full model, see [Access Model and Role Reference for Private Mendix Platform](/private-mendix-platform/access-model/). + +### Platform Roles {#platform-role} + +Platform roles define what a user can do on the platform in general. They are assigned to a user account at creation, and can be edited afterwards. Their scope involves the whole plaform. Having multiple platform roles gives a user all the access rights of every role they hold. + +### Resource Roles {#resource-role} + +Resource roles define what a user can do with specific resources, such as a specific app or namespace. They are assigned to an individual, as a member of a group, or directly on an app team. Their scope involves only the resources the relevant group owns or is associated with. Multiple resource roles are only combined where two roles apply to the same resource. + +## Read More + +* [Access Model and Role Reference for Private Mendix Platform](/private-mendix-platform/access-model/) - Before configuring the access rights, review this document to understand how the model works, including how groups inherit membership, which resources a group can own, and how permissions combine. It also lists every default role and what it grants. +* [Administering Users, Groups, and Roles in Private Mendix Platform](/private-mendix-platform/access-administration/) - Refer to this document for information about creating user accounts, defining or editing roles, building your group hierarchy, and associating apps and namespaces with groups. Those tasks require the **CompanyAdmin** Platform Role. +* [Working with Groups and App Teams in Private Mendix Platform](/private-mendix-platform/groups-and-app-teams/) - Refer to this document for information about managing the membership of a group you administer, or a team on an app you own. Those tasks require no administrator role. +* [Private Mendix Platform Functionalities - System Administrators](/private-mendix-platform/reference-guide/admin/system/) - Refer to this document for information about identity provider configuration, including connect an identity provider, configuring SCIM provisioning, and adjusting login session preferences. +* [Federated Users](/private-mendix-platform/access-model/#federated-users) - Refer to this document for information about what happens to a federated user on first login, and where they land in the group hierarchy. \ No newline at end of file diff --git a/content/en/docs/private-platform/roles/pmp-access-administration.md b/content/en/docs/private-platform/roles/pmp-access-administration.md new file mode 100644 index 00000000000..6711aea0dfc --- /dev/null +++ b/content/en/docs/private-platform/roles/pmp-access-administration.md @@ -0,0 +1,187 @@ +--- +title: "Administering Users, Groups, and Roles in Private Mendix Platform" +url: /private-mendix-platform/access-administration/ +weight: 20 +description: "Documents the administrator tasks for managing user accounts, defining roles, building the group hierarchy, and associating resources with groups in Private Mendix Platform." +--- + +## Introduction + +This page documents the tasks that configure access in Private Mendix Platform: creating and maintaining user accounts, defining what roles exist and what they grant, building the group hierarchy, and associating apps and deployment namespaces with the groups that need them. + +These tasks require the **CompanyAdmin** Platform Role. Configuring the identity provider that federated users authenticate against is a separate concern requiring **SystemAdmin**, and is documented in [Private Mendix Platform Functionalities - System Administrators](/private-mendix-platform/reference-guide/admin/system/). + +Before making structural changes, read [Access Model and Role Reference for Private Mendix Platform](/private-mendix-platform/access-model/). Two rules in particular have consequences that are not visible from the screens described below: group membership inherits downward without limit, and deployment namespace associations do not inherit at all. + +## Accessing the Access Management Pages + +1. Click your profile picture in the top right corner of the screen and select **Switch to Admin Mode**. +2. In the left navigation menu, open the **Manage** section. + +User accounts, groups, and roles are managed from this section. + +{{% alert color="info" %}} +**Reviewer note:** confirm the exact navigation path and page names in the current release, in particular whether Role Management is a page of its own under **Manage** or a tab within User Management. +{{% /alert %}} + +## Managing User Accounts + +On the **User Management** page you can create and maintain the accounts that use your platform, whether they belong to people or to services. + +There is one kind of account. What an account can do comes from the Platform Roles assigned to it, not from any account type, so the same page and the same procedure serve a developer, an administrator, and an integration. + +To create an account, click **New** and provide the user's name and email address, then assign the Platform Roles the account requires. An account with no Platform Role cannot use the platform, so at minimum assign **User**. + +By clicking **More Actions** by an existing account you can: + +* Edit the user's name and email address. +* Assign or remove Platform Roles. +* Block the user, preventing sign-in without deleting the account or its history. +* Change the user's password. +* Configure the user's language and time zone. +* Log the user out of all current sessions. +* Delete the account. + +The **Actions** tab additionally lets you log out every user currently signed in to the platform. + +Some of these actions depend on how the account authenticates rather than on what kind of account it is. Setting a password, for instance, applies to accounts that sign in with platform credentials and not to accounts that authenticate through your identity provider. + +{{% alert color="info" %}} +**Reviewer note:** confirm which of the actions above are unavailable for accounts that authenticate through an identity provider. The current [Company Administrators](/private-mendix-platform/reference-guide/admin/company/#user-management) page marks several of them "local users only", which reads as an account-type restriction; the list needs restating in terms of authentication method. +{{% /alert %}} + +{{% alert color="warning" %}} +Assigning a Platform Role gives a user platform-wide capability and nothing else. It does not give them access to any app, namespace, or Marketplace item. Access to resources comes from group membership or an app team invitation, described below. +{{% /alert %}} + +### Accounts Used by Services + +A service that calls the platform API signs in as an ordinary account, and what it can do is determined by that account's Platform Role. A role such as **API User**, carrying only the permissions one integration needs, is an example of a Platform Role defined for this purpose. + +Give each integration its own account and its own narrowly scoped role rather than reusing an administrator account. Because the account is ordinary, everything else on this page applies to it: it can be blocked, its roles can be changed, and its actions appear in the activity log. + +{{% alert color="info" %}} +**Reviewer note:** confirm whether a role named API User ships with the platform or is customer-defined. Note also that [Private Mendix Platform Functionalities - Company Administrators](/private-mendix-platform/reference-guide/admin/company/#user-management) currently presents "API users" as a separate kind of account, and that several of the per-account actions on that page are described as available to "local users only". Both need reconciling with the single-account-kind model as part of this change. +{{% /alert %}} + +### Sign-In and Lockout Behavior + +Session limits, automatic disabling of unused accounts, failed sign-in lockout, and lockout duration are platform-wide settings rather than per-account ones, and are configured by a system administrator. See [Preferences](/private-mendix-platform/reference-guide/admin/system/#preferences-1). + +## Managing Roles + +Role Management is where you decide what roles exist and what each one grants. It presents Platform Roles and Resource Roles separately, because they are separate systems with separate permission schemas. For what each default role grants, see [The Two Role Systems](/private-mendix-platform/access-model/#the-two-role-systems). + +In both systems: + +* You can change the permissions of a default role. +* You cannot delete a default role. +* You can create new roles with any combination of permissions. + +{{% alert color="warning" %}} +Editing a role changes the effective access of everyone who holds it, immediately. Before editing, check how many users hold the role and what resources they reach through it. Where a change applies to some users and not others, create a new role instead of editing an existing one. +{{% /alert %}} + +### Editing a Platform Role + +Select the role and adjust its permissions. These cover generic platform access such as signing in and creating an app, capabilities in the **Manage** area such as app, user, group, and Marketplace administration, and capabilities in the **Settings** area such as identity configuration, licensing, and webhooks. + +Because CompanyAdmin and SystemAdmin are parallel rather than nested, a custom role that needs capabilities from both areas must be given permissions from both. + +### Editing a Resource Role + +Select the role and adjust its permissions, which are grouped into four categories: + +* **Project** - the app lifecycle, its team, version control, and viewing environments. +* **Build** - packaging, the build pipeline, and the software bill of materials. +* **Deployment** - deploying to and managing environments. +* **Monitoring** - logs and metrics. + +**Owner** is a special case. It is assigned automatically to whoever creates an app and cannot be granted to anyone manually. To change who holds it, transfer ownership of the app. + +### Scoping Deployment Permissions per Environment + +Permissions in the **Deployment** category, and only in that category, can be limited to specific environments. For each such permission, select the combination of Development, Test, Acceptance, and Production it should apply to. + +Use this rather than maintaining several near-identical roles. A single role in which deployment is permitted for Development and Test and withheld for Production expresses a common compliance requirement in one place, and stays correct as teams change. + +### Creating a Custom Role + +Click **New** in the relevant tab, name the role, and select its permissions. Choose which system you are creating in deliberately: a role that should let someone administer part of the platform belongs in Platform Roles, and a role that should let someone act on apps and namespaces belongs in Resource Roles. + +Name custom roles for the responsibility they represent rather than for the seniority of the people who will hold them, and avoid names that echo the default roles of the other system. + +{{% alert color="info" %}} +**Reviewer note:** supply the individual permission labels in both schemas, and screenshots of the two tabs. A full role-to-permission matrix should be added to [Access Model and Role Reference for Private Mendix Platform](/private-mendix-platform/access-model/) and cross-referenced from here. +{{% /alert %}} + +## Managing Groups + +On the **Group Management** page you build and maintain the group hierarchy. Groups typically reflect your organization's structure, and they are what deliver Resource Roles to users at scale. + +The root group is created by Private Mendix Platform automatically and is the foundation of the hierarchy. You can edit its details to match your organization, and every other group descends from it. + +### Creating a Group + +Click **New** and provide: + +* **Parent Group** - where the group sits in the hierarchy. Choose this carefully: every member of the parent, and of everything above it, becomes an inherited member of the new group with the role they already hold. +* **Group Admins** - one or more users who will manage this group's membership. Naming someone here is what allows them to add and remove members, and it requires no administrator role. See [Group Admin](/private-mendix-platform/access-model/#group-admin). +* **Description** - what the group is for. This is what other administrators will use to decide whether a resource belongs here. + +The hierarchy has no depth limit. Add a level when it corresponds to a real boundary of accountability, since each level adds inherited membership to reason about. + +### Adding Members and Assigning Their Roles + +Roles are assigned to the members of a group, not to the group itself. Add a user to the group and assign the Resource Role they should hold there. Different members of the same group can hold different roles, and usually should. + +Members of parent groups appear in the group as inherited members, holding the same role they hold above. You cannot change an inherited member's role from the child group; change it where the membership originates, or add the user directly with a different role. + +{{% alert color="warning" %}} +Because membership cascades downward, a role assigned in a group near the root of the hierarchy reaches every group beneath it. Assign broad roles such as Administrator and Maintainer as close as possible to the groups that need them, rather than high in the tree. +{{% /alert %}} + +### Associating Resources with a Group + +A group needs resources for its members' roles to act upon. + +**Apps.** An app is owned by exactly one group. Assign or move ownership from the App Management page. Apps created through Mendix Studio Pro are owned by the Mendix root group on creation, so transfer ownership after creation if a different group should own them. See [Assigning the App to a New Owner](/private-mendix-platform/reference-guide/admin/company/#ownership). + +**Deployment namespaces.** A namespace can be associated with several groups at once, so operational responsibility can be shared. The namespace's purpose is configured on the namespace itself, in Cluster Manager, rather than on the association. See [Cluster Manager](/private-mendix-platform/reference-guide/admin/company/#cluster-manager). + +{{% alert color="warning" %}} +**Namespace associations do not inherit.** Unlike membership, a namespace association extends neither upward to a group's parents nor downward to its children. A group that owns an app and needs to deploy it must be associated with the target namespace itself. + +If a team reports that they can build an app but not deploy it, this is the first thing to check: confirm that the group owning the app is directly associated with the namespace, not merely descended from a group that is. +{{% /alert %}} + +**Marketplace content.** Components published to the private Marketplace are owned by the user who published them rather than by a group, and are shared with groups by their publisher. See [Sharing Content with Groups](/private-mendix-platform/user-guide/#sharing-content-with-groups). Administering Marketplace content is a Platform Role capability and is documented in [Marketplace](/private-mendix-platform/reference-guide/admin/company/#marketplace). + +### Automating Group Assignment {#automating-group-assignment} + +**Automation Settings** on the Group Management page lets group membership follow the identity provider information mapped onto users' profiles, rather than being assigned by hand. + +Once configured for a profile attribute, membership is derived from that attribute's value when a user arrives: + +* If the value corresponds to an existing group, the user is added to that group. +* If the value does not correspond to any existing group, a group is created for it and the user is made a member. + +This keeps group structure aligned with the organizational data your identity provider already holds, at the cost of allowing the hierarchy to grow on its own. Review the groups it creates periodically, give them proper descriptions and group admins, and place them deliberately in the tree. + +This is a separate mechanism from the **Parse Roles** setting on your identity provider configuration, which maps role and group claims from the token itself. The two can be used together. For how both fit into first-login behavior, see [Federated Users](/private-mendix-platform/access-model/#federated-users). + +{{% alert color="info" %}} +**Reviewer note:** supply the exact field labels in Automation Settings, which profile attributes can be used, where a newly created group is placed in the hierarchy, and what role its members receive. +{{% /alert %}} + +### Monitoring the Hierarchy + +The Group Management page reports live figures for the number of groups, the number of resources owned, the number of namespaces associated with groups, and the average number of members per group. They are useful as a quick check that the hierarchy still matches expectations, particularly where group creation is automated. + +## Auditing Access Changes + +Changes to user accounts are recorded in the platform activity log, along with app creation and deletion, package creation, and platform setting changes. Retention and logging level are configurable, and expired entries can be downloaded from the archive for audit purposes. See [Activity Logs](/private-mendix-platform/reference-guide/admin/company/#activity-logs). + +{{% alert color="info" %}} +**Reviewer note:** confirm which access-management events are captured in the activity log - specifically whether role edits, group membership changes, and namespace associations are logged, or only account changes. This determines how much of an audit story this section can honestly tell. +{{% /alert %}} diff --git a/content/en/docs/private-platform/roles/pmp-access-model.md b/content/en/docs/private-platform/roles/pmp-access-model.md new file mode 100644 index 00000000000..1f63f9f7337 --- /dev/null +++ b/content/en/docs/private-platform/roles/pmp-access-model.md @@ -0,0 +1,280 @@ +--- +title: "Access Model and Role Reference for Private Mendix Platform" +url: /private-mendix-platform/access-model/ +weight: 10 +description: "Describes the access model of Private Mendix Platform, including Platform Roles, Resource Roles, group hierarchy and inheritance, resource ownership, and how permissions combine." +--- + +## Introduction + +Access in Private Mendix Platform is governed by two role systems that operate independently of one another, applied to users who are organized into a hierarchy of groups, which in turn own or are associated with the resources those roles act upon. + +This page describes that model. It is the reference to consult before you design a group hierarchy or define a custom role, and the place to look when the access someone has does not match the access you expected them to have. For the procedures that configure the model, see [Administering Users, Groups, and Roles in Private Mendix Platform](/private-mendix-platform/access-administration/). + +Administrators configure all of it at runtime, from the **Manage** section of admin mode. No part of the model requires a code change to the platform or to your apps. + +## The Two Role Systems + +Private Mendix Platform separates platform-wide privilege from privilege over an individual resource. Role Management presents the two as separate tabs, and they share no permissions. + +{{% alert color="info" %}} +**Reviewer note:** confirm the exact tab labels used in the Role Management page of the current release, so this page matches the UI wording. +{{% /alert %}} + +### Platform Roles + +A Platform Role answers the question *what can this person do on the platform in general?* It is assigned to a user account when the account is created, and can be changed at any time afterwards. Platform Roles are stackable: a user can hold several, and the effective set of permissions is simply everything those roles grant, added together. + +Private Mendix Platform includes the following default Platform Roles. + +| Role | Grants | +| --- | --- | +| **User** | Baseline access to the platform web interface. Every human user needs this role at minimum. | +| **CompanyAdmin** | Everything under **Admin** > **Manage**: app management, user and group management, Marketplace content, deployment clusters, activity logs, and platform statistics. Intended for the people who own day-to-day platform operations. | +| **SystemAdmin** | Everything under **Admin** > **Settings**: identity provider and SSO configuration, version control and CI/CD integrations, licensing, branding, and platform capabilities. Intended for the people who own the infrastructure the platform depends on. | + +{{% alert color="warning" %}} +**CompanyAdmin and SystemAdmin are parallel, not nested.** Neither contains the other. They address different audiences and grant access to different halves of admin mode. Granting CompanyAdmin does not give someone access to identity or licensing settings, and granting SystemAdmin does not give someone the ability to manage users and groups. A user who needs both must be given both. +{{% /alert %}} + +There is only one kind of account. Accounts used by services rather than people are not a separate account type: a service that calls the platform API authenticates as an ordinary account, and what it can do is determined by that account's Platform Role, exactly as it would be for a person. A role such as **API User**, holding only the permissions a particular integration needs, is an example of a Platform Role defined for that purpose. + +{{% alert color="info" %}} +**Reviewer note:** confirm whether a role named API User ships with the platform or is customer-defined, so this paragraph can state it plainly. Note also that [Private Mendix Platform Functionalities - Company Administrators](/private-mendix-platform/reference-guide/admin/company/#user-management) currently describes "API users" as a distinct kind of account. That wording contradicts the model and should be corrected on that page as part of this change. +{{% /alert %}} + +Permissions in a Platform Role fall into the following broad categories: + +* Generic platform access, such as reaching the web interface and creating an app. +* Management capabilities on the **Manage** side, such as app management, user and group management, Marketplace administration, and activity logs. +* Management capabilities on the **Settings** side, such as identity and access configuration, licensing, cluster manager configuration, and webhooks. + +{{% alert color="info" %}} +**Reviewer note:** the three categories above are representative rather than a literal reproduction of the permission schema. Supply the exact category names and the individual permission labels as they appear in the UI, and this list will be replaced with a complete table. +{{% /alert %}} + +### Resource Roles + +A Resource Role answers the question *what can this person do to this app, or this namespace?* It is held by an individual, and it applies only to the resources that the individual reaches it through: the resources owned by the group in which they hold the role, or the single app whose team they were invited to. + +Private Mendix Platform includes the following default Resource Roles. + +| Role | Covers | +| --- | --- | +| **Owner** | Full control of an app, including transferring ownership, inviting team members, and assigning their roles. | +| **Developer** | The complete development and operations set: change the app's source and deploy it. | +| **Contributor** | Development only. Can change the app's source, cannot deploy it. | +| **Operator** | Operations only. Can deploy the app, cannot change its source. | +| **Maintainer** | Oversight of the deployment settings of the apps in scope. | +| **Administrator** | Oversight of the deployment settings of the apps in scope. | + +{{% alert color="info" %}} +**Reviewer note:** Maintainer and Administrator are both concerned with deployment settings, and the table above does not yet distinguish them. Supply the actual difference in their permission sets so each row says something a reader can act on, rather than describing the two identically. +{{% /alert %}} + +{{% alert color="warning" %}} +**Owner is assigned automatically and cannot be granted manually.** It is held by whoever created the app. To move it, transfer ownership of the app rather than assigning the role. See [Assigning the App to a New Owner](/private-mendix-platform/reference-guide/admin/company/#ownership). +{{% /alert %}} + +{{% alert color="warning" %}} +**The Resource Role named Administrator is not a platform administrator.** It grants no access to admin mode and no privilege over the platform. It reaches only the resources owned by the group in which its holder holds it. The platform-wide equivalents are the **CompanyAdmin** and **SystemAdmin** Platform Roles. +{{% /alert %}} + +Permissions in a Resource Role fall into four categories: + +* **Project** - the app lifecycle, its team, version control, and viewing its environments. +* **Build** - packaging, the build pipeline, and the software bill of materials. +* **Deployment** - deploying and managing the app's environments. This is the largest category, and the only one that can be scoped per environment. +* **Monitoring** - logs and metrics. + +Every permission in a Resource Role is expressed as an action on an app, which is why the schema reads as a set of app permissions even for roles concerned mainly with deployment settings. + +{{% alert color="info" %}} +**Reviewer note:** supply the individual permission labels within each of the four categories, and this section will be replaced with a full role-to-permission matrix. +{{% /alert %}} + +#### Per-Environment Scoping + +Deployment is the only permission category that can be limited by environment. Each permission in it can be restricted to any combination of Development, Test, Acceptance, and Production. No other category offers this. + +This is what makes it possible to express a role such as *may deploy freely to Development and Test, and may not deploy to Production at all* without creating separate roles per environment, and it is the mechanism to reach for when a compliance requirement separates production deployment from everyday development. + +### Editing Roles and Creating Custom Roles + +Both systems are fully editable by administrators: + +* The permissions of a default role can be changed. +* A default role cannot be deleted. +* Entirely new roles can be created in either system, with any combination of permissions. + +Changing a role changes the effective access of everyone who holds it, so review who holds a role before editing it. + +### Group Admin + +Group Admin sits outside both role systems. It is not a Platform Role, not a Resource Role, and not governable: it does not appear anywhere among the roles you can view or edit, and its permissions cannot be changed or extended. + +It is assigned invisibly and automatically to the users named in the **Group Admins** field of a group, as a consequence of naming them there. You never assign it yourself and you will not see it listed against a user. + +Its only effect is to let those users manage that group's membership, meaning they can add and remove members. It grants nothing else, and it applies only to the groups for which its holder was designated. + +Consequently, delegating group membership management does not require giving anyone an administrator role. Naming a person as a group admin on their own group is sufficient. See [Working with Groups and App Teams in Private Mendix Platform](/private-mendix-platform/groups-and-app-teams/). + +## Groups + +Groups are how users are organized and how Resource Roles are delivered at scale. They typically mirror your organization: a division, a department, a portfolio, a team. + +### Structure + +Groups form a hierarchical tree. Private Mendix Platform creates the root group automatically, and it is the foundation of everything beneath it. You can edit the root group's details to match your organization. + +Every group other than the root requires three things: + +* **Parent Group** - the group's place in the hierarchy. There is no such thing as a group outside the tree. +* **Group Admins** - one or more users who will manage the group's membership. +* **Description** - a clear statement of the group's purpose. + +The depth of the hierarchy is not limited. + +### A Group Does Not Hold a Role + +This is the point at which the model is most often misread. A group is not granted a role, and a group has no permissions of its own. A group holds *members*, and each member individually holds a Resource Role. The group's function is to own resources, so that the roles its members hold have something to apply to. + +Two members of the same group can legitimately hold different Resource Roles, and often should. A team group might contain several Developers, a few Contributors, and one Operator, all with access to the same app, doing different things to it. + +It follows that a statement such as *this group grants Administrator, so its members are administrators* has the relationship backwards. Members hold roles; the group supplies the scope. + +### Membership Inherits Downward + +Members of a group automatically become members of every group beneath it in the hierarchy, carrying forward the same Resource Role they hold in the higher group. These are shown as inherited members, as distinct from members added directly. + +Inheritance goes to any depth. A member two levels up appears in a grandchild group with the same role they hold two levels up. It does not travel upward: membership of a child group confers nothing in the parent. + +{{% alert color="warning" %}} +Because membership cascades downward without limit, a role granted high in the hierarchy reaches every group below it. Granting a broad Resource Role at or near the root group extends that role across the entire platform. See [Designing Your Access Model](#designing-your-access-model). +{{% /alert %}} + +## Resources Owned by Groups + +A group can own or be associated with three kinds of resource. The ownership rules differ for each, and so does the behavior of that ownership with respect to the hierarchy. + +| Resource | Ownership model | +| --- | --- | +| **App Projects** | Exclusive. An app is owned by exactly one group, so accountability is unambiguous. | +| **Deployment Namespaces** | Shareable. A namespace can be associated with several groups at once, allowing operational responsibility to be shared between teams. | +| **Marketplace Components** | Owned by the individual user who published the component. | + +### App Projects + +An app is owned by one group and one user within it. Members of the owning group reach the app through the Resource Role they hold in that group, whether they hold it directly or by inheritance from a group further up. + +{{% alert color="warning" %}} +**Apps created through Mendix Studio Pro are owned by the Mendix root group.** Ownership is assigned to the root group on creation rather than to the group the creating developer belongs to. An app left in this state is reachable by everyone holding a Resource Role in the root group, and by nobody further down the hierarchy, since membership inherits downward and resource access does not travel upward. Neither is usually what was intended. + +Transfer ownership to the group that should hold it as a routine step after creating an app from Studio Pro. See [Assigning the App to a New Owner](/private-mendix-platform/reference-guide/admin/company/#ownership). +{{% /alert %}} + +### Deployment Namespaces + +Two concepts are involved here and both are meaningful. A **deployment namespace** is the resource. A **namespace purpose** is a scoping tied to that resource, describing what the namespace is for. + +They form a chain: a namespace is associated with a group, and the namespace's purpose is tied to the namespace in turn. So the group is associated with the namespace, and the purpose comes with it as a property of the namespace rather than as something set on the association. Purpose is therefore configured once, on the namespace, and holds for every group associated with it. For how purpose relates to environments, see [Deployment Purpose and DTAP Mode](/private-mendix-platform/user-guide/#deployment-purpose-and-dtap-mode). + +{{% alert color="warning" %}} +**A namespace association does not inherit, in either direction.** Group membership and the Resource Roles that come with it cascade down the hierarchy. A deployment namespace association does not: it extends neither to a group's parents nor to its children. + +For a group to deploy to a namespace, **that group must itself be directly associated with the namespace**, regardless of where either sits in the tree. In practice this means keeping an app project and the namespace it deploys to associated at the same level of the hierarchy. + +This rule is specific to deployment namespaces. App projects are already exclusive to a single group, and Marketplace components follow their own ownership model, so neither is affected by it. +{{% /alert %}} + +### Marketplace Components + +A component published to the private Marketplace is owned by the user who published it, rather than by a group. Ownership therefore does not follow the group hierarchy. + +Access to the Marketplace administration area, where content is approved, categorized, and imported, is a Platform Role permission and not a Resource Role. A user who administers Marketplace content does not need any Resource Role to do so. + +Marketplace content can additionally be shared with groups by its publisher. See [Sharing Content with Groups](/private-mendix-platform/user-guide/#sharing-content-with-groups). + +## How a User Gets Access to an App + +There are three distinct paths, and it is worth keeping them separate when diagnosing why someone can or cannot reach an app. + +1. **Through the owning group.** The user is a member, directly or by inheritance, of the group that owns the app, and holds a Resource Role there. This is the primary path and the one that scales. +2. **Through a direct invitation to the app team.** The app's owner invites an individual onto the team and assigns them a role such as Developer, Contributor, or Operator. This bypasses groups entirely and applies to that one app. Before a user can be invited, their account must exist. See [Editing App Details](/private-mendix-platform/reference-guide/admin/company/#app-details). +3. **Through app sharing, followed by a request.** An app can be shared with groups that do not own it. Sharing makes the app *visible* to those groups; it grants no access. Members who can see a shared app can request access from the app's owner, who decides whether to grant it and with which role. See [Sharing the App with Selected User Groups](/private-mendix-platform/reference-guide/admin/company/#share). + +{{% alert color="info" %}} +**Reviewer note:** confirm the mechanics of the request flow in path 3 - how the request reaches the owner, whether it is notified, and whether granting it creates a direct team membership. +{{% /alert %}} + +## How Permissions Combine + +The two role systems combine differently, and conflating them is the source of most incorrect expectations about effective access. + +### Platform Roles Combine as a Union + +Platform Roles are not scoped to a resource, so there is nothing to reconcile. A user's effective platform permissions are every permission granted by every Platform Role they hold, added together. + +### Resource Roles Combine Only on a Shared Resource + +Resource Roles do not blanket-combine across every group a user belongs to. Two groups that are not in a parent-and-child relationship share no resources, so a user's roles in them never interact: the role held in one group applies to that group's resources and nowhere else. + +Combination happens only when two roles land on the *same* resource. The common case is a user who has been invited directly onto an app's team in one role, and who also inherits a different role on that same app through the group hierarchy. There, and only there, the two are reconciled into a single effective set of permissions on that app. + +### Changes Take Effect Immediately + +When a member's role in a group changes, the change is applied at once to every resource that group owns or is associated with. There is no separate synchronization step to run, and no need to reapply access to individual apps or namespaces after a role change. + +## Federated Users {#federated-users} + +When users sign in through your identity provider rather than with a local account, they still need a place in the group hierarchy and a Resource Role in order to do anything. Three settings determine what happens on first arrival. + +* **Default Group and Default Role.** Every incoming user with no other placement is put into a configured group with a configured role. Pointing these at a deliberately low-privilege landing group gives new arrivals somewhere to be that has no access to real projects, until they are assigned to their actual team. +* **Parse Roles.** When enabled, Private Mendix Platform reads group and role claims from the incoming token and maps them onto Platform Roles and groups automatically. When disabled, no such mapping occurs and every federated user lands on the defaults above, to be assigned afterwards manually, through SCIM, or through the platform API. +* **Automation Settings.** For users whose identity provider information is mapped onto their platform profile, group membership can be driven from the values of those profile attributes. When a user arrives with a value that already corresponds to a group, they are added to that group. When a user arrives with a value that does not, a group is created for it and the user is made a member. This is configured on the Group Management page and is separate from Parse Roles. See [Automating Group Assignment](/private-mendix-platform/access-administration/#automating-group-assignment). + +Users can also be provisioned before their first login, using SCIM, so that their accounts and group placement exist in advance. + +Configuring the identity provider connection itself, including OIDC and SAML setup, attribute mapping, and SCIM tokens, is documented in [Private Mendix Platform Functionalities - System Administrators](/private-mendix-platform/reference-guide/admin/system/#identity--access). + +{{% alert color="info" %}} +**Reviewer note:** supply the exact field labels and locations for Default Group, Default Role, and Parse Roles so this section can point readers at the right screen. +{{% /alert %}} + +## Designing Your Access Model {#designing-your-access-model} + +The rules above have direct consequences for how a hierarchy should be laid out. + +**Keep broad roles rare and high, and let narrow roles do the work low down.** Because membership cascades downward, a Resource Role granted near the root reaches everything beneath it. Roles such as Administrator and Maintainer should be granted sparingly, and as close as possible to the groups that actually need them. Developer, Contributor, and Operator are the roles intended to carry everyday work further down the tree. + +**Associate an app and the namespace it deploys to at the same level.** Since namespace associations do not inherit, a group that owns an app but is not itself associated with a namespace cannot deploy that app, no matter what its parent is associated with. Placing both at the same level avoids the problem entirely. + +**Give federated arrivals a landing group.** A low-privilege group configured as the Default Group means an unrecognized user who signs in successfully still reaches nothing of consequence until an administrator places them. + +**Use per-environment scoping instead of parallel roles.** Where the requirement is that a team may deploy to some environments and not others, scope the Deployment permissions of one role rather than maintaining two similar roles. + +**Mirror your organization, but only as deeply as you need.** Depth is unlimited, and each additional level adds inherited membership to reason about. Add a level when it corresponds to a real boundary of accountability. + +### Worked Example + +Consider the following hierarchy. + +```text +Mendix (root) +├── Platform Admin +│ └── App Portfolios +│ └── App Portfolio 1 +└── Preboarding +``` + +A user who is a member of **App Portfolios** with the Developer role is also, by inheritance, a Developer in **App Portfolio 1**, and can develop and deploy the apps that group owns. That same user is not a member of **Preboarding**, which is not beneath their group, and has no access to anything Preboarding owns. + +A user who is a member of **Platform Admin** with the Administrator role holds it in **App Portfolios** and **App Portfolio 1** as well, because both are beneath Platform Admin. Adding a new portfolio group under App Portfolios extends that user's Administrator role into it automatically. This is the reason to grant Administrator low rather than high. + +If **App Portfolio 1** owns an app that must deploy to a namespace, App Portfolio 1 must be associated with that namespace itself. Associating the namespace with **App Portfolios**, or with **Mendix**, does not enable the deployment. + +**Preboarding** is a natural candidate for the Default Group in an SSO configuration: users who arrive without a recognized placement land there, hold whatever low-privilege Default Role is configured, and reach nothing owned elsewhere in the tree. + +{{% alert color="info" %}} +**Reviewer note:** a diagram of this hierarchy showing groups, members, roles, owned apps, and namespace associations exists in the supporting document set and should be attached here in place of the code block above. +{{% /alert %}} diff --git a/content/en/docs/private-platform/roles/pmp-groups-and-app-teams.md b/content/en/docs/private-platform/roles/pmp-groups-and-app-teams.md new file mode 100644 index 00000000000..79933b37ab0 --- /dev/null +++ b/content/en/docs/private-platform/roles/pmp-groups-and-app-teams.md @@ -0,0 +1,110 @@ +--- +title: "Working with Groups and App Teams in Private Mendix Platform" +url: /private-mendix-platform/groups-and-app-teams/ +weight: 30 +description: "Documents how users manage the membership of groups they administer, and how app owners manage the team and sharing of their apps in Private Mendix Platform." +--- + +## Introduction + +Not all access management in Private Mendix Platform requires an administrator. Two responsibilities are deliberately delegated to ordinary users: managing the membership of a group you have been made responsible for, and managing the team on an app you own. + +This page documents both, along with how to work out what access you yourself hold and why. None of it requires switching to admin mode. + +## Understanding Your Own Access + +Your access comes from two independent sources, and it is worth knowing which one is responsible for what you can and cannot do. + +Your **Platform Role** determines what you can do on the platform in general, such as signing in and creating an app. It is set on your account by an administrator. + +Your **Resource Roles** determine what you can do to individual apps and namespaces. You hold these as a member of a group, or by direct invitation onto an app's team. A powerful Platform Role does not give you access to any app, and a powerful role on an app does not give you any platform-wide privilege. + +If you cannot reach an app you expect to reach, the question to ask is not what role you have, but *through which group*. You have access to an app if you are a member of the group that owns it, or of a group above that one in the hierarchy, or if the app's owner invited you directly. Membership of an unrelated group, however senior, grants nothing. + +You can review your own profile, password, personal access tokens, and service credentials from your account page. See [Configuring Your User Profile and Settings](/private-mendix-platform/user-guide/#configuring-your-user-profile-and-settings). + +{{% alert color="info" %}} +**Reviewer note:** confirm whether users have a screen that shows the roles they hold and the groups they hold them in. If one exists, it should be named here, as this is the first thing a user needs when access does not behave as expected. +{{% /alert %}} + +## Managing Your Group's Membership + +If you have been named a group admin on a group, you can manage that group's membership from the **Manage My Group** page. The left navigation menu lists every group you administer. + +For each group you can: + +* View its current members. +* Search the platform's users by name or email address and add them to the group. +* Remove members from the group. + +Being a group admin lets you change *who is in* the group. It does not let you create groups, change the hierarchy, change which resources the group owns, or edit roles. Those require an administrator. See [Administering Users, Groups, and Roles in Private Mendix Platform](/private-mendix-platform/access-administration/). + +{{% alert color="warning" %}} +Adding a member to your group gives them access to everything your group owns, and to everything owned by every group beneath yours in the hierarchy, with the role they hold in your group. Before adding someone, be clear about what sits below your group. +{{% /alert %}} + +Members shown as inherited come from groups above yours. You cannot remove them from your group, because their membership does not originate there. If an inherited member should not have access, raise it with the administrator of the group they come from. + +{{% alert color="info" %}} +**Reviewer note:** confirm whether a group admin assigns a member's Resource Role when adding them, or whether membership and role assignment are separate actions with the latter reserved to administrators. The current reference page describes only adding and removing members, which suggests the latter, but this needs confirming because it materially changes what delegation means. +{{% /alert %}} + +## Managing Your App's Team + +The **Teams** page of an app shows everyone who has access to it and the role each of them holds. + +### Owner + +The user who created the app becomes its owner automatically, and ownership cannot be assigned as a role. The owner has full control of the app, including inviting members, assigning their roles, and transferring ownership. Apps created through Mendix Studio Pro are owned by the Mendix root group on creation, so ask an administrator to transfer ownership if it should sit elsewhere. + +### Direct and Inherited Members + +The Teams page distinguishes two kinds of member. + +**Direct members** were invited onto this app specifically, and their roles were assigned by the owner. Their access applies to this app and nothing else. + +**Inherited members** reach the app through the group hierarchy rather than through an invitation. Members of the group that owns the app are inherited into it, as are members of the groups above it, each carrying the role they hold in their own group. Their roles are determined by group configuration, not by the app owner, and cannot be changed from the Teams page. To change an inherited member's role, the change has to be made in the group it comes from. + +This split is deliberate: direct membership handles the individual exceptions, and inherited membership handles the standing arrangement, so team composition stays consistent with organizational governance without being maintained app by app. + +### Inviting a Member + +As the app's owner, invite a user onto the team and assign the role they should hold on it, such as **Developer**, **Contributor**, or **Operator**. Which of these to choose follows from what the person will do: + +* **Developer** if they will change the app's source and deploy it. +* **Contributor** if they will change the app's source but should not deploy it. +* **Operator** if they will deploy the app but should not change its source. + +For what each role grants in full, see [Resource Roles](/private-mendix-platform/access-model/#resource-roles). + +The user must already have an account on the platform before you can invite them. If they do not, ask an administrator to create one. + +{{% alert color="warning" %}} +An invitation grants access to this app only. It is the right mechanism for a genuine exception, such as a specialist joining for one project. Where a whole team needs standing access, group membership is the mechanism to use instead, because it does not have to be maintained app by app. +{{% /alert %}} + +### Sharing Your App with Other Groups + +You can share your app with groups that do not own it. Sharing makes the app visible to those groups, so that people who would otherwise not know it exists can find it. It grants no access of any kind. + +Members of a group the app has been shared with can request access from you. You decide whether to grant it, and with which role. + +Share an app when you want it discoverable across the organization, for example a reference implementation or an internal service other teams may want to build against. Do not use sharing to grant access; use a team invitation or group membership for that. + +{{% alert color="info" %}} +**Reviewer note:** confirm how an access request reaches the app owner, whether the owner is notified, and what granting a request produces - a direct team membership with a chosen role, or something else. +{{% /alert %}} + +### Deploying to a Namespace + +Holding a role that permits deployment is necessary but not sufficient: the group that owns the app must also be associated with the namespace you are deploying to. That association is made by an administrator, and it does not follow the group hierarchy, so a parent group's association does not help. + +If you hold Developer or Operator on an app and deployment is nevertheless unavailable, the likely cause is a missing namespace association rather than a role problem. Ask an administrator to confirm that the group owning the app is directly associated with the target namespace. See [Associating Resources with a Group](/private-mendix-platform/access-administration/#associating-resources-with-a-group). + +## Finding Your Group's Apps and Content + +Apps owned by groups you belong to are listed on the **My Group Apps** page. See [My Group Apps](/private-mendix-platform/reference-guide/common/group-apps/). + +Marketplace content shared with your groups is listed on the **Group Content** page. See [Group Content](/private-mendix-platform/reference-guide/common/group-content/). + +Content you have published yourself is listed on **My Content**, and you can share it with groups from there. See [Sharing Content with Groups](/private-mendix-platform/user-guide/#sharing-content-with-groups). From 933b88de503508c3203d9ffcc2de45935690fded Mon Sep 17 00:00:00 2001 From: katarzyna_koltun Date: Wed, 21 Oct 2026 18:13:06 +0200 Subject: [PATCH 02/12] updates --- .../roles/pmp-access-administration.md | 25 ++++++++++--------- 1 file changed, 13 insertions(+), 12 deletions(-) diff --git a/content/en/docs/private-platform/roles/pmp-access-administration.md b/content/en/docs/private-platform/roles/pmp-access-administration.md index 6711aea0dfc..7e2a661cbfe 100644 --- a/content/en/docs/private-platform/roles/pmp-access-administration.md +++ b/content/en/docs/private-platform/roles/pmp-access-administration.md @@ -7,28 +7,33 @@ description: "Documents the administrator tasks for managing user accounts, defi ## Introduction -This page documents the tasks that configure access in Private Mendix Platform: creating and maintaining user accounts, defining what roles exist and what they grant, building the group hierarchy, and associating apps and deployment namespaces with the groups that need them. +This document describes the tasks that configure access in Private Mendix Platform: -These tasks require the **CompanyAdmin** Platform Role. Configuring the identity provider that federated users authenticate against is a separate concern requiring **SystemAdmin**, and is documented in [Private Mendix Platform Functionalities - System Administrators](/private-mendix-platform/reference-guide/admin/system/). +* Creating and maintaining user accounts +* Defining what roles exist and what they grant +* Building the group hierarchy +* Associating apps and deployment namespaces with the groups that need them. + +### Prerequisites + +To perform the above tasks, you must have the **CompanyAdmin** platform role. Configuring the identity provider that federated users authenticate against is a separate concern requiring **SystemAdmin**, and is documented in [Private Mendix Platform Functionalities - System Administrators](/private-mendix-platform/reference-guide/admin/system/). Before making structural changes, read [Access Model and Role Reference for Private Mendix Platform](/private-mendix-platform/access-model/). Two rules in particular have consequences that are not visible from the screens described below: group membership inherits downward without limit, and deployment namespace associations do not inherit at all. ## Accessing the Access Management Pages +To open the **Access Management** page, peform the following steps: + 1. Click your profile picture in the top right corner of the screen and select **Switch to Admin Mode**. 2. In the left navigation menu, open the **Manage** section. -User accounts, groups, and roles are managed from this section. - -{{% alert color="info" %}} -**Reviewer note:** confirm the exact navigation path and page names in the current release, in particular whether Role Management is a page of its own under **Manage** or a tab within User Management. -{{% /alert %}} +From this section, you can manage user accounts, groups, and roles. ## Managing User Accounts On the **User Management** page you can create and maintain the accounts that use your platform, whether they belong to people or to services. -There is one kind of account. What an account can do comes from the Platform Roles assigned to it, not from any account type, so the same page and the same procedure serve a developer, an administrator, and an integration. +What an account can do comes from the platform roles assigned to it, not from any account type, so the same page and the same procedure serve a developer, an administrator, and an integration. To create an account, click **New** and provide the user's name and email address, then assign the Platform Roles the account requires. An account with no Platform Role cannot use the platform, so at minimum assign **User**. @@ -46,10 +51,6 @@ The **Actions** tab additionally lets you log out every user currently signed in Some of these actions depend on how the account authenticates rather than on what kind of account it is. Setting a password, for instance, applies to accounts that sign in with platform credentials and not to accounts that authenticate through your identity provider. -{{% alert color="info" %}} -**Reviewer note:** confirm which of the actions above are unavailable for accounts that authenticate through an identity provider. The current [Company Administrators](/private-mendix-platform/reference-guide/admin/company/#user-management) page marks several of them "local users only", which reads as an account-type restriction; the list needs restating in terms of authentication method. -{{% /alert %}} - {{% alert color="warning" %}} Assigning a Platform Role gives a user platform-wide capability and nothing else. It does not give them access to any app, namespace, or Marketplace item. Access to resources comes from group membership or an app team invitation, described below. {{% /alert %}} From cd09cb2488106dd0213ff49229315fd15c687859 Mon Sep 17 00:00:00 2001 From: katarzyna_koltun Date: Wed, 21 Oct 2026 18:17:18 +0200 Subject: [PATCH 03/12] updates --- .../roles/pmp-access-administration.md | 12 ------------ 1 file changed, 12 deletions(-) diff --git a/content/en/docs/private-platform/roles/pmp-access-administration.md b/content/en/docs/private-platform/roles/pmp-access-administration.md index 7e2a661cbfe..91b7e95b9df 100644 --- a/content/en/docs/private-platform/roles/pmp-access-administration.md +++ b/content/en/docs/private-platform/roles/pmp-access-administration.md @@ -112,10 +112,6 @@ Click **New** in the relevant tab, name the role, and select its permissions. Ch Name custom roles for the responsibility they represent rather than for the seniority of the people who will hold them, and avoid names that echo the default roles of the other system. -{{% alert color="info" %}} -**Reviewer note:** supply the individual permission labels in both schemas, and screenshots of the two tabs. A full role-to-permission matrix should be added to [Access Model and Role Reference for Private Mendix Platform](/private-mendix-platform/access-model/) and cross-referenced from here. -{{% /alert %}} - ## Managing Groups On the **Group Management** page you build and maintain the group hierarchy. Groups typically reflect your organization's structure, and they are what deliver Resource Roles to users at scale. @@ -171,10 +167,6 @@ This keeps group structure aligned with the organizational data your identity pr This is a separate mechanism from the **Parse Roles** setting on your identity provider configuration, which maps role and group claims from the token itself. The two can be used together. For how both fit into first-login behavior, see [Federated Users](/private-mendix-platform/access-model/#federated-users). -{{% alert color="info" %}} -**Reviewer note:** supply the exact field labels in Automation Settings, which profile attributes can be used, where a newly created group is placed in the hierarchy, and what role its members receive. -{{% /alert %}} - ### Monitoring the Hierarchy The Group Management page reports live figures for the number of groups, the number of resources owned, the number of namespaces associated with groups, and the average number of members per group. They are useful as a quick check that the hierarchy still matches expectations, particularly where group creation is automated. @@ -182,7 +174,3 @@ The Group Management page reports live figures for the number of groups, the num ## Auditing Access Changes Changes to user accounts are recorded in the platform activity log, along with app creation and deletion, package creation, and platform setting changes. Retention and logging level are configurable, and expired entries can be downloaded from the archive for audit purposes. See [Activity Logs](/private-mendix-platform/reference-guide/admin/company/#activity-logs). - -{{% alert color="info" %}} -**Reviewer note:** confirm which access-management events are captured in the activity log - specifically whether role edits, group membership changes, and namespace associations are logged, or only account changes. This determines how much of an audit story this section can honestly tell. -{{% /alert %}} From 75a4fa1b85415e671a0136d85bfa020cdbe454b9 Mon Sep 17 00:00:00 2001 From: katarzyna-koltun-mx <108737161+katarzyna-koltun-mx@users.noreply.github.com> Date: Thu, 22 Oct 2026 17:07:24 +0200 Subject: [PATCH 04/12] Update _index.md --- content/en/docs/private-platform/roles/_index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/en/docs/private-platform/roles/_index.md b/content/en/docs/private-platform/roles/_index.md index 9b375a9c771..003e64ee455 100644 --- a/content/en/docs/private-platform/roles/_index.md +++ b/content/en/docs/private-platform/roles/_index.md @@ -28,7 +28,7 @@ The following sections contain more information about platform and resource role ### Platform Roles {#platform-role} -Platform roles define what a user can do on the platform in general. They are assigned to a user account at creation, and can be edited afterwards. Their scope involves the whole plaform. Having multiple platform roles gives a user all the access rights of every role they hold. +Platform roles define what a user can do on the platform in general. They are assigned to a user account at creation, and can be edited afterward. Their scope involves the whole plaform. Having multiple platform roles gives a user all the access rights of every role they hold. ### Resource Roles {#resource-role} @@ -40,4 +40,4 @@ Resource roles define what a user can do with specific resources, such as a spec * [Administering Users, Groups, and Roles in Private Mendix Platform](/private-mendix-platform/access-administration/) - Refer to this document for information about creating user accounts, defining or editing roles, building your group hierarchy, and associating apps and namespaces with groups. Those tasks require the **CompanyAdmin** Platform Role. * [Working with Groups and App Teams in Private Mendix Platform](/private-mendix-platform/groups-and-app-teams/) - Refer to this document for information about managing the membership of a group you administer, or a team on an app you own. Those tasks require no administrator role. * [Private Mendix Platform Functionalities - System Administrators](/private-mendix-platform/reference-guide/admin/system/) - Refer to this document for information about identity provider configuration, including connect an identity provider, configuring SCIM provisioning, and adjusting login session preferences. -* [Federated Users](/private-mendix-platform/access-model/#federated-users) - Refer to this document for information about what happens to a federated user on first login, and where they land in the group hierarchy. \ No newline at end of file +* [Federated Users](/private-mendix-platform/access-model/#federated-users) - Refer to this document for information about what happens to a federated user on first login, and where they land in the group hierarchy. From 9df18aa7af2d9ea875e838bce7ed7b8db3097190 Mon Sep 17 00:00:00 2001 From: katarzyna-koltun-mx <108737161+katarzyna-koltun-mx@users.noreply.github.com> Date: Thu, 22 Oct 2026 17:09:08 +0200 Subject: [PATCH 05/12] Update pmp-access-administration.md --- .../en/docs/private-platform/roles/pmp-access-administration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/private-platform/roles/pmp-access-administration.md b/content/en/docs/private-platform/roles/pmp-access-administration.md index 91b7e95b9df..b2b53065b81 100644 --- a/content/en/docs/private-platform/roles/pmp-access-administration.md +++ b/content/en/docs/private-platform/roles/pmp-access-administration.md @@ -65,7 +65,7 @@ Give each integration its own account and its own narrowly scoped role rather th **Reviewer note:** confirm whether a role named API User ships with the platform or is customer-defined. Note also that [Private Mendix Platform Functionalities - Company Administrators](/private-mendix-platform/reference-guide/admin/company/#user-management) currently presents "API users" as a separate kind of account, and that several of the per-account actions on that page are described as available to "local users only". Both need reconciling with the single-account-kind model as part of this change. {{% /alert %}} -### Sign-In and Lockout Behavior +### Sign-in and Lockout Behavior Session limits, automatic disabling of unused accounts, failed sign-in lockout, and lockout duration are platform-wide settings rather than per-account ones, and are configured by a system administrator. See [Preferences](/private-mendix-platform/reference-guide/admin/system/#preferences-1). From 6a9785aca75e5236c19cc5d0d4c35cc6454ea4a1 Mon Sep 17 00:00:00 2001 From: katarzyna_koltun Date: Thu, 22 Oct 2026 17:22:48 +0200 Subject: [PATCH 06/12] draft --- .../roles/pmp-access-administration.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/content/en/docs/private-platform/roles/pmp-access-administration.md b/content/en/docs/private-platform/roles/pmp-access-administration.md index 91b7e95b9df..704d2af4372 100644 --- a/content/en/docs/private-platform/roles/pmp-access-administration.md +++ b/content/en/docs/private-platform/roles/pmp-access-administration.md @@ -22,7 +22,7 @@ Before making structural changes, read [Access Model and Role Reference for Priv ## Accessing the Access Management Pages -To open the **Access Management** page, peform the following steps: +To open the **Access Management** page, perform the following steps: 1. Click your profile picture in the top right corner of the screen and select **Switch to Admin Mode**. 2. In the left navigation menu, open the **Manage** section. @@ -35,9 +35,13 @@ On the **User Management** page you can create and maintain the accounts that us What an account can do comes from the platform roles assigned to it, not from any account type, so the same page and the same procedure serve a developer, an administrator, and an integration. +### Creating Accounts + To create an account, click **New** and provide the user's name and email address, then assign the Platform Roles the account requires. An account with no Platform Role cannot use the platform, so at minimum assign **User**. -By clicking **More Actions** by an existing account you can: +### More Actions + +By clicking **More Actions** by an existing account, you can perform the following tasks: * Edit the user's name and email address. * Assign or remove Platform Roles. @@ -51,8 +55,8 @@ The **Actions** tab additionally lets you log out every user currently signed in Some of these actions depend on how the account authenticates rather than on what kind of account it is. Setting a password, for instance, applies to accounts that sign in with platform credentials and not to accounts that authenticate through your identity provider. -{{% alert color="warning" %}} -Assigning a Platform Role gives a user platform-wide capability and nothing else. It does not give them access to any app, namespace, or Marketplace item. Access to resources comes from group membership or an app team invitation, described below. +{{% alert color="info" %}} +Assigning a Platform Role gives a user platform-wide capability to perform specific tasks. However, it does not give them access to any app, namespace, or Marketplace item. Access to resources comes from group membership or an app team invitation, as described in the following sections. {{% /alert %}} ### Accounts Used by Services From 67f5f693cb32bdcfbcad6cc7b7f5aa89db6242d8 Mon Sep 17 00:00:00 2001 From: katarzyna_koltun Date: Thu, 22 Oct 2026 20:14:31 +0200 Subject: [PATCH 07/12] draft --- .../en/docs/private-platform/roles/_index.md | 2 +- .../roles/pmp-access-administration.md | 36 ++++++++++--------- 2 files changed, 20 insertions(+), 18 deletions(-) diff --git a/content/en/docs/private-platform/roles/_index.md b/content/en/docs/private-platform/roles/_index.md index 003e64ee455..2a97c328911 100644 --- a/content/en/docs/private-platform/roles/_index.md +++ b/content/en/docs/private-platform/roles/_index.md @@ -18,7 +18,7 @@ Both axes are configured by administrators at runtime through Dynamic Role Manag This document explains the two axes. Other articles in this section describe the model, the administrative tasks that configure it, and the day-to-day tasks that users, group administrators, and app owners perform within it. -## Understanding the Two Role Systems +## Understanding the Two Role Systems {#role-systems} Instead of a single ladder of roles, with an administrator at the top who can do everything, Private Mendix Platform has two role systems, that is, [platform roles](#platform-role) and [resource roles](#resource-role). Each role system has its own permission schema, its own assignment mechanism, and its own scope. diff --git a/content/en/docs/private-platform/roles/pmp-access-administration.md b/content/en/docs/private-platform/roles/pmp-access-administration.md index dafedc1437c..aa02c535d42 100644 --- a/content/en/docs/private-platform/roles/pmp-access-administration.md +++ b/content/en/docs/private-platform/roles/pmp-access-administration.md @@ -61,21 +61,17 @@ Assigning a Platform Role gives a user platform-wide capability to perform speci ### Accounts Used by Services -A service that calls the platform API signs in as an ordinary account, and what it can do is determined by that account's Platform Role. A role such as **API User**, carrying only the permissions one integration needs, is an example of a Platform Role defined for this purpose. +A service that calls the platform API signs in as an ordinary account, and what it can do is determined by that account's platform role. A role such as *API User*, carrying only the permissions one integration needs, is an example of a platform role defined for this purpose. -Give each integration its own account and its own narrowly scoped role rather than reusing an administrator account. Because the account is ordinary, everything else on this page applies to it: it can be blocked, its roles can be changed, and its actions appear in the activity log. - -{{% alert color="info" %}} -**Reviewer note:** confirm whether a role named API User ships with the platform or is customer-defined. Note also that [Private Mendix Platform Functionalities - Company Administrators](/private-mendix-platform/reference-guide/admin/company/#user-management) currently presents "API users" as a separate kind of account, and that several of the per-account actions on that page are described as available to "local users only". Both need reconciling with the single-account-kind model as part of this change. -{{% /alert %}} +Give each integration its own account and its own narrowly scoped role rather than reusing an administrator account. Accounts used by services behave the same as all other accounts. That is, they can be blocked, their roles can be changed, and their actions appear in the activity log. ### Sign-in and Lockout Behavior -Session limits, automatic disabling of unused accounts, failed sign-in lockout, and lockout duration are platform-wide settings rather than per-account ones, and are configured by a system administrator. See [Preferences](/private-mendix-platform/reference-guide/admin/system/#preferences-1). +Session limits, automatic disabling of unused accounts, failed sign-in lockout, and lockout duration are platform-wide settings rather than per-account ones, and are configured by a system administrator. For more information, see [Preferences](/private-mendix-platform/reference-guide/admin/system/#preferences-1). ## Managing Roles -Role Management is where you decide what roles exist and what each one grants. It presents Platform Roles and Resource Roles separately, because they are separate systems with separate permission schemas. For what each default role grants, see [The Two Role Systems](/private-mendix-platform/access-model/#the-two-role-systems). +On the **Role Management > Platform Roles** and **Role Management > Resource Roles** pages, you can create roles and configure their permissions. For more information about what each default role grants, see [Understanding the Two Role Systems](/private-mendix-platform/access-management/#role-systems). In both systems: @@ -84,7 +80,7 @@ In both systems: * You can create new roles with any combination of permissions. {{% alert color="warning" %}} -Editing a role changes the effective access of everyone who holds it, immediately. Before editing, check how many users hold the role and what resources they reach through it. Where a change applies to some users and not others, create a new role instead of editing an existing one. +Editing a role immediately changes the effective access of everyone who holds it. Before editing, check how many users hold the role and what resources they reach through it. Where a change applies to some users and not others, create a new role instead of editing an existing one. {{% /alert %}} ### Editing a Platform Role @@ -124,7 +120,7 @@ The root group is created by Private Mendix Platform automatically and is the fo ### Creating a Group -Click **New** and provide: +To create a group, click **New** and specify the following information: * **Parent Group** - where the group sits in the hierarchy. Choose this carefully: every member of the parent, and of everything above it, becomes an inherited member of the new group with the role they already hold. * **Group Admins** - one or more users who will manage this group's membership. Naming someone here is what allows them to add and remove members, and it requires no administrator role. See [Group Admin](/private-mendix-platform/access-model/#group-admin). @@ -138,7 +134,7 @@ Roles are assigned to the members of a group, not to the group itself. Add a use Members of parent groups appear in the group as inherited members, holding the same role they hold above. You cannot change an inherited member's role from the child group; change it where the membership originates, or add the user directly with a different role. -{{% alert color="warning" %}} +{{% alert color="info" %}} Because membership cascades downward, a role assigned in a group near the root of the hierarchy reaches every group beneath it. Assign broad roles such as Administrator and Maintainer as close as possible to the groups that need them, rather than high in the tree. {{% /alert %}} @@ -146,21 +142,27 @@ Because membership cascades downward, a role assigned in a group near the root o A group needs resources for its members' roles to act upon. -**Apps.** An app is owned by exactly one group. Assign or move ownership from the App Management page. Apps created through Mendix Studio Pro are owned by the Mendix root group on creation, so transfer ownership after creation if a different group should own them. See [Assigning the App to a New Owner](/private-mendix-platform/reference-guide/admin/company/#ownership). +#### Apps + +An app is owned by exactly one group. Assign or move ownership from the App Management page. Apps created through Mendix Studio Pro are owned by the Mendix root group on creation, so transfer ownership after creation if a different group should own them. See [Assigning the App to a New Owner](/private-mendix-platform/reference-guide/admin/company/#ownership). -**Deployment namespaces.** A namespace can be associated with several groups at once, so operational responsibility can be shared. The namespace's purpose is configured on the namespace itself, in Cluster Manager, rather than on the association. See [Cluster Manager](/private-mendix-platform/reference-guide/admin/company/#cluster-manager). +#### Deployment Namespaces + +A namespace can be associated with several groups at once, so operational responsibility can be shared. The namespace's purpose is configured on the namespace itself, in Cluster Manager, rather than on the association. See [Cluster Manager](/private-mendix-platform/reference-guide/admin/company/#cluster-manager). {{% alert color="warning" %}} -**Namespace associations do not inherit.** Unlike membership, a namespace association extends neither upward to a group's parents nor downward to its children. A group that owns an app and needs to deploy it must be associated with the target namespace itself. +Unlike membership, namespace associations are not inherited. That is, a namespace association does not extend to a parent group, or to child groups. A group that owns an app and needs to deploy it must be associated with the target namespace itself. -If a team reports that they can build an app but not deploy it, this is the first thing to check: confirm that the group owning the app is directly associated with the namespace, not merely descended from a group that is. +If a team reports that they can build an app but not deploy it, verify that the group owning the app is directly associated with the namespace, not merely descended from a group that is. {{% /alert %}} -**Marketplace content.** Components published to the private Marketplace are owned by the user who published them rather than by a group, and are shared with groups by their publisher. See [Sharing Content with Groups](/private-mendix-platform/user-guide/#sharing-content-with-groups). Administering Marketplace content is a Platform Role capability and is documented in [Marketplace](/private-mendix-platform/reference-guide/admin/company/#marketplace). +#### Marketplace Contents + +Components published to the private Marketplace are owned by the user who published them rather than by a group, and are shared with groups by their publisher. See [Sharing Content with Groups](/private-mendix-platform/user-guide/#sharing-content-with-groups). Administering Marketplace content is a platform role capability, and is documented in [Marketplace](/private-mendix-platform/reference-guide/admin/company/#marketplace). ### Automating Group Assignment {#automating-group-assignment} -**Automation Settings** on the Group Management page lets group membership follow the identity provider information mapped onto users' profiles, rather than being assigned by hand. +**Automation Settings** on the Group Management page let group membership follow the identity provider information mapped onto users' profiles, rather than being assigned by hand. Once configured for a profile attribute, membership is derived from that attribute's value when a user arrives: From fcb2c18929feb46e45effb85fa9015787c195bed Mon Sep 17 00:00:00 2001 From: katarzyna_koltun Date: Fri, 23 Oct 2026 15:52:23 +0200 Subject: [PATCH 08/12] updates --- .../roles/pmp-access-model.md | 20 +++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/content/en/docs/private-platform/roles/pmp-access-model.md b/content/en/docs/private-platform/roles/pmp-access-model.md index 1f63f9f7337..7e08ca9b2f1 100644 --- a/content/en/docs/private-platform/roles/pmp-access-model.md +++ b/content/en/docs/private-platform/roles/pmp-access-model.md @@ -2,7 +2,7 @@ title: "Access Model and Role Reference for Private Mendix Platform" url: /private-mendix-platform/access-model/ weight: 10 -description: "Describes the access model of Private Mendix Platform, including Platform Roles, Resource Roles, group hierarchy and inheritance, resource ownership, and how permissions combine." +description: "Describes the access model of Private Mendix Platform, including platform roles, Resource Roles, group hierarchy and inheritance, resource ownership, and how permissions combine." --- ## Introduction @@ -23,9 +23,9 @@ Private Mendix Platform separates platform-wide privilege from privilege over an ### Platform Roles -A Platform Role answers the question *what can this person do on the platform in general?* It is assigned to a user account when the account is created, and can be changed at any time afterwards. Platform Roles are stackable: a user can hold several, and the effective set of permissions is simply everything those roles grant, added together. +A platform role answers the question *what can this person do on the platform in general?* It is assigned to a user account when the account is created, and can be changed at any time afterwards. Platform roles are stackable: a user can hold several, and the effective set of permissions is simply everything those roles grant, added together. -Private Mendix Platform includes the following default Platform Roles. +Private Mendix Platform includes the following default platform roles. | Role | Grants | | --- | --- | @@ -37,13 +37,13 @@ Private Mendix Platform includes the following default Platform Roles. **CompanyAdmin and SystemAdmin are parallel, not nested.** Neither contains the other. They address different audiences and grant access to different halves of admin mode. Granting CompanyAdmin does not give someone access to identity or licensing settings, and granting SystemAdmin does not give someone the ability to manage users and groups. A user who needs both must be given both. {{% /alert %}} -There is only one kind of account. Accounts used by services rather than people are not a separate account type: a service that calls the platform API authenticates as an ordinary account, and what it can do is determined by that account's Platform Role, exactly as it would be for a person. A role such as **API User**, holding only the permissions a particular integration needs, is an example of a Platform Role defined for that purpose. +There is only one kind of account. Accounts used by services rather than people are not a separate account type: a service that calls the platform API authenticates as an ordinary account, and what it can do is determined by that account's platform role, exactly as it would be for a person. A role such as **API User**, holding only the permissions a particular integration needs, is an example of a platform role defined for that purpose. {{% alert color="info" %}} **Reviewer note:** confirm whether a role named API User ships with the platform or is customer-defined, so this paragraph can state it plainly. Note also that [Private Mendix Platform Functionalities - Company Administrators](/private-mendix-platform/reference-guide/admin/company/#user-management) currently describes "API users" as a distinct kind of account. That wording contradicts the model and should be corrected on that page as part of this change. {{% /alert %}} -Permissions in a Platform Role fall into the following broad categories: +Permissions in a platform role fall into the following broad categories: * Generic platform access, such as reaching the web interface and creating an app. * Management capabilities on the **Manage** side, such as app management, user and group management, Marketplace administration, and activity logs. @@ -77,7 +77,7 @@ Private Mendix Platform includes the following default Resource Roles. {{% /alert %}} {{% alert color="warning" %}} -**The Resource Role named Administrator is not a platform administrator.** It grants no access to admin mode and no privilege over the platform. It reaches only the resources owned by the group in which its holder holds it. The platform-wide equivalents are the **CompanyAdmin** and **SystemAdmin** Platform Roles. +**The Resource Role named Administrator is not a platform administrator.** It grants no access to admin mode and no privilege over the platform. It reaches only the resources owned by the group in which its holder holds it. The platform-wide equivalents are the **CompanyAdmin** and **SystemAdmin** platform roles. {{% /alert %}} Permissions in a Resource Role fall into four categories: @@ -111,7 +111,7 @@ Changing a role changes the effective access of everyone who holds it, so review ### Group Admin -Group Admin sits outside both role systems. It is not a Platform Role, not a Resource Role, and not governable: it does not appear anywhere among the roles you can view or edit, and its permissions cannot be changed or extended. +Group Admin sits outside both role systems. It is not a platform role, not a Resource Role, and not governable: it does not appear anywhere among the roles you can view or edit, and its permissions cannot be changed or extended. It is assigned invisibly and automatically to the users named in the **Group Admins** field of a group, as a consequence of naming them there. You never assign it yourself and you will not see it listed against a user. @@ -191,7 +191,7 @@ This rule is specific to deployment namespaces. App projects are already exclusi A component published to the private Marketplace is owned by the user who published it, rather than by a group. Ownership therefore does not follow the group hierarchy. -Access to the Marketplace administration area, where content is approved, categorized, and imported, is a Platform Role permission and not a Resource Role. A user who administers Marketplace content does not need any Resource Role to do so. +Access to the Marketplace administration area, where content is approved, categorized, and imported, is a platform role permission and not a Resource Role. A user who administers Marketplace content does not need any Resource Role to do so. Marketplace content can additionally be shared with groups by its publisher. See [Sharing Content with Groups](/private-mendix-platform/user-guide/#sharing-content-with-groups). @@ -213,7 +213,7 @@ The two role systems combine differently, and conflating them is the source of m ### Platform Roles Combine as a Union -Platform Roles are not scoped to a resource, so there is nothing to reconcile. A user's effective platform permissions are every permission granted by every Platform Role they hold, added together. +Platform roles are not scoped to a resource, so there is nothing to reconcile. A user's effective platform permissions are every permission granted by every platform role they hold, added together. ### Resource Roles Combine Only on a Shared Resource @@ -230,7 +230,7 @@ When a member's role in a group changes, the change is applied at once to every When users sign in through your identity provider rather than with a local account, they still need a place in the group hierarchy and a Resource Role in order to do anything. Three settings determine what happens on first arrival. * **Default Group and Default Role.** Every incoming user with no other placement is put into a configured group with a configured role. Pointing these at a deliberately low-privilege landing group gives new arrivals somewhere to be that has no access to real projects, until they are assigned to their actual team. -* **Parse Roles.** When enabled, Private Mendix Platform reads group and role claims from the incoming token and maps them onto Platform Roles and groups automatically. When disabled, no such mapping occurs and every federated user lands on the defaults above, to be assigned afterwards manually, through SCIM, or through the platform API. +* **Parse Roles.** When enabled, Private Mendix Platform reads group and role claims from the incoming token and maps them onto platform roles and groups automatically. When disabled, no such mapping occurs and every federated user lands on the defaults above, to be assigned afterwards manually, through SCIM, or through the platform API. * **Automation Settings.** For users whose identity provider information is mapped onto their platform profile, group membership can be driven from the values of those profile attributes. When a user arrives with a value that already corresponds to a group, they are added to that group. When a user arrives with a value that does not, a group is created for it and the user is made a member. This is configured on the Group Management page and is separate from Parse Roles. See [Automating Group Assignment](/private-mendix-platform/access-administration/#automating-group-assignment). Users can also be provisioned before their first login, using SCIM, so that their accounts and group placement exist in advance. From e0a12dc27f86d15c6420b19fd0bb6f26864edc95 Mon Sep 17 00:00:00 2001 From: katarzyna_koltun Date: Mon, 26 Oct 2026 12:15:50 +0100 Subject: [PATCH 09/12] updates --- .../reference/admin/pmp-ref-admin-manage.md | 2 +- .../roles/pmp-access-model.md | 173 +++++++++++------- 2 files changed, 103 insertions(+), 72 deletions(-) diff --git a/content/en/docs/private-platform/reference/admin/pmp-ref-admin-manage.md b/content/en/docs/private-platform/reference/admin/pmp-ref-admin-manage.md index 6dc06702274..00343a8348a 100644 --- a/content/en/docs/private-platform/reference/admin/pmp-ref-admin-manage.md +++ b/content/en/docs/private-platform/reference/admin/pmp-ref-admin-manage.md @@ -295,7 +295,7 @@ As the administrator, you can perform the following actions: #### User Management -In the **User Management** tab, you can create and edit accounts for your local users and API users (that is, accounts that are used by an API service to access your Private Mendix Platform). By clicking **More Actions** ({{% icon name="three-dots-menu-horizontal" %}}) by an account, you can quickly perform a number of actions: +In the **User Management** tab, you can create and edit accounts for your users. By clicking **More Actions** ({{% icon name="three-dots-menu-horizontal" %}}) by an account, you can quickly perform a number of actions: * Edit a user's name and email * Assign or remove user roles (local users only) diff --git a/content/en/docs/private-platform/roles/pmp-access-model.md b/content/en/docs/private-platform/roles/pmp-access-model.md index 7e08ca9b2f1..1494acf919d 100644 --- a/content/en/docs/private-platform/roles/pmp-access-model.md +++ b/content/en/docs/private-platform/roles/pmp-access-model.md @@ -11,127 +11,158 @@ Access in Private Mendix Platform is governed by two role systems that operate i This page describes that model. It is the reference to consult before you design a group hierarchy or define a custom role, and the place to look when the access someone has does not match the access you expected them to have. For the procedures that configure the model, see [Administering Users, Groups, and Roles in Private Mendix Platform](/private-mendix-platform/access-administration/). -Administrators configure all of it at runtime, from the **Manage** section of admin mode. No part of the model requires a code change to the platform or to your apps. +Administrators configure all of it at runtime, from the **Manage** section of the [Admin menu](/private-mendix-platform/reference-guide/admin/). No part of the model requires a code change to the platform or to your apps. -## The Two Role Systems +## Resource and Platform Roles Private Mendix Platform separates platform-wide privilege from privilege over an individual resource. Role Management presents the two as separate tabs, and they share no permissions. -{{% alert color="info" %}} -**Reviewer note:** confirm the exact tab labels used in the Role Management page of the current release, so this page matches the UI wording. -{{% /alert %}} +### Resource Roles + +A Resource Role answers the question *what can this person do to this app, or this namespace?* It is held by an individual, and it applies only to the resources that the individual reaches it through: the resources owned by the group in which they hold the role, or the single app whose team they were invited to. + +Private Mendix Platform includes the following default resource roles: + +* **Owner** - Has full control of an app, including transferring ownership, inviting team members, and assigning their roles. + + This role is automatically granted to the user that created the app. It cannot be granted manually, except by transfering ownership of the app to a new owner. For more information, see [Assigning the App to a New Owner](/private-mendix-platform/reference-guide/admin/company/#ownership). + +* **Developer** - Has the complete development and operations set; can change the app's source and deploy it. +* **Contributor** - Development only; can change the app's source but cannot deploy it. +* **Operator** - Operations only; can deploy the app, but cannot change its source. +* **Maintainer** - Can manage logs, events, and metrics, as well as applications and apps. +* **Administrator** - Can oversee the deployment settings of the apps in scope. + + The Administrator resource role is not the same as a platform administrator.It does not grant access to admin mode and has no privilege over the platform. It reaches only the resources owned by the relevant group. The platform-wide equivalents are the **CompanyAdmin** and **SystemAdmin** platform roles. + +Permissions in a Resource Role have the following categories: + +* **Project** - The app lifecycle, its team, version control, and viewing its environments +* **Build** - Packaging, the build pipeline, and the software bill of materials. +* **Deployment** - Deploying and managing the app's environments; this is the largest category, and the only one that can be scoped per environment +* **Monitoring** - Logs and metrics + +Every permission in a resource role is expressed as an action on an app, which is why the schema reads as a set of app permissions even for roles concerned mainly with deployment settings. + +#### Per-Environment Scoping + +Deployment is the only permission category that can be limited by environment. Each permission in it can be restricted to any combination of Development, Test, Acceptance, and Production. No other category offers this. + +This is what makes it possible to express a role such as *may deploy freely to Development and Test, and may not deploy to Production at all* without creating separate roles per environment, and it is the mechanism to reach for when a compliance requirement separates production deployment from everyday development. ### Platform Roles -A platform role answers the question *what can this person do on the platform in general?* It is assigned to a user account when the account is created, and can be changed at any time afterwards. Platform roles are stackable: a user can hold several, and the effective set of permissions is simply everything those roles grant, added together. +A platform role answers the question *what can this person do on the platform in general?* It is assigned to a user account when the account is created, and can be changed at any time afterward. Platform roles are stackable. That is, a user can hold several, and the effective set of permissions is everything those roles grant, added together. -Private Mendix Platform includes the following default platform roles. +Private Mendix Platform includes the following default platform roles: -| Role | Grants | -| --- | --- | -| **User** | Baseline access to the platform web interface. Every human user needs this role at minimum. | -| **CompanyAdmin** | Everything under **Admin** > **Manage**: app management, user and group management, Marketplace content, deployment clusters, activity logs, and platform statistics. Intended for the people who own day-to-day platform operations. | -| **SystemAdmin** | Everything under **Admin** > **Settings**: identity provider and SSO configuration, version control and CI/CD integrations, licensing, branding, and platform capabilities. Intended for the people who own the infrastructure the platform depends on. | +* **User** - Baseline access to the platform web interface. Every human user needs this role at minimum. +* **CompanyAdmin** - Company admins have access to everything under the **Manage** section of the Admin menu, including the following capabilities: -{{% alert color="warning" %}} -**CompanyAdmin and SystemAdmin are parallel, not nested.** Neither contains the other. They address different audiences and grant access to different halves of admin mode. Granting CompanyAdmin does not give someone access to identity or licensing settings, and granting SystemAdmin does not give someone the ability to manage users and groups. A user who needs both must be given both. -{{% /alert %}} + * App management + * User and group management + * Marketplace content + * Deployment clusters + * Activity logs + * Platform statistics + + This role is intended for users who own day-to-day platform operations. -There is only one kind of account. Accounts used by services rather than people are not a separate account type: a service that calls the platform API authenticates as an ordinary account, and what it can do is determined by that account's platform role, exactly as it would be for a person. A role such as **API User**, holding only the permissions a particular integration needs, is an example of a platform role defined for that purpose. +* **SystemAdmin** - Company admins have access to everything under the **Settings** section of the Admin menu, including the following capabilities: + + * Identity provider and SSO configuration, version control and CI/CD integrations, licensing, branding, and platform capabilities. Intended for the people who own the infrastructure the platform depends on. {{% alert color="info" %}} -**Reviewer note:** confirm whether a role named API User ships with the platform or is customer-defined, so this paragraph can state it plainly. Note also that [Private Mendix Platform Functionalities - Company Administrators](/private-mendix-platform/reference-guide/admin/company/#user-management) currently describes "API users" as a distinct kind of account. That wording contradicts the model and should be corrected on that page as part of this change. +CompanyAdmin and SystemAdmin address different audiences and grant access to different capabilities of Admin mode. Granting CompanyAdmin does not give someone access to identity or licensing settings, and granting SystemAdmin does not give someone the ability to manage users and groups. A user who needs both must be given both. {{% /alert %}} -Permissions in a platform role fall into the following broad categories: +#### Platform Role Permissions -* Generic platform access, such as reaching the web interface and creating an app. -* Management capabilities on the **Manage** side, such as app management, user and group management, Marketplace administration, and activity logs. -* Management capabilities on the **Settings** side, such as identity and access configuration, licensing, cluster manager configuration, and webhooks. +Permissions in a platform role fall into the following broad categories. -{{% alert color="info" %}} -**Reviewer note:** the three categories above are representative rather than a literal reproduction of the permission schema. Supply the exact category names and the individual permission labels as they appear in the UI, and this list will be replaced with a complete table. -{{% /alert %}} +##### Generic Permissions -### Resource Roles +Generic permissions grant basic platform access: -A Resource Role answers the question *what can this person do to this app, or this namespace?* It is held by an individual, and it applies only to the resources that the individual reaches it through: the resources owned by the group in which they hold the role, or the single app whose team they were invited to. +* **Web** - Can reach the web interface. +* **App** - Can create an app. -Private Mendix Platform includes the following default Resource Roles. +##### Management Permissions -| Role | Covers | -| --- | --- | -| **Owner** | Full control of an app, including transferring ownership, inviting team members, and assigning their roles. | -| **Developer** | The complete development and operations set: change the app's source and deploy it. | -| **Contributor** | Development only. Can change the app's source, cannot deploy it. | -| **Operator** | Operations only. Can deploy the app, cannot change its source. | -| **Maintainer** | Oversight of the deployment settings of the apps in scope. | -| **Administrator** | Oversight of the deployment settings of the apps in scope. | +Management permissions involve the capabilities available in the **Manage** section of the Admin menu, such as app management, user and group management, Marketplace administration, and activity logs: -{{% alert color="info" %}} -**Reviewer note:** Maintainer and Administrator are both concerned with deployment settings, and the table above does not yet distinguish them. Supply the actual difference in their permission sets so each row says something a reader can act on, rather than describing the two identically. -{{% /alert %}} +* **Apps** - Includes the following permissions: + + * **Access App management pane** + * **Access software composition pane** + * **Access import apps pane** -{{% alert color="warning" %}} -**Owner is assigned automatically and cannot be granted manually.** It is held by whoever created the app. To move it, transfer ownership of the app rather than assigning the role. See [Assigning the App to a New Owner](/private-mendix-platform/reference-guide/admin/company/#ownership). -{{% /alert %}} +* **Marketplace** - Includes the following permissions: -{{% alert color="warning" %}} -**The Resource Role named Administrator is not a platform administrator.** It grants no access to admin mode and no privilege over the platform. It reaches only the resources owned by the group in which its holder holds it. The platform-wide equivalents are the **CompanyAdmin** and **SystemAdmin** platform roles. -{{% /alert %}} + * **Manage content in content management pane** + * **Approve content in content management pane** + * **Delete content in content management pane** + * **Access import content in content management pane** + * **Access taxonomy management pane** -Permissions in a Resource Role fall into four categories: +* **Deployment** - Includes the following permissions: -* **Project** - the app lifecycle, its team, version control, and viewing its environments. -* **Build** - packaging, the build pipeline, and the software bill of materials. -* **Deployment** - deploying and managing the app's environments. This is the largest category, and the only one that can be scoped per environment. -* **Monitoring** - logs and metrics. + * **Access cluster manager pane** + * **Access environment overview pane** -Every permission in a Resource Role is expressed as an action on an app, which is why the schema reads as a set of app permissions even for roles concerned mainly with deployment settings. +* **Users** - Includes the following permissions: -{{% alert color="info" %}} -**Reviewer note:** supply the individual permission labels within each of the four categories, and this section will be replaced with a full role-to-permission matrix. -{{% /alert %}} + * **Access role management pane** + * **Edit user management pane** + * **View user management pane** + * **Edit group management pane** + * **View group management pane** -#### Per-Environment Scoping +* **Platform** - Includes the following permissions: -Deployment is the only permission category that can be limited by environment. Each permission in it can be restricted to any combination of Development, Test, Acceptance, and Production. No other category offers this. + * **Access platform statistics pane** + * **Access activity logs pane** + * **Access webhooks pane** + * **Access licensing pane** + * **Access Maia pane** -This is what makes it possible to express a role such as *may deploy freely to Development and Test, and may not deploy to Production at all* without creating separate roles per environment, and it is the mechanism to reach for when a compliance requirement separates production deployment from everyday development. +##### Settings Permissions -### Editing Roles and Creating Custom Roles +Settings permissions involve the capabilities available in the **Settings** section of the Admin menu, such as identity and access configuration, licensing, cluster manager configuration, and webhooks: + +#### Managing API User Accounts -Both systems are fully editable by administrators: +There is only one kind of account. Accounts used by services rather than people are not a separate account type. A service that calls the platform API authenticates as an ordinary account, and what it can do is determined by that account's platform role, in the same way as for a person. A role such as **API User**, holding only the permissions a particular integration needs, is an example of a platform role defined for that purpose. + +### Editing Roles and Creating Custom Roles -* The permissions of a default role can be changed. -* A default role cannot be deleted. -* Entirely new roles can be created in either system, with any combination of permissions. +Administrators can edit both types of roles, change their permissions, and create new roles. Changing a role changes the effective access of everyone who holds it, so review who holds a role before editing it. -Changing a role changes the effective access of everyone who holds it, so review who holds a role before editing it. +Unlike custom roles, default roles cannot be deleted. ### Group Admin -Group Admin sits outside both role systems. It is not a platform role, not a Resource Role, and not governable: it does not appear anywhere among the roles you can view or edit, and its permissions cannot be changed or extended. +Group Admin exists outside both role systems. It is not a platform role, not a resource role, and not governable. That is, you cannot view or edit this role, and its permissions cannot be changed or extended. -It is assigned invisibly and automatically to the users named in the **Group Admins** field of a group, as a consequence of naming them there. You never assign it yourself and you will not see it listed against a user. +It is automatically assigned to users assigned in the **Group Admins** field of a group. It is not visible in the list of user roles. -Its only effect is to let those users manage that group's membership, meaning they can add and remove members. It grants nothing else, and it applies only to the groups for which its holder was designated. +This role lets group admins manage a group's membership, that is, add and remove members. It does not grant any other rights, and it applies only to the groups for which its holder was designated. -Consequently, delegating group membership management does not require giving anyone an administrator role. Naming a person as a group admin on their own group is sufficient. See [Working with Groups and App Teams in Private Mendix Platform](/private-mendix-platform/groups-and-app-teams/). +Consequently, delegating group membership management does not require giving anyone an administrator role. Naming a person as a group admin on their own group is sufficient. For more information, see [Working with Groups and App Teams in Private Mendix Platform](/private-mendix-platform/groups-and-app-teams/). ## Groups -Groups are how users are organized and how Resource Roles are delivered at scale. They typically mirror your organization: a division, a department, a portfolio, a team. +Groups organize users and deliver resource roles at scale. They typically mirror your organization and can represent, for example, a division, a department, a portfolio, or a team. ### Structure Groups form a hierarchical tree. Private Mendix Platform creates the root group automatically, and it is the foundation of everything beneath it. You can edit the root group's details to match your organization. -Every group other than the root requires three things: +Every group other than the root must have the following properties: -* **Parent Group** - the group's place in the hierarchy. There is no such thing as a group outside the tree. -* **Group Admins** - one or more users who will manage the group's membership. -* **Description** - a clear statement of the group's purpose. +* **Parent Group** - The group's place in the hierarchy. There is no such thing as a group outside the tree. +* **Group Admins** - One or more users who manage the group's membership. +* **Description** - A clear statement of the group's purpose. The depth of the hierarchy is not limited. From f5152bee11e0f8408f7e5c2914e4b23611a79242 Mon Sep 17 00:00:00 2001 From: katarzyna_koltun Date: Tue, 27 Oct 2026 11:50:54 +0100 Subject: [PATCH 10/12] draft --- .../roles/pmp-access-model.md | 24 +++++++++++++++++-- 1 file changed, 22 insertions(+), 2 deletions(-) diff --git a/content/en/docs/private-platform/roles/pmp-access-model.md b/content/en/docs/private-platform/roles/pmp-access-model.md index 1494acf919d..21f38db08e0 100644 --- a/content/en/docs/private-platform/roles/pmp-access-model.md +++ b/content/en/docs/private-platform/roles/pmp-access-model.md @@ -130,9 +130,29 @@ Management permissions involve the capabilities available in the **Manage** sect Settings permissions involve the capabilities available in the **Settings** section of the Admin menu, such as identity and access configuration, licensing, cluster manager configuration, and webhooks: +* **Preferences** - Includes the following permissions: + + * **Access notification setting pane** + * **Access general setting pane** + * **Access marketplace setting pane** + * **Access version support setting pane** + +* **Integrations** - Includes the following permissions: + + * **Access identity & access setting pane** + * **Access project management setting pane** + * **Access version control setting pane** + * **Access build setting pane** + * **Access deployment setting pane** + +* **Advanced** - Includes the following permissions: + + * **Access capability setting pane** + * **Access operational setting pane** + #### Managing API User Accounts -There is only one kind of account. Accounts used by services rather than people are not a separate account type. A service that calls the platform API authenticates as an ordinary account, and what it can do is determined by that account's platform role, in the same way as for a person. A role such as **API User**, holding only the permissions a particular integration needs, is an example of a platform role defined for that purpose. +There is only one type of account. Accounts used by services rather than people are not a separate account type. A service that calls the platform API authenticates as an ordinary account, and what it can do is determined by that account's platform role, in the same way as for a person. A role such as **API User**, holding only the permissions a particular integration needs, is an example of a platform role defined for that purpose. ### Editing Roles and Creating Custom Roles @@ -142,7 +162,7 @@ Unlike custom roles, default roles cannot be deleted. ### Group Admin -Group Admin exists outside both role systems. It is not a platform role, not a resource role, and not governable. That is, you cannot view or edit this role, and its permissions cannot be changed or extended. +The Group Admin role exists outside both role systems. That is, it is not a platform or resource role. You cannot view or edit this role, and its permissions cannot be changed or extended. It is automatically assigned to users assigned in the **Group Admins** field of a group. It is not visible in the list of user roles. From 7949c0cc3302aa49478e9123658e7c41904b4ee3 Mon Sep 17 00:00:00 2001 From: katarzyna_koltun Date: Wed, 28 Oct 2026 18:11:56 +0100 Subject: [PATCH 11/12] updates --- .../roles/pmp-access-model.md | 107 +++++++----------- 1 file changed, 44 insertions(+), 63 deletions(-) diff --git a/content/en/docs/private-platform/roles/pmp-access-model.md b/content/en/docs/private-platform/roles/pmp-access-model.md index 21f38db08e0..b554d29601d 100644 --- a/content/en/docs/private-platform/roles/pmp-access-model.md +++ b/content/en/docs/private-platform/roles/pmp-access-model.md @@ -19,7 +19,7 @@ Private Mendix Platform separates platform-wide privilege from privilege over an ### Resource Roles -A Resource Role answers the question *what can this person do to this app, or this namespace?* It is held by an individual, and it applies only to the resources that the individual reaches it through: the resources owned by the group in which they hold the role, or the single app whose team they were invited to. +A Resource role answers the question *what can this person do to this app, or this namespace?* Their scope involves only the resources the relevant group owns or is associated with. Multiple resource roles are only combined where two roles apply to the same resource. Private Mendix Platform includes the following default resource roles: @@ -52,7 +52,7 @@ This is what makes it possible to express a role such as *may deploy freely to D ### Platform Roles -A platform role answers the question *what can this person do on the platform in general?* It is assigned to a user account when the account is created, and can be changed at any time afterward. Platform roles are stackable. That is, a user can hold several, and the effective set of permissions is everything those roles grant, added together. +A platform role answers the question *what can this person do on the platform in general?* It is assigned to a user account when the account is created, and can be changed at any time afterward. Platform roles are stackable. That is, if a user has more than one platform role, they get all the access rights of every role they hold. Private Mendix Platform includes the following default platform roles: @@ -186,111 +186,92 @@ Every group other than the root must have the following properties: The depth of the hierarchy is not limited. -### A Group Does Not Hold a Role +### Groups vs Roles -This is the point at which the model is most often misread. A group is not granted a role, and a group has no permissions of its own. A group holds *members*, and each member individually holds a Resource Role. The group's function is to own resources, so that the roles its members hold have something to apply to. +A group is not granted a role, and a group has no permissions of its own. A group holds *members*, and each member individually holds a resource role. The group owns resources, to which its members' roles apply. -Two members of the same group can legitimately hold different Resource Roles, and often should. A team group might contain several Developers, a few Contributors, and one Operator, all with access to the same app, doing different things to it. +Two members of the same group can have different resource roles. For example, a team group can contain several Developers, a few Contributors, and one Operator. All of these roles have access to the same app, but can do different things in the app. -It follows that a statement such as *this group grants Administrator, so its members are administrators* has the relationship backwards. Members hold roles; the group supplies the scope. +When a member's role in a group changes, the change is applied at once to every resource that group owns or is associated with. -### Membership Inherits Downward +### Membership Inheritance -Members of a group automatically become members of every group beneath it in the hierarchy, carrying forward the same Resource Role they hold in the higher group. These are shown as inherited members, as distinct from members added directly. +Members of a group automatically become members of every group beneath it in the hierarchy, carrying forward the same resource role they hold in the higher group. Granting a broad resource role at or near the root group extends that role across the entire platform. See [Designing Your Access Model](#designing-your-access-model). These are shown as inherited members, as distinct from members added directly. -Inheritance goes to any depth. A member two levels up appears in a grandchild group with the same role they hold two levels up. It does not travel upward: membership of a child group confers nothing in the parent. +Membership of a child group does not give any roles in the groups higher in the hierarchy. -{{% alert color="warning" %}} -Because membership cascades downward without limit, a role granted high in the hierarchy reaches every group below it. Granting a broad Resource Role at or near the root group extends that role across the entire platform. See [Designing Your Access Model](#designing-your-access-model). -{{% /alert %}} - -## Resources Owned by Groups +### Resource Ownership for Groups -A group can own or be associated with three kinds of resource. The ownership rules differ for each, and so does the behavior of that ownership with respect to the hierarchy. +A group can own or be associated with the following kinds of resource, with different ownership rules and behavior depending on the resource type: -| Resource | Ownership model | -| --- | --- | -| **App Projects** | Exclusive. An app is owned by exactly one group, so accountability is unambiguous. | -| **Deployment Namespaces** | Shareable. A namespace can be associated with several groups at once, allowing operational responsibility to be shared between teams. | -| **Marketplace Components** | Owned by the individual user who published the component. | +* **App Projects** - Exclusive. An app is owned by exactly one group, so accountability is unambiguous. +* **Deployment Namespaces** - Shareable. A namespace can be associated with several groups at once, allowing operational responsibility to be shared between teams. +* **Marketplace Components** - Owned by the individual user who published the component. -### App Projects +#### App Projects An app is owned by one group and one user within it. Members of the owning group reach the app through the Resource Role they hold in that group, whether they hold it directly or by inheritance from a group further up. -{{% alert color="warning" %}} -**Apps created through Mendix Studio Pro are owned by the Mendix root group.** Ownership is assigned to the root group on creation rather than to the group the creating developer belongs to. An app left in this state is reachable by everyone holding a Resource Role in the root group, and by nobody further down the hierarchy, since membership inherits downward and resource access does not travel upward. Neither is usually what was intended. +{{% alert color="info" %}} +Apps created through Mendix Studio Pro are owned by the Mendix root group. Ownership is assigned to the root group on creation rather than to the group the creating developer belongs to. An app left in this state is reachable by everyone holding a resource role in the root group, and by nobody further down the hierarchy. -Transfer ownership to the group that should hold it as a routine step after creating an app from Studio Pro. See [Assigning the App to a New Owner](/private-mendix-platform/reference-guide/admin/company/#ownership). +Because of that, you should transfer ownership to the group that should hold it as a routine step after creating an app from Studio Pro. See [Assigning the App to a New Owner](/private-mendix-platform/reference-guide/admin/company/#ownership). {{% /alert %}} -### Deployment Namespaces +#### Deployment Namespaces -Two concepts are involved here and both are meaningful. A **deployment namespace** is the resource. A **namespace purpose** is a scoping tied to that resource, describing what the namespace is for. +A deployment namespace is a resource associated with a group. The *namespace purpose* is a scoping tied to that resource, describing what the namespace is for. -They form a chain: a namespace is associated with a group, and the namespace's purpose is tied to the namespace in turn. So the group is associated with the namespace, and the purpose comes with it as a property of the namespace rather than as something set on the association. Purpose is therefore configured once, on the namespace, and holds for every group associated with it. For how purpose relates to environments, see [Deployment Purpose and DTAP Mode](/private-mendix-platform/user-guide/#deployment-purpose-and-dtap-mode). +Because purpose is configured on the namespace level, it applies to every group associated with the namespace. For how purpose relates to environments, see [Deployment Purpose and DTAP Mode](/private-mendix-platform/user-guide/#deployment-purpose-and-dtap-mode). -{{% alert color="warning" %}} -**A namespace association does not inherit, in either direction.** Group membership and the Resource Roles that come with it cascade down the hierarchy. A deployment namespace association does not: it extends neither to a group's parents nor to its children. +Unlike group membership, a namespace association is not inherited by grops lower in the hierarchy. For a group to deploy to a namespace, the group must be directly associated with the namespace. Because of that, an app project and the namespace to which it deploys should be associated at the same level of the hierarchy. -For a group to deploy to a namespace, **that group must itself be directly associated with the namespace**, regardless of where either sits in the tree. In practice this means keeping an app project and the namespace it deploys to associated at the same level of the hierarchy. +This rule is specific to deployment namespaces. App projects are already exclusive to a single group, and Marketplace components follow their own ownership model. -This rule is specific to deployment namespaces. App projects are already exclusive to a single group, and Marketplace components follow their own ownership model, so neither is affected by it. -{{% /alert %}} +#### Marketplace Components -### Marketplace Components +Marketplace component ownership does not follow the group hierarchy. A component published to the private Marketplace is owned by the user who published it, rather than by a group. -A component published to the private Marketplace is owned by the user who published it, rather than by a group. Ownership therefore does not follow the group hierarchy. +Access to the Marketplace administration area, where content is approved, categorized, and imported, is a platform role permission and not a resource role. Administering Marketplace content does not require any resource roles. -Access to the Marketplace administration area, where content is approved, categorized, and imported, is a platform role permission and not a Resource Role. A user who administers Marketplace content does not need any Resource Role to do so. +Marketplace content can additionally be shared with groups by its publisher. For more information, see [Sharing Content with Groups](/private-mendix-platform/user-guide/#sharing-content-with-groups). -Marketplace content can additionally be shared with groups by its publisher. See [Sharing Content with Groups](/private-mendix-platform/user-guide/#sharing-content-with-groups). +## Granting Users Access to an App -## How a User Gets Access to an App +Users can get access to an app in the following ways. -There are three distinct paths, and it is worth keeping them separate when diagnosing why someone can or cannot reach an app. +### Owning Group -1. **Through the owning group.** The user is a member, directly or by inheritance, of the group that owns the app, and holds a Resource Role there. This is the primary path and the one that scales. -2. **Through a direct invitation to the app team.** The app's owner invites an individual onto the team and assigns them a role such as Developer, Contributor, or Operator. This bypasses groups entirely and applies to that one app. Before a user can be invited, their account must exist. See [Editing App Details](/private-mendix-platform/reference-guide/admin/company/#app-details). -3. **Through app sharing, followed by a request.** An app can be shared with groups that do not own it. Sharing makes the app *visible* to those groups; it grants no access. Members who can see a shared app can request access from the app's owner, who decides whether to grant it and with which role. See [Sharing the App with Selected User Groups](/private-mendix-platform/reference-guide/admin/company/#share). +The user is a member, directly or by inheritance, of the group that owns the app, and holds a Resource Role there. This is the primary path and the one that scales. -{{% alert color="info" %}} -**Reviewer note:** confirm the mechanics of the request flow in path 3 - how the request reaches the owner, whether it is notified, and whether granting it creates a direct team membership. -{{% /alert %}} +### Invitation to App Team -## How Permissions Combine +The app's owner invites an individual onto the team and assigns them a role such as Developer, Contributor, or Operator. This bypasses groups entirely and applies only to the specific app. Before a user can be invited, their account must exist. For more information, see [Editing App Details](/private-mendix-platform/reference-guide/admin/company/#app-details). -The two role systems combine differently, and conflating them is the source of most incorrect expectations about effective access. -### Platform Roles Combine as a Union +### App Sharing -Platform roles are not scoped to a resource, so there is nothing to reconcile. A user's effective platform permissions are every permission granted by every platform role they hold, added together. +An app can be shared with groups that do not own it. Sharing makes the app visible to those groups but grants no access. Members can then request access from the app's owner, who decides whether to grant it and with which role. For more infomration, see [Sharing the App with Selected User Groups](/private-mendix-platform/reference-guide/admin/company/#share). -### Resource Roles Combine Only on a Shared Resource +## Managing Federated Users {#federated-users} -Resource Roles do not blanket-combine across every group a user belongs to. Two groups that are not in a parent-and-child relationship share no resources, so a user's roles in them never interact: the role held in one group applies to that group's resources and nowhere else. +When users sign in through your identity provider rather than with a local account, they still need a place in the group hierarchy and a resource role in order to do anything. The following settings determine what happens on first arrival. -Combination happens only when two roles land on the *same* resource. The common case is a user who has been invited directly onto an app's team in one role, and who also inherits a different role on that same app through the group hierarchy. There, and only there, the two are reconciled into a single effective set of permissions on that app. +### Default Group and Role -### Changes Take Effect Immediately +Every incoming user with no other placement is put into a configured group with a configured role. Pointing these at a deliberately low-privilege landing group gives new arrivals somewhere to be that has no access to real projects, until they are assigned to their actual team. -When a member's role in a group changes, the change is applied at once to every resource that group owns or is associated with. There is no separate synchronization step to run, and no need to reapply access to individual apps or namespaces after a role change. +### Role Parsing -## Federated Users {#federated-users} +When enabled, Private Mendix Platform reads group and role claims from the incoming token and maps them onto platform roles and groups automatically. When disabled, no such mapping occurs and every federated user lands on the defaults above, to be assigned afterwards manually, through SCIM, or through the platform API. -When users sign in through your identity provider rather than with a local account, they still need a place in the group hierarchy and a Resource Role in order to do anything. Three settings determine what happens on first arrival. +### Automation Settings -* **Default Group and Default Role.** Every incoming user with no other placement is put into a configured group with a configured role. Pointing these at a deliberately low-privilege landing group gives new arrivals somewhere to be that has no access to real projects, until they are assigned to their actual team. -* **Parse Roles.** When enabled, Private Mendix Platform reads group and role claims from the incoming token and maps them onto platform roles and groups automatically. When disabled, no such mapping occurs and every federated user lands on the defaults above, to be assigned afterwards manually, through SCIM, or through the platform API. -* **Automation Settings.** For users whose identity provider information is mapped onto their platform profile, group membership can be driven from the values of those profile attributes. When a user arrives with a value that already corresponds to a group, they are added to that group. When a user arrives with a value that does not, a group is created for it and the user is made a member. This is configured on the Group Management page and is separate from Parse Roles. See [Automating Group Assignment](/private-mendix-platform/access-administration/#automating-group-assignment). +For users whose identity provider information is mapped onto their platform profile, group membership can be derived from the values of those profile attributes. When a user arrives with a value that already corresponds to a group, they are added to that group. When a user arrives with a value that does not, a group is created for it and the user is made a member. This is configured on the Group Management page and is separate from Parse Roles. See [Automating Group Assignment](/private-mendix-platform/access-administration/#automating-group-assignment). Users can also be provisioned before their first login, using SCIM, so that their accounts and group placement exist in advance. -Configuring the identity provider connection itself, including OIDC and SAML setup, attribute mapping, and SCIM tokens, is documented in [Private Mendix Platform Functionalities - System Administrators](/private-mendix-platform/reference-guide/admin/system/#identity--access). - -{{% alert color="info" %}} -**Reviewer note:** supply the exact field labels and locations for Default Group, Default Role, and Parse Roles so this section can point readers at the right screen. -{{% /alert %}} +For information about configuring the identity provider connection, including OIDC and SAML setup, attribute mapping, and SCIM tokens, see [Private Mendix Platform Functionalities - System Administrators](/private-mendix-platform/reference-guide/admin/system/#identity--access). ## Designing Your Access Model {#designing-your-access-model} From 2aa8e8ed0ec01e4d1a83a8543ec6d07f63e493a2 Mon Sep 17 00:00:00 2001 From: katarzyna_koltun Date: Wed, 28 Oct 2026 19:04:06 +0100 Subject: [PATCH 12/12] updates --- .../roles/pmp-access-model.md | 38 +++++++++++-------- 1 file changed, 22 insertions(+), 16 deletions(-) diff --git a/content/en/docs/private-platform/roles/pmp-access-model.md b/content/en/docs/private-platform/roles/pmp-access-model.md index b554d29601d..eb4489b7ac9 100644 --- a/content/en/docs/private-platform/roles/pmp-access-model.md +++ b/content/en/docs/private-platform/roles/pmp-access-model.md @@ -273,21 +273,31 @@ Users can also be provisioned before their first login, using SCIM, so that thei For information about configuring the identity provider connection, including OIDC and SAML setup, attribute mapping, and SCIM tokens, see [Private Mendix Platform Functionalities - System Administrators](/private-mendix-platform/reference-guide/admin/system/#identity--access). -## Designing Your Access Model {#designing-your-access-model} +## Best Practices for Designing Your Access Model {#designing-your-access-model} -The rules above have direct consequences for how a hierarchy should be laid out. +When designing your access hierarchy, keep in mind the following recommendations. -**Keep broad roles rare and high, and let narrow roles do the work low down.** Because membership cascades downward, a Resource Role granted near the root reaches everything beneath it. Roles such as Administrator and Maintainer should be granted sparingly, and as close as possible to the groups that actually need them. Developer, Contributor, and Operator are the roles intended to carry everyday work further down the tree. +* Keep broad roles rare and high-level. -**Associate an app and the namespace it deploys to at the same level.** Since namespace associations do not inherit, a group that owns an app but is not itself associated with a namespace cannot deploy that app, no matter what its parent is associated with. Placing both at the same level avoids the problem entirely. + Because membership cascades downward, a resource role granted near the root reaches everything beneath it. Roles such as Administrator and Maintainer should be granted sparingly, and as close as possible to the groups that actually need them. Developer, Contributor, and Operator are the roles intended to carry everyday work further down the tree. -**Give federated arrivals a landing group.** A low-privilege group configured as the Default Group means an unrecognized user who signs in successfully still reaches nothing of consequence until an administrator places them. +* Associate an app and the namespace it deploys to at the same level. -**Use per-environment scoping instead of parallel roles.** Where the requirement is that a team may deploy to some environments and not others, scope the Deployment permissions of one role rather than maintaining two similar roles. + Since namespace associations are not inherited, a group that owns an app but is not associated with the namespace cannot deploy that app. Place both at the same level to avoid this issue. -**Mirror your organization, but only as deeply as you need.** Depth is unlimited, and each additional level adds inherited membership to reason about. Add a level when it corresponds to a real boundary of accountability. +* Give federated users a landing group. -### Worked Example + A low-privilege group configured as the Default Group means an unrecognized user who signs in successfully has limited access rights until an administrator places them in the appropriate group. + +* Use per-environment scoping instead of parallel roles. + + If a team should be allowed to deploy to some environments and not others, scope the Deployment permissions of one role rather than maintaining two similar roles. + +* Only create as many hierarchy levels as you need. + + Each hierarchy level potentially increases complexity by adding more inherited membership levels to consider. + +### Example Hierarchy Consider the following hierarchy. @@ -299,14 +309,10 @@ Mendix (root) └── Preboarding ``` -A user who is a member of **App Portfolios** with the Developer role is also, by inheritance, a Developer in **App Portfolio 1**, and can develop and deploy the apps that group owns. That same user is not a member of **Preboarding**, which is not beneath their group, and has no access to anything Preboarding owns. - -A user who is a member of **Platform Admin** with the Administrator role holds it in **App Portfolios** and **App Portfolio 1** as well, because both are beneath Platform Admin. Adding a new portfolio group under App Portfolios extends that user's Administrator role into it automatically. This is the reason to grant Administrator low rather than high. +A user who is a member of *App Portfolios* with the Developer role is also, by inheritance, a Developer in *App Portfolio 1*, and can develop and deploy the apps that group owns. That same user is not a member of *Preboarding*, which is not beneath their group, and has no access to anything Preboarding owns. -If **App Portfolio 1** owns an app that must deploy to a namespace, App Portfolio 1 must be associated with that namespace itself. Associating the namespace with **App Portfolios**, or with **Mendix**, does not enable the deployment. +A user who is a member of *Platform Admin* with the Administrator role holds it in *App Portfolios* and *App Portfolio 1* as well, because both are beneath Platform Admin. Adding a new portfolio group under App Portfolios extends that user's Administrator role into it automatically. This is the reason to grant Administrator low rather than high. -**Preboarding** is a natural candidate for the Default Group in an SSO configuration: users who arrive without a recognized placement land there, hold whatever low-privilege Default Role is configured, and reach nothing owned elsewhere in the tree. +If *App Portfolio 1* owns an app that must deploy to a namespace, App Portfolio 1 must be associated with that namespace itself. Associating the namespace with *App Portfolios*, or with *Mendix*, does not enable the deployment. -{{% alert color="info" %}} -**Reviewer note:** a diagram of this hierarchy showing groups, members, roles, owned apps, and namespace associations exists in the supporting document set and should be attached here in place of the code block above. -{{% /alert %}} +*Preboarding* is a good choice for the Default Group in an SSO configuration. Users who arrive without a recognized placement land there, hold whatever low-privilege Default Role is configured, and cannot reach anything owned elsewhere in the tree. \ No newline at end of file