Permissions

Permissions are custom Entitlements for PowerShell target systems and PowerShell v2 target systems. Their most common use case is to add target user accounts to groups, akin to Group Membership entitlements in Active Directory target systems and Azure AD target systems. However, permissions can execute any PowerShell code in the target system. Thus, adding target user accounts to groups is only one possible use case. After you have created a permission, you assign it via Business rules like any other entitlement.

To get started, Add a permission set.

A permission set is represented by a tile on the system's Permissions tab:

Each permission set comprises three things:

One or more Standard permissions
Grant, update, and revoke PowerShell code for each standard permission (see Permission actions)
Sub-permissions (also known as dynamic permissions) for each standard permission

Typically, you should create a separate permission set for each general type or theme of permission. For example, one set for group memberships, one set for project folder access, and one set for email accounts. Although you can include as many standard permissions as you want in a single permission set, each permission set shares the same grant/update/revoke PowerShell code. Creating multiple permission sets prevents each set's PowerShell code from becoming too complex.

Tip

The key difference between Permissions and Resources is that HelloID tracks the state of permissions by treating them as Entitlements, whereas it does not track the state of resources. To verify if a resource exists, you simply query the external system in your PowerShell code. This also means that there is no special way to "revoke" resources, beyond what you manually script.

Standard permissions

Each permission set can contain one or more standard permissions. Each standard permission should correspond to a single, atomic user privilege in a target system. For example, group membership based on Departments.

Each standard permission in a permission set becomes assignable as its own Permission-type entitlement in Business rules.

You can define standard permissions manually or programmatically:

Use manual definitions (Use Script To Retrieve Permissions disabled) if you are creating a small (~<10), fixed number of standard permissions which you know in advance.
Use programmatic definitions via PowerShell (Use Script To Retrieve Permissions enabled) if you are creating a large number (~>10) of standard permissions, or if you don't know them in advance. See Retrieve permissions script.

Permission actions

Each standard permission requires a Grant action, a Revoke action, and an Update action. You write these action scripts in PowerShell, and HelloID executes them during the corresponding stage of Enforcement.

You can define these three actions in a single script, or in separate scripts. The choice mainly depends on whether you are using Sub-permissions:

Typically, you should use separate scripts (Use Separate Script For Each Action enabled) if you are not using sub-permissions. See Separate permission scripts.
Typically, you should use a single script (Use Separate Script For Each Action disabled) if you are using sub-permissions. See Single permission script and Sub-permissions.

In all scripts (single scripts as well as separate scripts), HelloID passes you a variety of input variables and expects you to send results back at the end. The details of these inputs/outputs depend on whether you're using a PowerShell v1 or v2 system. See PowerShell target system variable reference or PowerShell v2 target system variable reference, respectively.

Note

If necessary, you can reverse this recommendation and use separate scripts with sub-permissions, or a single script without sub-permissions. If you do this, the script templates will require additional customization beyond the scope of this documentation.

Sub-permissions

Each standard permission can optionally contain up to 100 sub-permissions, which are also known as dynamic permissions. They are dynamic because the specific sub-permission can change while the Person remains in scope of the same business rule, granted the same permission entitlement.

The most common use case for sub-permissions is to dynamically select target group memberships based on a person's in-conditions Contracts data (see $contract.Context.InConditions (PowerShell v1) or $personContext.Person.Contracts[x].Context.InConditions (PowerShell v2)). However, sub-permissions can also respond to changes in out-of-conditions contracts data, as well as other data in Persons objects.

For example, suppose you need to assign target group memberships in a PowerShell target system, based on the department listed in their primary contract. Suppose your organization has 20 departments.

Using standard permissions, you would need to create 20 separate Business rules each with its own standard permission and Conditions. When a person's department changes, they would exit the scope of one business rule and enter another, causing one standard permission to be revoked and another to be granted.
Using sub-permissions, you can accomplish the same thing using a single standard permission within a single business rule. You would write PowerShell code that selects the relevant sub-permission based on the person's primary contract's $contract.Department.ExternalId value. Then, when a person's department changes and an Enforcement runs, the permission's update code is triggered, causing sub-permissions to be dynamically re-evaluated. The person remains in scope of the same business rule and standard permission. The only change is the selection of the specific sub-permission.

In this way, sub-permissions can drastically reduce the number of business rules and permissions required in your environment.

HelloID re-evaluates sub-permissions during the Update step of Enforcement, as well as during Force update permissions.

Caution

If you're using sub-permissions, you should typically create only one standard permission per permission set. A permission set with multiple standard permissions, each with multiple sub-permissions, will make your PowerShell code overly complex.

In this section: