Manage Security

Security Management Skill

This skill covers Mendix security configuration via MDL: module roles, user roles, access control (microflows, pages, entities), project security settings, and demo users.

When to Use This Skill

Use when the user asks to:

• Set up security for a module or project
• Create or manage module roles / user roles
• Grant or revoke access to microflows, pages, or entities
• Configure project security level or demo users
• Review existing security configuration

Security Concepts

• Module Roles define permissions within a single module (e.g., Shop.Admin, Shop.Viewer)
• User Roles aggregate module roles from multiple modules (e.g., Administrator includes Shop.Admin + System.Administrator)
• Access Rules control CRUD rights on entities per module role
• Microflow/Page Access controls which module roles can execute/view specific elements
• Project Security Level determines enforcement: off, prototype, or production

The System-module ceiling — decide the role model around this FIRST

No project module can widen access to System.User, System.Workflow or System.WorkflowUserTask. Access to System entities comes from the System module's own roles, and a grant in your module cannot raise it. This is a design constraint, not a detail: it decides what your screens can be, and finding it late means rebuilding them (ako/mxcli-maintenance-2 designed a technician picker, built it, tested it, and tore it out).

Every consequence is silent — the page renders, the data is simply missing, and mx check, mxcli lint and mxcli report all pass:

The rule: a microflow data source moves the ROWS, not the MEMBERS

Learn this as a rule rather than as a symptom, because the obvious workaround only looks like it worked, and the same trap is waiting on the next screen.

A microflow does not apply entity access, so its retrieve returns every row. But the runtime re-applies entity access when it serializes those objects to the client, XPath constraint included — so a row the role may not read arrives with every member empty. The list comes out the right length and the cards come out blank.

Measured in a browser on Mendix 11.14.0 — one page, two microflow-sourced lists over the same System.User retrieve, opened by two users:

Both lists hold two rows for both users, so the microflow really did carry the rows past entity access. Only A loses the values, and it loses them per object: System.User's own rule grants read where [id = '[%CurrentUser%]'], which is why a user picker shows you yourself and nobody else rather than showing nothing.

System.WorkflowUserTask has no such escape hatch for an ordinary role, so a workflow inbox built this way comes out entirely blank — the reported case (ako/mxcli#587): the inbox drew the right number of cards, every one of them empty, with mxcli check, lint, report and docker check all at 0 errors.

What to do instead

1. Record, don't pick. Have the workflow stamp itself against a row your own module owns — an ON CREATED MICROFLOW writing an association plus a plain status string — and list those objects. Target a task at a role, let whoever opens it do the work, and record who acted when they act.
2. Read it inside a microflow, return your OWN object. Entity access does not apply to the retrieve or to the member read, only to what crosses to the client — so copy the values you need onto an entity your module owns (persistent or non-persistent) and bind the page to that. This is list B above, and it is the same shape the reporter arrived at independently for user pickers: Engineer is a module-owned entity rather than System.User.
3. Split the page by role. Keep raw System grids on an Administrator-only page. Mendix hides a button to a page the user may not view, so the link simply does not appear.

Related: grant … on System.User is refused by exec — the System module's domain model is not stored in the project, so it has no access rules to add to. The refusal is at execution, not at mxcli check, so a script carrying one passes check and then stops part-way through.

Syntax Reference

Show Commands (Read-Only)

-- Project-wide security overview
describe app security;

-- Module roles (all or filtered)
list module roles;
list module roles in MyModule;

-- User roles and demo users
list user roles;
list demo users;

-- Access on specific elements
list access on microflow MyModule.ProcessOrder;
list access on page MyModule.CustomerOverview;
list access on entity MyModule.Customer;
list access on MyModule.Customer;        -- a bare name means the entity

-- Full security matrix
describe security matrix;
describe security matrix in MyModule;

Describe Commands

-- Describe individual roles and users (MDL output)
describe module role MyModule.Admin;
describe user role Administrator;
describe demo user 'demo_admin';

describe demo user never prints the password. It emits create or modify demo user 'demo_admin' password '***' …, where '***' means keep the stored password: replaying the output on the same project leaves the password as it is, and on a project without that user the statement is refused until you replace '***' with a real password.

Catalog Queries (SQL)

Security data is available in catalog tables for advanced querying. Use refresh catalog full to populate permissions and role mappings.

-- All permissions (entity, microflow, page, OData access)
select * from CATALOG.PERMISSIONS where ModuleRoleName = 'MyModule.Admin';

-- Filter by type
select ElementName, AccessType from CATALOG.PERMISSIONS
  where ElementType = 'ENTITY' and ModuleName = 'MyModule';

select ElementName from CATALOG.PERMISSIONS
  where ElementType = 'MICROFLOW' and AccessType = 'EXECUTE';

-- User role to module role mappings
select * from CATALOG.ROLE_MAPPINGS;
select ModuleRoleName from CATALOG.ROLE_MAPPINGS where UserRoleName = 'Administrator';

-- Which user roles have access to a module?
select distinct UserRoleName from CATALOG.ROLE_MAPPINGS where ModuleName = 'MyModule';

-- Describe catalog table schema
describe CATALOG.PERMISSIONS;
describe CATALOG.ROLE_MAPPINGS;

Catalog tables:

Module Roles

mdl 1;
-- Create module roles
create module role MyModule.Admin description 'Full administrative access';
create module role MyModule.User;
create module role MyModule.Viewer description 'Read-only access';

-- `or modify` updates an existing role's description instead of failing, so the
-- whole security script stays re-runnable rather than needing a run-once file.
create or modify module role MyModule.ApiUser description 'API consumer';

-- Remove a module role (`if exists` makes it a no-op when the role is gone)
drop module role MyModule.Viewer;
drop module role if exists MyModule.Legacy;

Microflow Access

mdl 1;
-- Grant execute access (multiple roles supported)
grant execute on microflow MyModule.ACT_Customer_Create to MyModule.User, MyModule.Admin;

-- Revoke from specific roles
revoke execute on microflow MyModule.ACT_Customer_Create from MyModule.User;

Nanoflow Access

mdl 1;
-- Grant execute access (same syntax as microflows)
grant execute on nanoflow MyModule.NF_ValidateCart to MyModule.User, MyModule.Admin;

-- Revoke from specific roles
revoke execute on nanoflow MyModule.NF_ValidateCart from MyModule.User;

-- Show current access
list access on nanoflow MyModule.NF_ValidateCart;

Note: Security roles persist through DROP+CREATE of the same nanoflow name within a session (by design, for refactor-in-place workflows).

Page Access

mdl 1;
-- Grant view access
grant view on page MyModule.Customer_Overview to MyModule.User, MyModule.Admin;

-- Revoke from specific roles
revoke view on page MyModule.Customer_Overview from MyModule.User;

What a New Document Starts With — and Why GRANT Does Not Narrow It

Document grants (page, microflow, nanoflow) are additive, like entity grants: GRANT adds roles, REVOKE removes them, nothing replaces the list. What a newly created document starts with depends on its module:

Consequences:

• A stub page created early (module still role-less) is open to <Module>.User. A later grant view on page M.Stub to M.Admin; adds Admin; every user role mapped to M.User can still open it. Narrow it explicitly: revoke view on page M.Stub from M.User;
• Drop + create in separate runs loses access. create or modify, and drop
  • create of the same name within one run, keep the stored roles. A create in a later run than the drop is a new document; in a module with its own roles it has none, and if a page, snippet, nanoflow or navigation item uses the flow MxBuild fails with CE0106 at security level Prototype/Production. mxcli check -p reports it as MDL-SEC21 before exec. Prefer create or modify to rebuild a flow; otherwise grant in the same script.

Always Qualify a Module Role

A module role is always Module.Role. The grammar makes the module part optional, so a bare Admin parses — and then either fails at exec (after every earlier statement has already been written) or, in create user role, is stored as .Admin and refused by MxBuild with CE1613. mxcli check reports it as MDL-GRANT02 without needing a project.

grant read * on entity MyModule.Customer to Admin;            -- ✗ MDL-GRANT02

mdl 1;
grant read * on entity MyModule.Customer to MyModule.Admin;   -- ✓

Entity Access (CRUD)

GRANT is additive — it merges with existing access, never removes permissions. Rights rank None < ReadOnly < ReadWrite and a merge takes the higher, so use revoke to take access away; a narrower grant will not do it.

A rule is identified by its role set and its where constraint. Two grants with the same constraint update one rule; with different constraints they make two, which Mendix combines at runtime (a role's access is the union of every rule naming it). So adding a where to an existing grant creates a second rule — it does not narrow the first.

mdl 1;
-- Full access (all CRUD + all members)
grant create, delete, read *, write * on entity MyModule.Customer to MyModule.Admin;

-- Read-only (all members)
grant read * on entity MyModule.Customer to MyModule.Viewer;

-- Selective member access
grant read (Name, Email), write (Email) on entity MyModule.Customer to MyModule.User;

-- Additive: adds Phone to existing read access (Name, Email preserved)
grant read (Phone) on entity MyModule.Customer to MyModule.User;

-- With XPath constraint: in [ ] like every XPath, quotes written once.
-- The old `grant MyModule.User on MyModule.Order (…) where '[…]'` still parses
-- but warns MDL-DEPR030; `mxcli fmt --upgrade` rewrites it.
grant read *, write * on entity MyModule.Order to MyModule.User where [Status = 'Open'];

-- Revoke entity access entirely
revoke all on entity MyModule.Customer from MyModule.Viewer;

-- Partial revoke: remove read on specific attribute
revoke read (Phone) on entity MyModule.Customer from MyModule.User;

-- Partial revoke: downgrade write to read-only
revoke write (Email) on entity MyModule.Customer from MyModule.User;

-- Partial revoke: remove structural permission
revoke delete on entity MyModule.Customer from MyModule.User;

Members added later

A rule also carries a default for members added after it was written, and MDL derives it from the grant: write * → ReadWrite, read * → ReadOnly, and a grant written purely as member lists leaves it at None.

So alter entity … add attribute gives the new attribute None on a member-listed rule. Nothing is broken — every rule gets an entry, the build is clean — but the attribute renders blank for that role. alter entity warns and prints the grant that widens it.

What decides this is the rule's default, not how narrow its member list is: read *, write (Email) is narrower than read *, write * and still picks up new members, because read * set its default to ReadOnly. Give a rule read * and narrow with revoke when the role should follow the entity as it grows.

Inherited members

Mendix inheritance is multi-table: a child adds attributes to its parent's, and all the parent's members belong to the child. Grant them exactly like the entity's own — read * / write * cover them too:

mdl 1;
create persistent entity Docs.DocumentBase (
  DocName: String(200),
  Confidential: Boolean
);

create persistent entity Docs.Contract extends Docs.DocumentBase (
  ContractNumber: String(50)
);

-- DocName is inherited, ContractNumber is Contract's own — name both the same way
grant read (DocName, ContractNumber) on entity Docs.Contract to Docs.Viewer;

-- Attachment inherits the file members from System.FileDocument
create persistent entity Docs.Attachment extends System.FileDocument (
  Category: String(50)
);
grant read (Category, "Name", Size) on entity Docs.Attachment to Docs.Viewer;

An access rule must carry an entry for every member, own and inherited — mxcli writes the ones you did not grant with rights None. Omitting them is Mendix CE0066 "Entity access is out of date", which masks the CE2729 "No read access to attribute" errors underneath until Studio Pro's Update security is clicked.