Security Roles

A Security Role (AxSecurityRole) is the top-level unit of the D365 F&O security model. Users are assigned to roles, and each role aggregates duties, privileges, sub-roles, and direct-access permissions to define what the user can see and do.

Roles map to business responsibilities. Standard examples include System Administrator, Accounts Payable Clerk, Purchasing Agent, and Sales Manager. Custom roles can be created for any business function.

---

Structure

A security role contains four child collections:

Collection	Child Type	Purpose
Duties	AxSecurityDutyReference	References to duties that group related privileges. This is the primary mechanism for granting access.
Privileges	AxSecurityPrivilegeReference	Direct privilege references — bypasses the duty layer. Use sparingly.
Sub-Roles	AxSecurityRoleReference	References to other roles whose access is inherited. Useful for building composite roles.
DirectAccessPermissions	AxSecurityDataEntityReference	Direct table/data entity access grants outside the entry-point model (rare).

tip

Prefer assigning duties to roles rather than individual privileges. Duties provide a meaningful business grouping that is easier to audit and manage as the number of privileges grows.

---

Standard Roles

Role	AOT Name	Description
System Administrator	SystemAdministrator	Full access to all application functionality.
Accounts Payable Clerk	VendAccountsPayableClerk	Processes vendor invoices and payments.
Purchasing Agent	PurchasingAgent	Creates and manages purchase orders.
Accounts Receivable Clerk	CustAccountsReceivableClerk	Manages customer invoices and collections.
Sales Manager	TradeSalesManager	Oversees sales order operations.
Human Resources Manager	HcmHumanResourcesManager	Manages employee records and HR processes.

---

Creating a Security Role

1. In Visual Studio, right-click your project and select Add → New Item → Security Role.
2. Set the Name, Label, and Description properties.
3. Add duty references under the Duties node.
4. Optionally add privilege references or sub-role references.
5. Build and deploy.

Code Example — Checking Role Assignment

Code Example — Enumerating Role Duties

---

Extensions

Use a Security Role Extension (AxSecurityRoleExtension) to modify standard Microsoft roles without overlaying them. Role extensions are the recommended approach for adding custom access to standard roles.

What Can Be Extended

Collection	Description
Duties	Add new duty references to the extended role.
Privileges	Add new privilege references to the extended role.
DirectAccessPermissions	Add direct table/entity access grants to the extended role.
PropertyModifications	Modify scalar properties (e.g., Label, Description, Enabled) of the base role.

warning

You cannot remove duties or privileges from a standard role via extension — you can only add new ones. To disable an inherited duty, create a custom role that excludes it, or use database-level security configuration to override the role definition at runtime.

Extension Example

To add a custom duty to the standard Purchasing Agent role:

1. Right-click the PurchasingAgent security role in Application Explorer.
2. Select Create Extension.
3. In the new extension object, add your custom duty reference under the Duties node.
4. Build and deploy.

---

Child Object Properties

Duty Reference

Each entry in the Duties collection is an AxSecurityDutyReference:

Property	Description
Name	The AOT name of the referenced duty.
Enabled	Whether this duty reference is active. Set to No to disable without removing.
Tags	Tags for this element separated by semicolon.

Privilege Reference

Each entry in the Privileges collection is an AxSecurityPrivilegeReference:

Property	Description
Name	The AOT name of the referenced privilege.
Enabled	Whether this privilege reference is active. Set to No to disable without removing.
Tags	Tags for this element separated by semicolon.

Sub-Role Reference

Each entry in the SubRoles collection is an AxSecurityRoleReference:

Property	Description
Name	The AOT name of the referenced role whose access is inherited.
Enabled	Whether this sub-role reference is active.
Tags	Tags for this element separated by semicolon.

Direct Access Permission

Each entry in the DirectAccessPermissions collection is an AxSecurityDataEntityReference:

Property	Description
Name	The AOT name of the referenced table or data entity.
Grant	Access level granted to data (AccessGrant).
GrantCurrentData	Access level granted to current-period data.
GrantFutureData	Access level granted to future-period data.
GrantPastData	Access level granted to past-period data.
Tags	Tags for this element separated by semicolon.

---

Properties

13/13 properties

Property	Display Name	Type	Description
Security RoleAxSecurityRole
Name	Name	String	The name of the element.
IsObsolete	Is Obsolete	NoYes	Determines whether the element is deprecated or not. Values: No (0), Yes (1)
Visibility	Visibility	CompilerVisibility	The visibility of the element. Values: Private (0), Protected (1), Public (2), Internal (3), InternalProtected (4)
Tags	Tags	String	Tags for this element separated by semicolon.
Label	Label	String	Role name that is displayed.
Description	Description	String	Role description that is displayed.
Enabled	Enabled	NoYes	Set to false to hide the node from the security framework. Values: No (0), Yes (1)
ContextString	Context String	String	If the context type is ContextString, this property displays the string.
CanBeDeletedFromUI	Can Be Deleted From UI	NoYes	Set to NO to block ability for users to delete critical security roles. Values: No (0), Yes (1)
Role ExtensionAxSecurityRoleExtension
Name	Name	String	The name of the extension element.
IsObsolete	Is Obsolete	NoYes	Determines whether the element is deprecated or not. Values: No (0), Yes (1)
Visibility	Visibility	CompilerVisibility	The visibility of the element. Values: Private (0), Protected (1), Public (2), Internal (3), InternalProtected (4)
Tags	Tags	String	Tags for this element separated by semicolon.

---