platform sdk privileges

About privileges

Privileges control what actions users can perform in Security Center. Every operation, from viewing cameras to modifying cardholders, requires the user to have the required privilege granted.

The SDK provides methods to check privileges, query privilege definitions, and modify privilege assignments on users and user groups.

Privilege types

Security Center has three types of privileges:

Type	Purpose	Displayed in partition treeview	Used in privilege computation
Entity	Controls operations on specific entity types (view, modify, add, delete)	Yes	Yes
Task	Controls system-wide functionality like reports or application access	No	Yes
Group	Organizes related privileges in the UI	Yes	No

Entity privileges apply to specific entities and can be granted or denied per partition. Use these for operations like viewing cameras or modifying cardholders.

Task privileges apply globally and cannot have partition-specific exceptions. Use these for functionality like running Config Tool or accessing reports.

Group privileges are organizational containers. They appear in the Config Tool privilege tree but are not used when computing whether a user has permission.

Checking privileges

Use SecurityManager.IsPrivilegeGranted() to check if a user has a specific privilege.

Basic privilege check

Check whether the logged-on user has a Task privilege or has an Entity privilege in at least one partition:

bool canViewCameras =
    engine.SecurityManager.IsPrivilegeGranted(
        SdkPrivilege.ViewCameras);

For an Entity privilege, this overload returns true when the privilege is granted in at least one partition. To check the effective privilege for a specific entity, use the overload that accepts the entity GUID.

Entity-specific privilege check

Check if the logged-on user has a privilege on a specific entity:

Guid cameraGuid = /* camera entity GUID */;
bool canModifyCamera = engine.SecurityManager.IsPrivilegeGranted(SdkPrivilege.ModifyCameras, cameraGuid);

This check considers partition access. The method returns false if:

• The privilege is denied or undefined.
• The user does not have access to any partition containing the entity.

If the user belongs to a user group that has partition access, the method returns true even if the user does not have direct partition membership.

Checking another user's privilege

Check if a specific user has a privilege on an entity:

Guid userGuid = /* user entity GUID */;
Guid cameraGuid = /* camera entity GUID */;
bool userCanModify = engine.SecurityManager.IsPrivilegeGranted(
    SdkPrivilege.ModifyCameras,
    userGuid,
    cameraGuid);

Pass Guid.Empty as the entity parameter to check a basic privilege without entity context.

Administrator users have every privilege supported by the system license. A privilege check can still return false or throw an exception when the privilege is unavailable or a supplied user, application, privilege, or entity identifier is invalid.

Async privilege checks

For workstation-aware privilege checking, use the async methods:

bool granted = await engine.SecurityManager.IsPrivilegeGrantedAsync(
    SdkPrivilege.ViewCameras,
    userGuid,
    applicationGuid,
    entityGuid);

The four-argument overload validates the workstation associated with the application in addition to the user's privilege and partition access. It applies only to entity privileges and requires a specific entity GUID; it does not evaluate global privileges.

Privilege states

A privilege can be in one of three states:

State	Value	Meaning
Granted	PrivilegeAccess.Granted	User can perform the action
Denied	PrivilegeAccess.Denied	User cannot perform the action
Undefined	PrivilegeAccess.Undefined	No direct assignment; the effective state can be inherited from a user group

IsPrivilegeGranted() evaluates the effective privilege state. It returns false when the effective state is Denied or remains Undefined after user-group inheritance. A user whose direct assignment is Undefined can still receive the privilege through a user group.

Querying privileges

Use the SecurityManager APIs to inspect the privilege definitions that are currently available in the system.

Listing all privileges in the system

Use GetPrivilegeDefinitions() to retrieve all privilege definitions:

ReadOnlyCollection<PrivilegeDefinitionInformation> allPrivileges =
    engine.SecurityManager.GetPrivilegeDefinitions();

foreach (PrivilegeDefinitionInformation privilege in allPrivileges)
{
    Console.WriteLine($"{privilege.Description}");
    Console.WriteLine($"  ID: {privilege.Id}");
    Console.WriteLine($"  Type: {privilege.Type}");
    Console.WriteLine($"  Parent: {privilege.ParentId}");
}

Each PrivilegeDefinitionInformation object contains:

Property	Type	Description
Id	Guid	Unique identifier
ParentId	Guid	Parent privilege identifier
Description	string	Localized description
Type	PrivilegeType	Entity, Task, or Group
Children	ReadOnlyCollection<Guid>	Child privilege identifiers

Listing a user's privileges

Access the Privileges property on a User or UserGroup entity:

var user = (User)engine.GetEntity(userGuid);

foreach (PrivilegeInformation privilege in user.Privileges)
{
    Console.WriteLine($"{privilege.PrivilegeGuid}: {privilege.State}");
}

Each PrivilegeInformation object contains:

Property	Type	Description
PrivilegeGuid	Guid	Privilege identifier
State	PrivilegeAccess	Granted, Denied, or Undefined

The Privileges property returns the raw privilege assignments on the user. It does not reflect:

• Privileges inherited from user groups
• Partition exceptions
• Effective privilege computation

Use IsPrivilegeGranted(privilege) to determine whether an Entity privilege is granted in at least one partition. Use IsPrivilegeGranted(privilege, entityGuid) to include the entity's partition access and partition exceptions.

Setting privileges on users

Use SetPrivilegeState() to grant or deny privileges on a user or user group:

var user = (User)engine.GetEntity(userGuid);

// Grant a privilege
user.SetPrivilegeState(SdkPrivilege.ViewCameras, PrivilegeAccess.Granted, PrivilegeChangeBehavior.Default);

// Deny a privilege
user.SetPrivilegeState(SdkPrivilege.ModifyCameras, PrivilegeAccess.Denied, PrivilegeChangeBehavior.Default);

Applying to child privileges

By default, SetPrivilegeState() only affects the specified privilege. To apply the state to all child privileges, use PrivilegeChangeBehavior.ApplyToChildrenPrivileges:

user.SetPrivilegeState(
    SdkPrivilege.ViewCameras,
    PrivilegeAccess.Granted,
    PrivilegeChangeBehavior.ApplyToChildrenPrivileges);

Restrictions

The following restrictions apply when setting privileges:

• Administrator privileges cannot be changed. SetPrivilegeState throws SdkException with SdkError.ReadonlyField when the target user or user group is an administrator.
• The logged-on user must have modify access. The logged-on user must have modify access to the target user's or user group's partition. Otherwise, the operation throws SdkException.
• PrivilegeAccess.None cannot be assigned. Passing PrivilegeAccess.None throws ArgumentException. Use Granted, Denied, or Undefined.
• The change behavior must be valid. Use PrivilegeChangeBehavior.Default or PrivilegeChangeBehavior.ApplyToChildrenPrivileges. Any other value throws ArgumentOutOfRangeException.

Built-in privileges

The SdkPrivilege class provides constants for all built-in Security Center privileges:

// Application access
SdkPrivilege.RunConfigTool
SdkPrivilege.RunSecurityDesk
SdkPrivilege.SdkLogon

// Entity operations
SdkPrivilege.ViewCameras
SdkPrivilege.ModifyCameras
SdkPrivilege.AddCameras
SdkPrivilege.RemoveCameras

// Root privilege (parent of all privileges)
SdkPrivilege.Root

Privilege hierarchy

Privileges are organized as a tree. Walk upward with ParentId and stop when ParentId is Guid.Empty: SdkPrivilege.Root, described as "All privileges", is the top of the main tree, and a small number of privileges sit outside it and also report an empty parent.

Getting child privileges

Use SdkPrivilege.GetPrivilegeAndChildren() to get a privilege and all its descendants:

IEnumerable<SdkPrivilege> privileges = SdkPrivilege.GetPrivilegeAndChildren(
    SdkPrivilege.ViewCameras);

foreach (var privilege in privileges)
{
    Console.WriteLine(privilege.Id);
}

To exclude specific privilege types (for example, Task privileges when working with partition exceptions):

IEnumerable<SdkPrivilege> entityPrivileges = SdkPrivilege.GetPrivilegeAndChildren(
    SdkPrivilege.ViewCameras,
    PrivilegeType.Task);  // Excludes Task type

User group inheritance

When a user belongs to a user group:

• The user inherits privileges from the group.
• A privilege set on the user overrides the group setting.
• Nested user groups are supported; child groups inherit from parent groups.

Partition interaction

Privileges and partitions work together to control access:

• Partition access determines which entities a user can see.
• Privileges determine what operations a user can perform.

For entity-specific privilege checks, the user must have both partition access and the required privilege.

Partition exceptions

Partition exceptions allow granting or denying specific privileges within a partition, overriding the user's global privilege setting. Only Entity privileges support partition exceptions; Task privileges do not.

For details on working with partitions and partition exceptions, see About partitions.

Checking if a privilege exists

Use HasPrivilege() on a User or UserGroup to check if a privilege definition exists and is licensed:

var user = (User)engine.GetEntity(userGuid);
bool exists = user.HasPrivilege(customPrivilegeGuid);

This method returns true if:

• The privilege is defined in the system.
• The required license is present.

This is different from IsPrivilegeGranted(), which checks whether the privilege is actually granted to the user.

Use HasPrivilege() to verify that a custom privilege is properly registered before attempting to check or set it.

See also

• About partitions: Partition membership, access control, and partition exceptions.
• About SDK certificates: SDK certificate fundamentals shared across all SDK families.
• About the Platform SDK: SDK assemblies and the Engine class.