/skill-permissions

name: skill-permissions
description: "AL permission set design for Business Central. Use when creating PermissionSets, implementing least-privilege access, or designing security models for extensions."

Skill: AL Permission Management

Purpose

Generate and manage permission sets for AL Business Central extensions following the principle of least privilege: role-based permission design, AL vs XML formats, permission set extensions, and security validation.

When to Load

This skill should be loaded when:

• A new extension needs its permission sets generated
• Permission errors surface at runtime ("You do not have permission to…")
• Role-based access control is being designed for an extension
• A security or compliance review requires permission documentation
• Permission set extensions need to be created for base-app objects

Core Patterns

Pattern 1: AL Permission Set Object (Preferred)

Generate with the VS Code permission-set generation command (not an agent tool), then refine:

permissionset 50100 "Contoso Sales"
{
    Assignable = true;
    Caption = 'Contoso Sales Permissions';

    Permissions =
        // Tables — object-level execute
        table "Contoso Sales Setup" = X,
        table "Contoso Discount Rule" = X,
        // Table data — RIMD granularity
        tabledata "Contoso Sales Setup" = R,          // read-only for most users
        tabledata "Contoso Discount Rule" = RIMD,     // full CRUD
        // Executable objects
        codeunit "Contoso Sales Management" = X,
        page "Contoso Sales Setup Card" = X,
        page "Contoso Discount Rules List" = X,
        report "Contoso Sales Summary" = X,
        xmlport "Contoso Sales Import" = X;
}

**Permission letters for `tabledata`:**

| Letter | Meaning | Grant when… | |---|---|---| | `R` | Read | User needs to view data | | `I` | Insert | User needs to create records | | `M` | Modify | User needs to edit existing records | | `D` | Delete | User needs to remove records (grant sparingly) |

For non-tabledata objects (`table`, `codeunit`, `page`, `report`, `xmlport`, `query`):

• `X` = Execute / Run
• `0` = No permission (omit the line instead)

Pattern 2: Role-Based Hierarchy (Least Privilege)

Design a layered permission structure — each role includes only what it needs:

// Layer 1: Base — read-only access shared by all roles
permissionset 50100 "Contoso Base"
{
    Assignable = false;                   // not directly assignable to users
    Caption = 'Contoso Base (Read)';

    Permissions =
        tabledata "Contoso Sales Setup" = R,
        tabledata "Contoso Discount Rule" = R,
        page "Contoso Sales Setup Card" = X,
        page "Contoso Discount Rules List" = X;
}

// Layer 2: User — standard operations (includes Base)
permissionset 50101 "Contoso User"
{
    Assignable = true;
    Caption = 'Contoso User';

    IncludedPermissionSets = "Contoso Base";

    Permissions =
        tabledata "Contoso Discount Rule" = IM,      // create + edit (no delete)
        codeunit "Contoso Sales Management" = X,
        report "Contoso Sales Summary" = X;
}

// Layer 3: Admin — full control (includes User)
permissionset 50102 "Contoso Admin"
{
    Assignable = true;
    Caption = 'Contoso Admin';

    IncludedPermissionSets = "Contoso User";

    Permissions =
        tabledata "Contoso Sales Setup" = RIMD,       // full CRUD on setup
        tabledata "Contoso Discount Rule" = D,         // adds Delete
        xmlport "Contoso Sales Import" = X;            // data import only for admin
}

**Design rules:**

• `Assignable = false` for base/internal layers — only assign leaf-level sets to users
• `IncludedPermissionSets` builds hierarchy — no need to repeat parent permissions
• Separate functional areas into distinct sets when the extension covers multiple domains

Pattern 3: Permission Set Extension

Extend existing BC permission sets to include your extension's objects — so users with standard roles automatically get access:

permissionsetextension 50100 "Contoso D365 Sales Ext" extends "D365 SALES"
{
    Permissions =
        tabledata "Contoso Discount Rule" = RIMD,
        codeunit "Contoso Sales Management" = X,
        page "Contoso Discount Rules List" = X;
}

permissionsetextension 50101 "Contoso D365 Read Ext" extends "D365 READ"
{
    Permissions =
        tabledata "Contoso Sales Setup" = R,
        tabledata "Contoso Discount Rule" = R,
        page "Contoso Sales Setup Card" = X;
}

**When to use `permissionsetextension`:**

• Your objects should be accessible to users who already have a standard BC role
• Avoids requiring admins to manually assign a new permission set to every user
• Always limit to what that role level logically needs (read-only for D365 READ, full for D365 SALES)

Pattern 4: XML Permission Set (Legacy Format)

Generate the XML format via the VS Code permission-set command (not an agent tool) when:

• Targeting older BC versions (< BC 20)
• Import via BC admin UI is required
• Customer tooling only supports XML format

<?xml version="1.0" encoding="utf-8"?>
<PermissionSets>
  <PermissionSet RoleID="CONTOSO-SALES" RoleName="Contoso Sales Permissions">
    <Permission>
      <ObjectType>0</ObjectType>         <!-- TableData -->
      <ObjectID>50100</ObjectID>
      <ReadPermission>1</ReadPermission>
      <InsertPermission>1</InsertPermission>
      <ModifyPermission>1</ModifyPermission>
      <DeletePermission>0</DeletePermission>
    </Permission>
    <Permission>
      <ObjectType>5</ObjectType>         <!-- Codeunit -->
      <ObjectID>50100</ObjectID>
      <ExecutePermission>1</ExecutePermission>
    </Permission>
  </PermissionSet>
</PermissionSets>

XML `ObjectType` codes: `0` = TableData, `1` = Table, `3` = Report, `5` = Codeunit, `6` = XMLport, `8` = Page, `9` = Query.

**Prefer AL format** for new development — it lives in source control, participates in build, and supports `IncludedPermissionSets`.