Skip to content

Roles

Roles in Zervicepoint help with the following:

  • Grant access to Service/Page by Role
  • Filter data from Data sources by Role
  • Grant role-based access control to admin web components and your services.

How do roles work?

Roles are set at login, they are set based of the role rules and direct memberships.

The issuer (ADFS/AzureAD) pass along "claims" in a token, those claims that can be sourced from different attributes in an AD or Azure AD environment, can be used to setup different types of rules.

A common role rule is to check if the user is member of a specific security group, and if true, it should add that role to the user session.

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

It's also possible to link an email address as a direct membership of that role, then a user that logs in with a email claim matches the direct membership, will gain access.

Note

Roles are often setup with rules that point to groups and then access to zervicepoint is managed based on the membership of those groups.

Role Administration

Roles are managed either through the Admin Web or ZP API

Roles are created in the Roles tab in Admin Web.

To grant access to a Service/Page, click the Visible for roles field and search for the role.

Important

Services/Pages are listed for everyone unless a role is specified.

Visible for role

How to create a role

Click Add new role when in the Roles tab in Admin Web.

AddRole

Add Rules

Tip

If you want any users that are logged on to be member of a specific role, create a rule that returns true return true;

Add users to a role

You should add users to a role by updating the source attribute from where the claim is sourced from, such as updating the group membership of a group in Active Directory.

Direct membership are generally used for development or test purposes, it's not a method you should use to grant access to several users to access a service.

    return Group.Contains('TEST_Access') || Group.Contains('ops-TEST-LocalIT')
    // Members of AD-group TEST_Access or ops-TEST-LocalIT gets this role.

Roles and Data sources

The list of roles a user is assigned to during a session, is passed as a parameter to the data source if the parameter $config exists. Read Data sources - access control for more details.

Most of our Zervicepoint plugins, includes a dropdown.xml file which is used to manage delegation or to create multiple data sources based on the same shared data source.

For the Active Directory plugin the folder structure is the following and contains powershell modules.

..\Provider Extensions\Active Directory\Activities
..\Provider Extensions\Active Directory\Activities\Activity.ActiveDirectory
..\Provider Extensions\Active Directory\Data sources
..\Provider Extensions\Active Directory\Data sources\DropDown.ADComputer
..\Provider Extensions\Active Directory\Data sources\DropDown.ADComputerNoDefault
..\Provider Extensions\Active Directory\Data sources\ # ... and more
..\Provider Extensions\Active Directory\Shared modules\
..\Provider Extensions\Active Directory\Shared modules\ActiveDirectory
..\Provider Extensions\Active Directory\Shared modules\DropDown.ADComputer
..\Provider Extensions\Active Directory\Shared modules\DropDown.ADGroup
..\Provider Extensions\Active Directory\Shared modules\ # ... and more

When the data source DropDown.ADComputerNoDefault is loaded, it will import the module based on the module manifest.

Click to show powershell manifest (DropDown.ADMyComputerNoDefault.psd1) 
@{
    ModuleVersion = '1.1.1.0'
    GUID = 'd5227a9f-d54f-45fc-9832-0a76dd1e1c99'
    Author = 'ZervicePoint Extension Team'
    CompanyName = 'Enfo Zipper'
    Copyright = '(c) 2014 Enfo Zipper. All rights reserved.'
    Description = 'Displays a users computer objects in Active Directory.'
    PowerShellVersion = '3.0'
    NestedModules = @("$env:ZPPackages\Active Directory\Shared modules\DropDown.ADComputer\DropDown.ADComputer.psd1", 'DropDown.ADMyComputerNoDefault.psm1', 'PowerFrame.Utility')
    FunctionsToExport = 'Search', 'Validate', 'GetCategories'
    FileList = @(
        'DropDown.ADMyComputerNoDefault.psd1',
        'DropDown.ADMyComputerNoDefault.psm1',
        'dropdown.xml'
    )
}

The manifest includes NestedModules and imports the module DropDown.ADComputer.psd1 which is located in the Shared modules path.

Click to show powershell manifest (DropDown.ADComputer.psd1) 
@{
    RootModule = 'DropDown.ADComputer.psm1'
    ModuleVersion = '1.1.1.0'
    GUID = '2c79a538-2d4e-423d-8c25-28938f0ba93b'
    Author = 'ZervicePoint Extension Team'
    CompanyName = 'Enfo Zipper'
    Copyright = '(c) 2014 Enfo Zipper. All rights reserved.'
    Description = 'Drop Down Datasource that returns Computer Objects.'
    PowerShellVersion = '3.0'
    ModuleList = @('DropDown.ADComputer.psm1')
    FileList = @(
        'DropDown.ADComputer.psm1',
        'DropDown.ADComputer.psd1'
    )
}

The Shared module contains the actual code for Search, Validate, GetCategories and GetDefault. You can learn more about those concepts here

In the our code for the Active Directory plugin, there is code as well to evaluate a $dropdown object if it exists. This object gets loaded when the DropDown.ADMyComputerNoDefault module is run, it runs the command Get-PFDropDownConfiguraiton -Path $PSScriptRoot which will import the dropdown.xml file in the same location.

The dropdown.xml contains a number of parameter elements ("LDAPFilter, SearchBase, DomainController") which can be used to create a filters from the Search function in the Shared module DropDown.ADComputer.

<?xml version="1.0" encoding="utf-8"?>
<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

Name Description
ApiStoreAdministrator ApiStoreAdministrator
ArticleAdmin Can add/edit/remove News, Info blocks and Slides.
OrderAdmin Can view and restart/terminate orders in store.
PageAdmin Can view pages. Can add/edit/remove pages and change order on pages.
ProcessAdmin Can view Processes. Can edit Processes. Can view both Shared and Custom services. Can edit both Shared and Custom services. Can view Providers and Data sources.
RoleAdmin Can view roles. Can add/edit roles.
ServiceAdmin Can view only Shared services. Can edit only Shared services.
ServiceReviewer Can view and order draft versions of services in userweb
StoreAdministrator Can do everything on a Store level.
TagAdmin Can add/edit/remove Tags.
TranslationAdmin Can view store translations and languages. Can edit store translations and languages.