Skip to content

Roles

Roles in Zervicepoint control access, visibility, and data filtering across the platform. They allow administrators to manage permissions efficiently and maintain a secure, role-based experience for users.

Overview

Roles in Zervicepoint are used to:

  • Grant access to Services and Pages
  • Filter data from Data sources
  • Control permissions for admin web components and services (RBAC)

How Roles Work

Roles are determined at login, based on: - Role rules, and
- Direct memberships

The authentication provider (ADFS/Azure AD) sends claims in the login token. These claims can come from AD or Azure AD attributes and are used to match configured role rules.

For example, to add a role when a user belongs to a specific AD group:

return user.hasClaim('Group', 'MyGroupName');

You can also assign a user directly via email membership. When a user logs in with an email that matches a direct membership, that role is granted.

Note

Most roles are configured through group-based rules, so access is automatically managed via Active Directory group membership.

Role Administration

Roles can be managed either in the Admin Web or through the ZP API.

Create and Manage Roles

  1. Navigate to Admin Web → Roles tab
  2. Click Add new role
  3. Configure role rules and memberships

AddRole Add Rules

Tip

To make a role apply to all logged-in users, use this rule: return true;

Grant Access by Role

To restrict a Service or Page to specific roles: - Open the item in Admin Web
- Set the Visible for roles field
- Search for and select the appropriate role(s)

Visible for role

Important

By default, all Services and Pages are visible to everyone unless roles are specified.

Adding Users to a Role

Ideally, you should add users by updating the source attribute (e.g., AD group membership) rather than manually adding users.

Direct memberships are mainly for testing or development purposes, not for managing production access.

Example rule using multiple AD groups:

return user.hasClaim('Group', 'TEST_Access') || user.hasClaim('Group', 'ops-TEST-LocalIT');
// Members of TEST_Access or ops-TEST-LocalIT get this role

Warning

The method .Contains() was deprecated in Zervicepoint 1.9.
Replace it with .hasClaim() or .claimIncludes() to ensure correct behavior.

Roles and Data Sources

When a user session is established, the list of assigned roles is passed to data sources as a parameter — if the data source includes the parameter $config.

For details, see: Data sources – Access control.

Many Zervicepoint plugins use a dropdown.xml file to configure data source delegation and structure.

Example (Active Directory plugin folder layout):

..\Provider Extensions\Active Directory\Activities
..\Provider Extensions\Active Directory\Data sources\DropDown.ADComputer
..\Provider Extensions\Active Directory\Shared modules\DropDown.ADComputer

When the data source DropDown.ADComputerNoDefault loads, it imports the corresponding module manifest.

Example: DropDown.ADMyComputerNoDefault.psd1 
@{
    ModuleVersion = '1.1.1.0'
    Author = 'ZervicePoint Extension Team'
    Description = 'Displays a user’s computer objects in Active Directory.'
    NestedModules = @("$env:ZPPackages\Active Directory\Shared modules\DropDown.ADComputer\DropDown.ADComputer.psd1", 'DropDown.ADMyComputerNoDefault.psm1', 'PowerFrame.Utility')
    FunctionsToExport = 'Search', 'Validate', 'GetCategories'
}
Example: DropDown.ADComputer.psd1 
@{
    RootModule = 'DropDown.ADComputer.psm1'
    Description = 'Drop Down Data source returning Computer Objects.'
    ModuleList = @('DropDown.ADComputer.psm1')
}

The Shared module contains core functions such as: - Search - Validate - GetCategories - GetDefault

These functions are described further in Data source tutorials.

When the dropdown module runs, it imports its configuration file (dropdown.xml) via:

Get-PFDropDownConfiguration -Path $PSScriptRoot

Example configuration:

<dropdowns>
  <dropdown>
    <parameter name="LDAPFilter">
      <add key="MyRole" value="(&amp;(objectCategory=computer)(name=$search*)(managedby=$currentUser.DistinguishedName))"/>
    </parameter>
    <parameter name="SearchBase">
      <add key="MyRole" value="$config.SearchBase"/>
    </parameter>
    <parameter name="DomainController">
      <add key="MyRole" value="$config.DomainController"/>
    </parameter>
  </dropdown>
</dropdowns>

System Roles

Role Name Description
ApiStoreAdministrator Full API store access
ArticleAdmin Manage News, Info blocks, and Slides
OrderAdmin View, restart, or terminate orders
PageAdmin Manage and reorder Pages
ProcessAdmin Full access to Processes, Services, Providers, and Data sources
RoleAdmin Manage and edit Roles
ServiceAdmin Edit only Shared Services
ServiceReviewer View and order draft versions of services in user web
StoreAdministrator Full Store-level access
TagAdmin Manage Tags
TranslationAdmin View and edit store translations and languages