Previous

Next

Create entitlements and permission sets

Completed

When developing an app, you can handle entitlements and permission sets as objects in AL, and you can extend existing permission sets in AL. You can use the following object types for handling entitlements and permissions:

• EntitlementObject

• PermissionSet

• PermissionSetExtension

Entitlement object

The entitlement object in Dynamics 365 Business Central describes which objects in Business Central that a customer is entitled to use according to the license that they purchased or according to the role that they have in Microsoft Entra ID.

An entitlement consists of many PermissionSet objects put together to constitute a set of meaningful permissions for a user. An entitlement can only include permission set objects, which reference the objects that are included within the same app. This aspect ensures that the entitlements that are included with one app can't alter or redefine the entitlements that are included with another app.

Entitlements can only be used with the online version of Dynamics 365 Business Central.

Typing the shortcut tentitlement will create the basic layout for an entitlement object when you are using the AL Language extension in Visual Studio Code.

This example illustrates a simple entitlement object with the Type property set to Role, which means that the entitlement is associated with a Microsoft Entra ID role. When Type is set to Role, the RoleType property is used to distinguish between local and delegated assignments of the role, which in this case is Delegated. The ObjectEntitlements property defines the list of permissions that the entitlement includes.

entitlement BC_Role_Delegated
{
    Type = Role;
    RoleType = Delegated;
    Id = '1a2aaaaa-3aa4-5aa6-789a-a1234567aaaa';
    ObjectEntitlements = 
        ”D365 BUS PREMIUM - BaseApp”;
}

The following example shows an entitlement where Type is PerUserServicePlan:

entitlement BC_PerUserServicePlan
{
    Type = PerUserServicePlan;
    Id = '1a2aaaaa-3aa4-5aa6-789a-a1234567aaaa';

    ObjectEntitlements = "D365 BASIC";
   
}

The entitlement object in Business Central describes which objects in an app a customer is entitled to use according to the license that they purchased or the role that they have in Microsoft Entra ID.

An entitlement consists of references to a number of PermissionSet objects put together to constitute a set of meaningful permissions for a user. An entitlement can only include permission set objects, which reference the objects that are included within the same app. This is to ensure that the entitlements included with one app can't alter or redefine the entitlements included with another app.

Each entitlement can then be linked to a license identifier. When a user signs in, entitlements are resolved, and if a user has the license that the entitlement links to, the user will get the permissions that the entitlement defines access to.

Note that while entitlements can be defined already at the time of general availability of Business Central 2022 release wave 2, the first wave of actual AppSource transactability support won't be generally available until at least the next release.

Permission set object

The permission set object in Business Central describes permissions on objects. Permission sets are building blocks that are used to compose assignable permission sets and entitlements. Assignable permission sets are permissions that an admin can assign to users in Business Central by using the Permission Sets page. An entitlement is a collection of permission sets that comprise a set of meaningful permissions for a user.

Some permission sets can be non-assignable, meaning that they aren't discoverable and assignable in the UI in Business Central; instead, they can be used as building blocks to compose functional assignable permission sets.

If a permission set is extended through AL, that extension will make additive changes to the permission set. Essentially, an extension can provide elevated privileges to an otherwise limited set of permissions. Building permission sets that can be extended must be done carefully with this factor in mind.

Typing the shortcut tpermissionset will create the basic layout for a permission set object when you are using the AL Language extension in Visual Studio Code.

The following example illustrates the Sales Person permission set, with permissions given to data in tables, each with different levels of access. The Assignable property is set to true, which allows the permission set to be assigned to a user. The Permissions property is set to the list of objects to give permissions to. The RIMD access that is assigned to data in the Customer table provides full access, whereas access is limited for data in the Currency table, only allowing full read and modify permission.

permissionset 50134 "Sales Person"
{
    Assignable = true;
    Caption = 'Sales Person';

    Permissions = 
        tabledata Customer = RIMD,
        tabledata "Payment Terms" = RMD,
        tabledata Currency = RM,
        tabledata "Sales Header" = RIM,
        tabledata "Sales Line" = RIMD;
}

The following example of a permission set illustrates assigned permissions to run codeunits. With the IncludedPermissionSets property, you will specify that the Sales Person permission set is also included in MyPermissionSet.

permissionset 50130 MyPermissionSet 
{ 
    Assignable = true;
    Caption = 'My PermissionSet';
    IncludedPermissionSets = "Sales Person"; 

    Permissions = 
        codeunit SomeCode = x, 
        tabledata Vendor = RIm,
        codeunit AccSchedManagement= X; 
}

Permission set extension object

The permission set extension object in Business Central adds permissions to an existing permission set that is defined in AL. A permission set extension object can't remove permissions from an existing permission set; it can only add permissions. For example, if you add an extension to Business Central, you can use permission set extension objects to grant permissions to the objects in your extension. Basically, the administrator of Business Central doesn't have to assign additional permission sets to users because that assignment automatically happens when the extension is installed, and the permissions go away if the extension is uninstalled.

If a permission set is extended through AL, that extension will make additive changes to the permission set. Essentially, an extension can provide elevated privileges to an otherwise limited set of permissions. Building permission sets that can be extended must be done carefully with this factor in mind.

Typing the shortcut tpermissionsetextension will create the basic layout for a permission set extension object when you are using the AL Language extension in Visual Studio Code.

The following permission set extension example extends the Sales Person permission set by adding direct insert and delete permissions to the Currency table data.

permissionsetextension 50140 "Extended Sales Doc" extends "Sales Person"
{
    Assignable = true;
    Caption = 'Extended Sales Doc';

    Permissions =
        tabledata Currency = ID;
}

Generate or update AL permission set(s)

Permission sets are at the core of controlling access to AL objects. When adding new objects, however, it can be easy to forget to update the permissions. To help with this, it's now possible with a new AL command to generate or update a permission file for the active project.

Now there's a command to generate a permission set as an AL object: al.generatePermissionSetForExtensionObjects.

When invoking the command, a developer can choose to create a new permission file or select an existing file to update.

The older functionality of creating a permission set XML file is moved into the command al.generatePermissionSetForExtensionObjectsAsXml.

Continue