platform sdk partitions

About partitions

Partitions organize entities in Security Center and control which users can access them. By assigning entities to partitions and granting users access to specific partitions, you control visibility and access throughout the system.

How partitions work

A partition is a container for entities. A user can see an entity when the user has access to at least one partition that contains the entity. An entity can belong to multiple partitions.

Partitions work together with privileges:

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

For a user to modify a camera, they need both access to the camera's partition and the ModifyCameras privilege.

Adding entities to partitions

Use either the partition API or the entity API depending on which object you already have in scope.

Using Partition.AddMember

Add an entity to a partition using the AddMember() method:

var partition = (Partition)engine.GetEntity(partitionGuid);
var camera = (Camera)engine.GetEntity(cameraGuid);

partition.AddMember(camera);

Using Entity.InsertIntoPartition

Add an entity to a partition from the entity side:

var camera = (Camera)engine.GetEntity(cameraGuid);
camera.InsertIntoPartition(partitionGuid);

Both approaches produce the same result. An entity can belong to multiple partitions.

Not all entity types support partition membership. Entity types like Camera, Alarm, Cardholder, Credential, and CustomEntity implement IPartitionSupport and can be added to or removed from partitions. Entity types like Server, Network, and Device do not support partition manipulation.

Default creation partitions

Unless you set DefaultEntityCreationPartitions, Security Center places new partition-supporting entities in the root partition (Partition.DefaultPartitionGuid). To place new entities in specific partitions instead, set this property on the engine:

// Set default partitions for the current Engine connection
engine.DefaultEntityCreationPartitions = new CreationPartitions(
    salesPartitionGuid,
    null,
    null);

// New entities are automatically added to the default partitions
var camera = (Camera)engine.CreateEntity("Lobby Camera", EntityType.Camera);
// camera is now a member of salesPartitionGuid

This setting only applies to the current Engine connection. Each connection maintains its own default partitions.

The three-parameter constructor accepts up to three default partitions:

engine.DefaultEntityCreationPartitions = new CreationPartitions(
    partition1Guid,
    partition2Guid,
    partition3Guid);

Pass null only for trailing unused parameters. If you need to provide a collection of partition GUIDs, use the CreationPartitions(IEnumerable<Guid>) constructor.

Important

In partition-isolated deployments, such as Security Center SaaS (Classic), users often do not have access to the root partition. In those environments, set DefaultEntityCreationPartitions to one or more partitions the user can access before you create entities.

Setting DefaultEntityCreationPartitions throws SdkException with SdkError.UnsufficientPrivilege if the logged-on user cannot access any specified partition. Creating an entity also requires the add and view privileges for that entity type in each creation partition.

Removing entities from partitions

Removing membership uses the same two-sided API pattern as adding membership.

Using Partition.RemoveMember

var partition = (Partition)engine.GetEntity(partitionGuid);
var camera = (Camera)engine.GetEntity(cameraGuid);

partition.RemoveMember(camera);

Using Entity.RemoveFromPartition

var camera = (Camera)engine.GetEntity(cameraGuid);
camera.RemoveFromPartition(partitionGuid);

Moving between partitions

To move an entity to a different partition, add it to the new partition before removing its previous memberships:

Camera camera = (Camera)engine.GetEntity(cameraGuid);
Guid[] previousPartitionGuids = camera.GetPartitions()
    .Where(partitionGuid => partitionGuid != newPartitionGuid)
    .ToArray();

camera.InsertIntoPartition(newPartitionGuid);

foreach (Guid previousPartitionGuid in previousPartitionGuids)
{
    camera.RemoveFromPartition(previousPartitionGuid);
}

Querying partition membership

These APIs let you inspect partition membership from either the partition or the entity side.

Getting partition members

Retrieve the direct members of a partition:

Partition partition = (Partition)engine.GetEntity(partitionGuid);
ReadOnlyCollection<Guid> members = partition.Members;

foreach (Guid memberGuid in members)
{
    Entity entity = engine.GetEntity(memberGuid);
    Console.WriteLine(entity.Name);
}

Getting an entity's partitions

Retrieve the partitions to which an entity is directly assigned:

Camera camera = (Camera)engine.GetEntity(cameraGuid);
IEnumerable<Guid> partitions = camera.GetPartitions();

foreach (Guid partitionGuid in partitions)
{
    Partition partition =
        (Partition)engine.GetEntity(partitionGuid);
    Console.WriteLine(partition.Name);
}

User access to partitions

Partition access controls who can see entities in a partition. Privileges still control what actions that person can perform.

Granting partition access

Add a user or user group to a partition:

var partition = (Partition)engine.GetEntity(partitionGuid);
partition.AddUserAccess(userGuid);

Users with partition access can see entities in that partition, subject to their privileges.

Revoking partition access

Remove a user or user group from a partition:

var partition = (Partition)engine.GetEntity(partitionGuid);
partition.RemoveUserAccess(userGuid);

Querying partition access

Get all users and user groups with access to a partition:

Partition partition = (Partition)engine.GetEntity(partitionGuid);
ReadOnlyCollection<Guid> userAccesses = partition.UserAccesses;

foreach (Guid userOrGroupGuid in userAccesses)
{
    Entity userOrGroup = engine.GetEntity(userOrGroupGuid);
    Console.WriteLine(userOrGroup.Name);
}

This includes users with inherited access through the partition hierarchy.

Partition hierarchy

Partitions can be organized in a hierarchy by adding partitions as members of other partitions.

Creating a partition hierarchy

var parentPartition = (Partition)engine.GetEntity(parentGuid);
var childPartition = (Partition)engine.GetEntity(childGuid);

parentPartition.AddMember(childPartition);

Access inheritance

When a user has access to a parent partition, child partitions inherit that access unless an access restriction is configured on a child partition. The user can see entities in the parent and accessible child partitions, subject to the user's privileges.

When an intermediate partition is deleted, its child partitions are automatically moved to the parent partition.

Partition exceptions

Partition exceptions allow you to override a user's global privilege setting within a specific partition. For example, you can grant a user ModifyCameras globally but deny it in a specific partition.

Creating a partition exception

var partition = (Partition)engine.GetEntity(partitionGuid);

partition.CreateOrUpdatePartitionException(
    userGuid,
    SdkPrivilege.ModifyCameras,
    PrivilegeAccess.Denied);

Only PrivilegeAccess.Granted or PrivilegeAccess.Denied are valid. You cannot set an exception to Undefined.

Removing a partition exception

var partition = (Partition)engine.GetEntity(partitionGuid);
partition.RemovePartitionException(userGuid, SdkPrivilege.ModifyCameras);

Checking possible exception states

GetPrivilegeExceptionPossibleStates returns the states that can be assigned. Because PrivilegeAccess is a flags enumeration, test for the required state before creating the exception:

Partition partition = (Partition)engine.GetEntity(partitionGuid);
PrivilegeAccess possibleStates =
    partition.GetPrivilegeExceptionPossibleStates(
        userGuid,
        SdkPrivilege.ModifyCameras);

if ((possibleStates & PrivilegeAccess.Denied) != 0)
{
    partition.CreateOrUpdatePartitionException(
        userGuid,
        SdkPrivilege.ModifyCameras,
        PrivilegeAccess.Denied);
}

Restrictions

• Only Entity privileges can have partition exceptions. Task privileges cannot.
• When you set an exception on a parent privilege, child privileges are also affected.
• You cannot create exceptions for administrator users.
• You cannot manage your own partition exceptions.

Read-only configuration access

Grant a user read-only access to configuration in a partition:

var partition = (Partition)engine.GetEntity(partitionGuid);
partition.SetConfigurationPrivilegesPartitionExceptions(userGuid, isReadOnly: true);

Partition exceptions specify a user's privileges for entities in a particular partition. Calling this method with isReadOnly: true sets the configuration-viewing exceptions to Granted and the configuration-modification exceptions to Denied, allowing read-only configuration access.

Calling it with isReadOnly: false sets both sets of exceptions to Granted. This does not undo the previous call. For example, a modification exception that was Denied before the first call becomes Granted, rather than returning to Denied. To restore the previous configuration, record the exceptions before calling this method and restore them afterwards.

Getting partition exceptions

Retrieve the current partition exceptions for a user:

var partition = (Partition)engine.GetEntity(partitionGuid);
ReadOnlyCollection<PrivilegeInformation> exceptions = partition.GetPartitionExceptions(userGuid);

foreach (var exception in exceptions)
{
    Console.WriteLine($"{exception.PrivilegeGuid}: {exception.State}");
}

You can also retrieve exceptions from the user side:

var user = (User)engine.GetEntity(userGuid);
ReadOnlyCollection<PrivilegeInformation> exceptions = user.GetPartitionExceptions(partitionGuid);

System partitions

Security Center has built-in system partitions that cannot be deleted:

Partition	Description
Root partition	The default partition (Partition.DefaultPartitionGuid)
System partition	Public partition accessible by all users

Administrator bypass

Administrator users and members of the Administrators user group bypass all partition restrictions. They can see and modify all entities regardless of partition membership.

var user = (User)engine.GetEntity(userGuid);
if (user.IsAdministrator)
{
    // User has access to all partitions
}

Because administrators bypass partition restrictions, you cannot limit their access with partition exceptions. CreateOrUpdatePartitionException, RemovePartitionException, and SetConfigurationPrivilegesPartitionExceptions throw SdkException with SdkError.InvalidOperation and make no change when the target is an administrator or the logged-on user.

Creating partitions

Create a new partition using the Engine.CreateEntity() method:

var partition = (Partition)engine.CreateEntity("Sales Department", EntityType.Partition);

After creating the partition, add users and entities as needed:

partition.AddUserAccess(salesManagerGuid);
partition.AddMember(lobbyCamera);

See also

• About privileges: Privilege types, states, and per-user privilege computation.
• About entities: Entity model and IPartitionSupport.
• About the Platform SDK: SDK assemblies and the Engine class.