9.1 Permission Sets & Permission Set Extensions

9.1 Permission Sets & Permission Set Extensions

In Microsoft Dynamics 365 Business Central, security and object authorization are managed through a declarative, role-based access control (RBAC) architecture. Prior to Business Central 2021 Release Wave 1 (runtime 7.0), permissions were primarily stored in database tables or managed through disparate XML files. Modern Business Central development replaces XML files with first-class AL objects: permissionset and permissionsetextension.

For developers preparing for the MB-820 certification exam, mastering AL permission set object anatomy, understanding the critical runtime difference between direct and indirect permissions, and effectively diagnosing authorization failures using built-in platform tooling are essential competencies in Domain 3.

1. AL Permission Set Object (permissionset) Anatomy

An AL permissionset object defines a cohesive collection of permissions granted to database tables, table data, pages, codeunits, reports, XMLports, and queries. Storing permissions as AL objects ensures that security definitions are compile-time validated, version-controlled in source repositories, and packaged seamlessly within extension .app binaries.

permissionset 50100 "Loyalty Admin"
{
    Assignable = true;
    Caption = 'Loyalty Management Administrator';
    IncludedPermissionSets = "D365 BASIC", "Loyalty User";
    ExcludedPermissionSets = "LOCAL_RESTRICTED";

    Permissions =
        tabledata "Loyalty Member" = RIMD,
        table "Loyalty Member" = X,
        tabledata "Loyalty Ledger Entry" = Rm,
        table "Loyalty Ledger Entry" = X,
        page "Loyalty Member Card" = X,
        page "Loyalty Member List" = X,
        codeunit "Loyalty Management" = X,
        report "Loyalty Points Statement" = X,
        query "Loyalty Point Summary" = X,
        xmlport "Export Loyalty Data" = X;
}

Core Properties of Permission Set Objects

Permission Object Types & Access Flags

Business Central differentiates between access to underlying database table data and access to executable object definitions:

1. TableData Access Rights: Controls CRUD (Create, Read, Update, Delete) operations on physical database table rows. Permissions are specified using combinations of four characters:

   • R / r: Read permission (viewing records, running AL FindSet / Get loops, reading via APIs or queries).
   • I / i: Insert permission (creating new records via UI, AL Insert, or data exchange).
   • M / m: Modify permission (updating existing record fields via UI, AL Modify, or batch routines).
   • D / d: Delete permission (removing records via UI, AL Delete, or batch deletion).

2. Executable Objects Access Rights: Controls the ability to invoke, open, or run object definitions. Executable objects require the X (Execute) permission:

   • Table: Execute permission on the table object definition (required to open table browsers or invoke table triggers).
   • Page: Execute permission to open and view the UI page or API page.
   • Codeunit: Execute permission to invoke procedures or run the codeunit via Codeunit.Run().
   • Report: Execute permission to generate, preview, print, or schedule report processing.
   • XMLport: Execute permission to import or export XML/data streams.
   • Query: Execute permission to open, read, or export query datasets.

2. Direct vs. Indirect Permissions Deep Dive

A critical security architecture concept frequently tested on the MB-820 exam is the distinction between Direct and Indirect permissions on TableData.

Direct Permissions (Uppercase: R, I, M, D)

When a user holds direct permissions on a table:

• The user can query and view records directly through lists, card pages, report datasets, OData/REST APIs, or standard AL code loops (FindSet, Get).
• The user can insert, edit, or delete records directly on editable page interfaces, configuration packages, or AL record modification methods (Insert, Modify, Delete).
• Direct permissions provide unrestricted operational access to that table, bounded only by page-level field editability or validation triggers.

Indirect Permissions (Lowercase: r, i, m, d)

When a user holds indirect permissions on a table:

• The user has no direct authority to read, insert, modify, or delete rows from that table.
• Any attempt by the user to open an editable page directly bound to that table, modify records via generic page actions, or call Record.Modify() from unprivileged AL code triggers an immediate runtime exception: "You do not have the following permissions on TableData <TableName>: <AccessType>".
• The Elevation Boundary: The user can access or manipulate the underlying table data strictly through an intermediary executable object (such as a Codeunit, Report, or Table trigger) that declares explicit elevated permissions in its object definition header.

Elevating Permissions via Object Header Properties

To enable users with indirect permissions to execute controlled transactions, the developer decorates the operational codeunit or report with the Permissions property:

codeunit 50105 "Loyalty Ledger Poster"
{
    TableNo = "Loyalty Header";
    // Elevates permissions during codeunit execution
    Permissions = 
        tabledata "Loyalty Ledger Entry" = rimd,
        tabledata "Loyalty Member" = rm;

    trigger OnRun()
    begin
        PostLoyaltyTransaction(Rec);
    end;

    local procedure PostLoyaltyTransaction(var LoyaltyHeader: Record "Loyalty Header")
    var
        LoyaltyLedgerEntry: Record "Loyalty Ledger Entry";
        LoyaltyMember: Record "Loyalty Member";
    begin
        // Executes with elevated authority without exposing direct modify rights to the user
        LoyaltyMember.Get(LoyaltyHeader."Member No.");
        LoyaltyMember."Total Points" += LoyaltyHeader."Points Earned";
        LoyaltyMember.Modify(true);

        LoyaltyLedgerEntry.Init();
        LoyaltyLedgerEntry."Entry No." := 0;
        LoyaltyLedgerEntry."Member No." := LoyaltyHeader."Member No.";
        LoyaltyLedgerEntry."Points" := LoyaltyHeader."Points Earned";
        LoyaltyLedgerEntry."Posting Date" := Today();
        LoyaltyLedgerEntry.Insert(true);
    end;
}

Enterprise Accounting Integrity: The Ledger Paradigm

In enterprise ERP architectures, financial ledgers must maintain complete auditability and prevent tampering:

• G/L Entry (Table 17), Cust. Ledger Entry (Table 21), Vendor Ledger Entry (Table 25), and Item Ledger Entry (Table 32):
  • End users are assigned indirect read (r) or no direct access in their assigned permission sets.
  • Users cannot edit posted entries via page extensions, web service APIs, or configuration packages.
  • Core posting routines (e.g., Codeunit 12 "Gen. Jnl.-Post Line", Codeunit 80 "Sales-Post", Codeunit 90 "Purch.-Post", Codeunit 22 "Item Jnl.-Post Line") declare Permissions = tabledata "G/L Entry" = rimd, tabledata "Cust. Ledger Entry" = rimd.
  • When a user posts a sales invoice, the posting codeunit temporarily elevates data manipulation rights within its isolated transaction context, writes the immutable ledger entries, and completes without ever granting broad write rights to the user's permanent security context.

3. Permission Set Extensions (permissionsetextension)

In modular AL development, extensions frequently introduce custom tables, pages, and processing codeunits that need to seamlessly blend into existing standard permission sets (such as D365 BASIC, D365 BUS PREMIUM, or third-party ISV permission sets). AL provides the permissionsetextension object to achieve this without modifying or cloning base permission sets.

permissionsetextension 50100 "Loyalty Basic Ext" extends "D365 BASIC"
{
    IncludedPermissionSets = "Loyalty User";

    Permissions =
        tabledata "Loyalty Setup" = R,
        table "Loyalty Setup" = X,
        page "Loyalty Setup Card" = X,
        codeunit "Loyalty Notification Handler" = X;
}

Key Architectural Rules of Permission Set Extensions

1. Additive Behavior: Permission set extensions can only add permissions or include child permission sets. They cannot remove, revoke, or restrict permissions granted by the base permission set.
2. Automatic Distribution: Any user or security group that has already been assigned the target permission set (e.g., D365 BASIC) automatically inherits all new object access rights defined in the permissionsetextension the moment the extension is deployed and synchronized, eliminating administrative overhead.
3. Multiple Extensions on One Set: Multiple independent extensions can extend the same base permission set simultaneously without conflict. The runtime merges all permissions into a unified effective permission set.
4. Targeting Custom & Standard Sets: Developers can extend standard Microsoft permission sets or permission sets introduced by other ISV apps listed as dependencies in app.json.

4. Permission Diagnostics & Troubleshooting in Business Central

When end users encounter permission errors during standard business operations or testing, developers and administrators leverage three primary platform diagnostic tools:

+-----------------------------------------------------------------------------------------+
|                         PERMISSION DIAGNOSTIC TOOLKIT IN BC                             |
+-----------------------+-----------------------------------------------------------------+
| Effective Permissions | Real-time computed union of User, Group, Entitlement & Inherent |
| Page (Page 9852)      | permissions. Inspects 'Origin' of every granted right.          |
+-----------------------+-----------------------------------------------------------------+
| Permission Recorder   | Live runtime trace capturing all TableData CRUD and object      |
| Web Client Tool       | execution events during an interactive user workflow.           |
+-----------------------+-----------------------------------------------------------------+
| Telemetry Logging     | Emits Application Insights trace RT0031 (permission error)      |
| (App Insights)        | object ID, object type, stack trace, and userSecurityId.       |
+-----------------------+-----------------------------------------------------------------+

1. The Effective Permissions Page (Page 9852)

Accessible from the User Card actions or by searching Effective Permissions in Tell Me:

• Real-Time Evaluation: Displays the exact runtime permissions computed for a selected user and company across every object in the database.
• Origin Inspection: Clicking on any permission value (Yes, Indirect, No) opens the Permission Set drilldown, displaying the specific permission set, security group, or system entitlement that contributed that permission.
• Conflict Resolution: Helps developers identify whether a user's access is blocked by an excluded permission set (ExcludedPermissionSets) or restricted by license entitlements.

2. The Permission Recorder Tool

Located on the Permission Sets page in the Business Central Web Client:

1. Open Permission Sets, select Record Permissions, and click Start.
2. In a separate browser tab or within the same session, perform the exact business workflow that needs to be authorized (e.g., create a custom service order, attach lines, calculate discount, post document).
3. Return to the Permission Recorder page and select Stop.
4. Business Central inspects the Navision Server Tier (NST) security trace log and displays a complete list of all TableData read/insert/modify/delete rights and object execution (X) permissions accessed during the session.
5. Click Add Permissions to Permission Set or export the recorded lines to paste directly into an AL permissionset object in Visual Studio Code.

3. Telemetry & Runtime Error Signatures

In production cloud environments, unhandled permission failures emit structured Application Insights telemetry:

• Error Pattern: You do not have the following permissions on TableData <TableName>: <AccessType>.
• Application Insights Event RT0031 (Permission error shown): Contains rich diagnostic dimensions (the related RT0032 reports a dependency cycle in permission sets):
  • alObjectId: The ID of the object executing when permission was denied.
  • alObjectType: The type of object (Codeunit, Page, Report).
  • alStackTrace: Complete AL call stack indicating the exact file and line number where the database call failed.
  • userSecurityId: The Entra ID / BC User GUID of the affected user.

4. VS Code AL Extension Permission Generation

Developers can generate AL permission set objects directly from Visual Studio Code using the command palette (Ctrl+Shift+P / Cmd+Shift+P):

• AL: Generate permission set as AL object (current extension): Scans all objects declared in the active workspace and auto-generates a comprehensive permissionset AL file containing default execute (X) and TableData = RIMD entries for all extension objects.