Entitlements and Permission Sets Overview

Article
02/23/2024

APPLIES TO: Business Central 2021 release wave 1 (v18.0) and later

Note

Azure Active Directory is now Microsoft Entra ID. Learn more

Business Central uses two main concepts for defining access to functionality: Entitlements and permissions.

Entitlements describe which objects in Business Central a customer is entitled to use according to the license that they purchased from Microsoft or according to the Microsoft Entra role that they have assigned in Microsoft 365 Admin Center, such as Global Administrator. Entitlements are only used in the online version of Business Central.
Permissions describe which objects an administrator or a partner has given the user.
Permission sets combine objects permissions in logical groups (or sets), which can then be assigned to the users explicitly or through a user group.

For more information about assigning licenses, see Licensing in Dynamics 365 Business Central. For more information about how to create and assign permissions, see Assign Permissions to Users and Groups.

Permission Set scope

A Business Central solution contains a number of predefined permission sets that are added by Microsoft or by your software provider (by an ISV application that you installed from AppSource).

Permission sets included with Microsoft and AppSource apps defined as AL objects are of the type System.

End-users can't create or edit these types of permission sets or the permissions within them. However, they can copy these permission sets to define their own permission sets and permissions. Permission sets that users create, from new or as copies, are of the type User-Defined and they can be edited.

Creating entitlements and permission sets in AL

When developing an app, entitlements and permission sets are handled as objects in AL, and existing permission sets can be extended in AL. The following object types are used for handling entitlements and permissions:

System Application objects for permissions

The Business Central System Application includes a number of objects that can help you when working with permissions:

Upgrade considerations (prior to version 18)

Starting with Business Central 2021 release wave 1 (v18.0), the Business Central demo database, which is shipped with our on-premises installation, doesn't contain any data in the Permission Set and Permission tables in the application database. Instead, the System permission sets and permissions are provided as AL objects of type PermissionSet and PermissionSetExtension, included with Microsoft apps.

The application database tables that used to store the entitlements won't contain any data either, because entitlements are now defined as AL objects.

Business Central server configuration file (CustomSettings.config) includes a setting that allows on-premises administrators to decide whether they want to continue using the permissions defined as data or as AL objects:

 <add key="UsePermissionSetsFromExtensions" value="true" />

The default value for this setting is true, meaning that the server will be retrieving all System permission sets and permissions from the AL objects of type PermissionSet and PermissionSetExtension. With the value for this setting set to true, the permissions data, in case it is still present in the application database, will be disregarded.

It's not possible to customize the System permission sets and permissions used in the online version of Business Central. End-users can only copy these types to new permission sets, which they can then adjust to their needs. For more information, see Assign Permissions to Users and Group.

In the on-premises version of Business Central, even though it's not recommended, the partners can customize the permission sets and permissions shipped in the application database. In this case, as for any upgrade before, the changes in Microsoft permissions should be merged with the customized permissions by partners during upgrade.

Although starting with Business Central 2021 release wave 1 (v.18.0), System permissions are no longer shipped as data in the application database, the partners can use the same procedure as before to export the new permissions that are defined using AL objects. The new permission sets and permissions can be exported into XML file by running XMLport 9171 Import/Export Permission Sets, making it possible to compare and merge the customized permission sets in your old database with the newly shipped permission sets. Find more details, see Export and Import Permission Sets and Permissions.

How to upgrade permission sets (when upgrading to version 18)

When upgrading to version 18, first decide whether you want to use the permissions defined as data or switch to permissions defined as AL objects. Then, follow the guidelines at Upgrading Permission Sets for details on how to do the upgrade.

Earlier versions of Business Central

In releases of Business Central prior to 2021 release wave 1 (v18.0), System and Extension permissions and entitlements were defined as data in the application database:

Entitlements tables:

Entitlement
Entitlement Set
Membership Entitlement

Permissions tables:

Permission Set
Permission

Keeping such sensitive information as data comes with additional maintenance, security, and audit risks for the software providers (ISVs). Changes applied to this data should ideally be well traceable, easy to update and maintain. Starting with Business Central 2021 release wave 1, the System permissions and entitlements are defined in code, using Entitlement, PermissionSet, and PermissionSetExtension AL objects. This change provides ISVs with all of the advantages of using the AL Language extension in Visual Studio Code and source control systems (as Visual Studio Online and GitHub) to design, get an overview, and track changes to the objects that describe user access.

Turning this data into code has another significant advantage: the ability to apply hotfixes to the entitlements and permissions in the same way that the hotfixes are applied to the apps themselves, simply by updating an app to a new version which carries fixed code. This improves Business Central support agility considerably, ultimately improving customer satisfaction with the service.

And finally, the new AL objects are envisioned to become the core building blocks in the story of monetizing the AppSource apps. It's through these new AL objects that AppSource ISVs will be able to define which capabilities of their apps should be made available to their users, when the customers purchase their app licenses. With Business Central 2021 release wave 1, we're paving the way by moving the entitlements and permission sets into AL objects for Microsoft apps, so that ISVs can follow the same approach for their apps, when the monetization story is introduced with one of the next releases of Business Central.

User-Defined permission sets and permissions, and functionality around them, remain unchanged. They're still stored as data in the tenant database:

Tenant Permission
Tenant Permission Set

Permission sets and permissions included with apps in XML format will continue to work as before, however, we recommend you to start using the AL objects of type PermissionSet and PermissionSetExtension instead.