Configuring Virtual Identity Silos

Any users, groups, contacts, or other objects to be displayed in Service Panel must be configured as Virtual Identities. A virtual identity sits on top of Identity Panel data and comprehensively describes how it should be presented in Service Panel.

A virtual identity silo sits on top of the Identity Panel join graph. This means that attributes from any silo within Identity Panel may be displayed in Service Panel, as long as they can be reached by Identity Panel links or joins. As a matter of performant design, it is worthwhile to minimize how much of the join graph must be queried to render a virtual silo.

For example, a view which requires loading a single object, or two objects connected by a join rule will simply load faster than one which requires traversing a join rule, two provider links, and another join rule.

Initializing a Virtual Identity

Go to Settings -> Service Panel -> Virtual Identity

Press the New button to start a silo

A virtual silo must have a Name (which should be user friendly as it appears in the interface). The name may have the following characters: A-Za-z0-9 :- If a name is desired with other characters it should be applied through the Translations interface.

Each virtual identity must specify a Silo and Object Type. This identifies that root of the join graph that will be used to project attributes from the silo. Every object viewable in the virtual identity must be present in the Identity Panel silo/object type chosen as the parent.

IMPORTANT: Before you create a virtual identity silo in Service Panel you must have data populated in Identity Panel. Only silos, objects, and attributes that already exist and have data in Identity Panel may be used to create Service Panel virtual identity settings.

Virtual Identity Audiences

When you create a virtual identity, if you leave audiences undefined, all authenticated users will be able to view all objects in the virtual silo. Use Audience Rules to narrow the scope of virtual identity visibility.

Types of Audience

Audience rules may be added and associated to a rule. Once any rule is created, access is denied for all users who do not match an existing audience rule. Note that an audience may be role or reference based, but for virtual identity visibility, role based is far more common, with referenced based audiences typically reserved for attribute level permissions.

When using a Referenced based audience, the reference attribute MUST be defined on the Parent silo. For example, if the parent silo of an identity is Active Directory, only AD reference attributes may be used in audiences.

Filter Rules

A Filter Rule may be applied to an audience rule when it is desirable to hide some objects from users in the role. A common example is to have a People virtual identity which only shows active person user accounts to everyone, and shows service accounts and disabled accounts only to administrators. Another example is a group silo which only displays distribution lists to regular users.

The Filter Rule is applied to each ObjectRecord in the Parent Silo. If the parent Silo is AD, then only AD attributes may be considered by the filter rule. Filter rules are applied with the Rule Engine to each ObjectRecord in the silo and return a true of false value for whether that identity should be displayed.

Filter Rule Performance

Filter rules can have a negative impact on Service Panel performance, and there is additional configuration required to alleviate the issue. Because of this, Service Panel will first evaluate if a user is in an unfiltered audience.

Consider the problem of loading a search with wide criteria and many results: In order to display an accurate page count, the audience scope needs to be considered for all objects in the search, even those that are not currently paged in. If the audience is unfiltered, then it is enough simply to retrieve the count of ids in the search result. However, if the audience is filtered, the entire search result set must be loaded (although fortunately only the parent silo objects and not the full virtual identities), and the filter rule must be evaluated for all objects to determine the correct window for a paging slice.

Audience Properties

The Virtual Identity includes an extra setting called Audience Properties. If defined, audience properties can be used to only load the data actually used in a filter rule, which dramatically improves performance for large queries.

Audience Properties are defined as multi-value tags, and should be the Rule Engine path to each attribute or property required by ANY of the Filter Rules.

For very large organizations (25K users and up), it may be desirable to go a step further and create a database index that covers the audience properties. This will allow the filter rule queries to be satisfied from the index without reading the full collection objects from disk. This technique is even more beneficial when used on the Self Lookup Claim settings (see below).

Indexing Audience Properties

The first step to creating an audience index is to obtain an learn an interface for MongoDB and connect to your database. One such program is Robo3T, or you may use the mongo.exe shell.

1. Identify your Silo Id. This may be done by querying for the FieldMap object with a name matching the Parent Silo:
   

   

2. Identity the system attribute names that are required in the silo by querying the AttributeNameMap
   
3. Expand the indices of the ObjectRecord* collection corresponding to the Parent Silo. The collection name ends with the first 8 characters of the Silo ID Guid
   
4. Create a new index including the _id property, and each of the attributes. For the Attributes collection, the path is going to be a.attr name, so if the shortened attribute is "e3", the index will be { _id: 1, "a.e3": 1 }
   

 

Virtual Identity Self Lookup

In order to allow Reference based audiences (and also to display a My Identity view for a user), Service Panel needs a way to associate the currently logged in user to a record in a Virtual Identity. This is done through the Self-Lookup Claim settings.

The Self Lookup uses claim values from the user's authentication token to craft a database query which should return the single user in the Parent Silo corresponding to the logged in user.

The available claim values are Id and Name. For on premise installations these correspond to the user's binary objectSid, and their DOMAIN\sAMAccountName. For SaaS installations these correspond to the user's Azure AD Object Id Guid (in string form), and their Azure AD userPrincipalName.

In order to find the user, the value must be a perfect, case sensitive, type sensitive, match to the Self Attribute selected from the Parent Silo's database collection. The case sensitivity requirement is imposed by the MongoDB query engine.

It is common that the self-lookup claim does not perfectly match available attributes in the Parent Silo. For this reason, the Self Lookup Rule may be used to make transformations.

The Self Lookup Rule is applied to the CLAIM VALUE. This means the context is the value off of the user's authentication token. The rule should be used to transform the value to match what is in the Identity Panel database.

Some common examples are:

• Make binary sid into a string:
  ConvertSidToString(context)
• Make string guid into a Guid type:
  CoerceGuid(context)
• Take only the sAMAccountName portion of a Name:
  Last(Split(context, "\\")) or
  RegexMatch(Username(), "\\w+\\\\(.+)", 1, false)
• Take only the prefix of a UPN:
  First(Split(context, "@"))
• Make a sAMAccountName uppercase:
  UpperCase(Last(Split(context, "\\")))

 

Virtual Identity Search

Each Virtual identity defines a search scope so it can be used for white pages functionality. Although all virtual identities are searchable via the REST API:

/api/servicesearch?limit=10&skip=0&term=Example&scope=people&field=

It is NOT mandatory to bind a virtual identity's search scope into the user interface.

Default Search

Exactly ONE Virtual Identity should have the Default Search box selected (typically a users or people virtual silo). This will bind it to the page header search bar.

Searchable Data

Because Service Panel uses the same full text Elastic search index as Identity Panel, by default all attributes in the Parent Silo are searchable, even if they are not displayed on the user interface. This may be desirable behavior, e.g. if you want service desk users to be able to lookup accounts by employee id, but don't want to explicitly list it to all users as a searchable attribute.

There are a few reasons you may want to limit search scope to explicitly listed fields, which may be done with the Field Query Only checkbox.

These reasons may include:

1. The Parent Silo may have sensitive data, and making the full silo searchable may allow users to identify accounts with certain attribute values by guess. For example, a malicious user might use a wildcard progressive search strategy to work out the CEO's employee ID.
2. Search may return unexpected results and cause user confusion if they display based on terms that are not visible for the user. For example, if a Parent Silo has been populated with a person's manager's display name and other data, it may cause confusion when a search for a manager name also returns all their direct reports.

Search Attributes

The search attributes section is used to list attributes for search. If the Field Query Only box is selected, only attributes listed here will be searched. The Search Attributes also appear in the Field Query drop-down lists when Search Scopes are displayed on the Service Panel dashboard.

Search Attributes settings have two parts:

Attribute: the attribute name from the Parent Silo that consists of the searchable source data.

Name: the display name to present to the user.

NOTE: search attributes are independent from Virtual Identity attributes. You may have virtual identity attributes that are not searchable, and vice-versa, although from a usability standpoint it is not recommended to have search attributes which don't appear on the Virtual Identity Silo.

 

Displaying Virtual Identity Attributes

The core of a Virtual Identity is its display attributes. There are three main sections for attribute configuration. This allows separation of concerns between how attributes are generated and rendered, and how silo display views are organized.

1. The Display Attributes section governs the generation of actual attribute values, as well as decorators for things like form triggers, icons, URLs, etc.
2. The List Display section determines how objects will appear in lists, i.e. in Search Results and Reference Attribute tables.
3. The Grid Display section determines how objects will appear in thumbnails, card view, and full details view.

Display Attribute Settings

The first part of the display attribute settings identifies name, whether it is detail linked and the Sortable Attribute.

The attribute name is displayed as the label unless Translation has been applied to transform it into something else. Attribute names follow the same rules as silo names: (A-Za-z0-9 :-)

If the Detail Link box is selected, the attribute will be turned into a hyperlink to the Detail page for the object. This is a shortcut over using a URL rule to produce the link. Common attributes to detail link are the Display Name, and an identifier attribute like Account Name or Employee ID.

The Sortable Attribute must be defined for the attribute to be sortable in list views. The Sortable Attribute MUST come from the Parent Silo, so some attributes may be intrinsically unsortable.

The following are settings within the expanded attribute:

• Value Silo – Required, indicates which silo the Value Rule is applied to in order to generate a value
• Value Rule – Generates the primary value to display. This is NOT mandatory because it is often not required when working with multi-value attributes, and is IGNORED when working with reference attributes.
• Word Break All – Sets the CSS flag for word-break-all. This is useful with long character strings that don't have natural breaks and need to wrap anywhere in list views or short width grid views. For example, objectSids.
• Show If Null – Normally, null-valued attributes are hidden completely. Show If Null can be used to display the attribute with an empty value. This is useful if the attribute has decorators, e.g. to launch an edit Service Form.
• Tooltip Rule – Generate a value to display as a tooltip. Sometimes this may just be a copy of the Value Rule. If this rule is not defined or returns null then no tooltip will be displayed for the value.
• Multi-Attribute Name – This should be set for any multi-value attribute, as well as for single and multi-valued reference attributes. If a non-reference value is specified, the entire list of values will be processed by the Value Rule. This may be used to filter or shorten an attribute for display.
• Single-Valued Reference – Should be ticked for any reference attribute that is intrinsically single-valued (e.g. manager). This is required because the underlying system does not distinguish between single-valued and multi-valued reference attributes.
• References Page Size – The number of rows or thumbnails to display per page when viewing a mult-valued reference attribute. If left blank, defaults to 5.
• Reverse Reference – Use this to indicate that a reference attribute should be traced backwards (e.g. manager of, member of)
• Audiences – if the attribute should have a NARROWER scope than the Virtual Identity as a whole, specify audiences that may view the attribute. If any audience is defined, all users outside the audience will be denied. If a user is not in the audience they can still see the object but the attribute will not be rendered. This applies even when Show If Null is set. Audience rules hide the attribute from display, API, and identity rendering for Service Forms.
• Detail Decorators – see next section

NOTE: Multi-value attributes may use any silo in the join graph by selecting the Value Silo. Although reference attributes can be defined to use any value silo, they the objects they reference MUST be a parent silo. For example, if the parent silo is AD, a user can display a Member Of attribute from an Azure AD silo, however, the referenced groups must be defined with an Azure AD Parent silo. This means it may be necessary to define a separate copy of a virtual identity for the sole purpose of displaying references.

 

Detail Decorators

Detail decorators are one of the most powerful tools for configuration of a virtual identity attribute. The can be used to add thumbnail photos and icons, replace values and turn either the decorators or the attributes themselves into hyperlinks.

Detail decorators are scoped by Slot and View Mode. Within a given view mode, there can be at MOST one decorator per slot.

The slots are:

Before – places the decorator before the attribute value

Replace – Replaces or transforms the attribute value: for example, an icon or photo decorator will remove the attribute value and display the decorator instead. A URL decorator will turn the value into a hyperlink. Note that Replace decorators generally won't work with multi-value and reference attributes.

After – places the decorator after the attribute value

The view modes are: All, List View, Business Card View, Detail View, and Thumbnail View

A detail decorator can have the following settings:

• Audiences – It is commonly useful to apply a NARROWER audience rule to a decorator than to a parent attribute. For example, an icon to launch an edit form which is only seen by some roles
• Photo Silo – The Identity Panel silo to use for extracting a value with a Photo rule. If Photo Silo is blank, the Parent Silo for the Virtual Identity will be used, NOT the silo of the display attribute.
• Photo Rule – Generates a photo URL. The value should be appropriate for placing in the src attribute of an <img> tag. Generally this means it should generate an absolute URL to an image servable to the user's browser. Alternatively, it may generate a data-encoded image string. This can be aided by the Base64Image Rule Engine function. For example, Base64Image(Attributes.thumbnailPhoto) will produce something like this: "data:image/jpeg;base64,<data>"
• Icon Silo – See Photo Silo
• Icon Rule – Generates the name of a material design icon to display. If the slot is Replace, the icon will replace the value and the value will be made a tooltip on the icon. If both a photo rule and an icon rule are defined, the icon will only be displayed if the photo rule did not return a value. This is useful for falling back from e.g. someone's thumbnail photo to a generic icon.
• URL Silo – See Photo Silo
• URL Target – Blank (opens in new window), Self (default behavior, normal navigation), Top (Same behavior as self unless the page is embedded in a frame)
• URL Rule – Generates a hyperlink for the decorator. In Replace slot, it turns the whole value into a hyperlink. Otherwise it must be used in conjunction with a Label, Photo, or Icon rule.
• Label Silo – See Photo Silo
• Label Rule – Generates a label value, which may be used in conjunction with a URL. If combined with a Photo or Icon rule it will provide the alt or title text for the decorator. In Replace mode, it will substitute for the value of the attribute. This may be desirable for localized translation purposes. Attribute values are NOT directly localizable. However, Label Rules appear in the Translations matrix and so may be customized per language.

The most common decorator type after simple icon display is to apply action URLs to link to forms or other objects. Following are some common sample rule types for generating a URL.

• Linking to a form – Instead of having to look up the guid corresponding to the form and generating a raw URL like this ("/form/aaa207fa-32da-48fd-85cf-7f5fa8657e95#!identity=" + Id), use the ServiceForm method with the form's name and object ID to be bound: ServiceForm("EditUser", Id)
• Linking to object details – ServiceDetail(Id)

 

List Display Settings

The list display section is simple, with relatively few options. It's consists of merely a list of attributes in display order, as well as a flag indicating whether the attribute should be made sortable in views.

NOTE: If the attribute is made sortable, you MUST have specified a Sortable Attribute value on the Display Attribute.

Grid Display Settings

Grid display mode controls three separate views:

Thumbnail, ID Card, and Details. These should be configured to reveal progressively more data. Part of a sample ID Card view is pictured here:

Thumbnails are displayed for single-valued reference attributes. ID Cards are displayed as an expander on search results, and on the My Identity dashboard module. Details should be considered the complete view of an object (except for un-displayed attributes).

IMPORTANT: It is possible to define attributes in Display Details which are NEVER assigned to a list display or a grid display section. One reason to do this is to render information and make it available to Service Forms/workflows even when it is never viewed by an end user. However, for performance reasons, Service Panel will only load underlying data silos if they are displayed. This means that if an un-displayed attribute, either directly, or via decorators, pulls data off of a joined Identity Panel data silo that does NOT have any displayed attributes associated with it, then that attribute will NOT be rendered and made available in the Rule Engine.

A Grid Section has an optional Section Name, as well as checkboxes indicating which views it will be rendered on. If a section name is defined, it will be rendered with a header label.

Any display attribute may be assigned to an multiple sections, and an attribute may even appear more than once in a single section (although there are few cases where this would be advisable). It is also possible to assign multiple sections to a single view. For this reason, the easiest way to keep grid sections straight and design your different views is to follow the rule of only assigning a single view to each section, even if this means that some attributes are allocated multiple times.

When a grid section is expanded a number of child settings are available:

• Beginning Divider – If checked, a horizontal rule will be drawn between the Section header (if present) and the attribute listing
• End Divider – If checked, a horizontal rule will be drawn at the end of the section
• Columns – If checked, the attribute grid settings will be completely disregarded and instead the section will be drawn in a column view mode with attribute names on the left and values on the right.
• Font Scale – Allows increasing or decreasing the font-size within a section. It expresses a CSS scaling factor in ems, so e.g. 1.2 will increase effective font-size from 14px to ~17px. Font scaling does not apply to section name headers.
• Attributes – The list of attributes to display within the section.

Grid Attribute Settings

• Name – The name of the Display Attribute to render
• Size – The width of the attribute in the grid (ignored in column mode). This ranges from 2 to 12 following a standard CSS grid model. NOTE: the grid refers to the available space. For example, you may have a manager attribute displayed with a grid-width of 6. The thumbnail within it may have a display name attribute with a grid-width of 12. This means that the display name will take the full width of the thumbnail, which itself will only be at half-width. Due to commonly being in a nested display, it is recommended that Thumbnail view attributes always be rendered at full width (12).
• Grid Label – Whether to display the attribute name as a label in grid display mode
• Text Justification – If specified, align the attribute to the left, right, or center within the available grid space
• Business Card View, Thumbnail View, Detail View – Use these flags to HIDE the attribute within a grid section where it would otherwise be visible. For example, the section may be visible on both thumbnail and ID card, but a particular attribute may be configured to only show on the ID card view. Selecting to show the attribute will NOT make it visible if the whole section is hidden.