Synchronizing Security Information from PI

Administrators can configure PI Connector to synchronize security related information from PI into Seeq.

Security related information consists of PI point security strings (data security and point security), PI identities and mappings of PI Identities to Active Directory accounts.

Note that even if both: data security and point security information is sent to Seeq, an AND between the two information pieces is made so that in order to get read access in Seeq for a signal, it must have in PI read+read_data permissions.

PI Security synchronization requires PI AF Client 2014+ (AFSDK 2.6+). The error SQ-1500 will be generated if this is not the case.

Overview

PI Connector may be configured to synchronize point security and PI Identities with Seeq.

A typical Additional Properties configuration looks like the following. The SecuritySynchronization section contains the security related information.

CODE

{
      "PIServerID": "c29fb683-86c9-4a74-b0af-95b6b9f528fb",
      "Username": null,
      "Password": null, 
      "Transforms": null,
      "SecuritySynchronization": {
        "Identities": true,
        "PointSecurity": true,
        "IdentityMappingsDatasourceClass": "LDAP",
        "IdentityMappingsDatasourceId": "7f4d9fb7-6b05-47c8-b8dd-7bec439810ad",
        "IdentityMappingsStopRegex": "^(BUILTIN\\\\.*)$",
        "PIWorldMapping": "Auth/Seeq/Everyone"
      }
}

Prerequisites

In order for Seeq to recognize the PI Identity mappings, the account running Seeq will need read access to the mappings and identities of the PI Data Archive. To determine whether this is the case or not, go to PI System Management Tools and connect to the PI server in question. Go to the System Management Tools menu and navigate the the pathway Security >> Database Security. In this page there are two tables, PIMAPPING and PIUSER. These tables dictate which identities have access to the mappings and PI identities. If the identity mapped to the Seeq account is not shown in the Security for both of these tables, double clicking the field allows you to add additional identities.

Configuration

The SecuritySynchronization section contains the following fields:

Config Key	Optional?	Notes
Identities	Required	Whether the PI Identities will be synchronized with Seeq. Possible values: true or false (no quotes!). When true, PI Identities and optionally (see IdentityMappingsDatasourceId key below) mappings with Active Directory groups are synchronized to Seeq before the incremental or full update of signals starts.
PointSecurity	Required	Whether the security strings for PI Points are sent to Seeq during full or incremental indexing of signals. Possible values: true or false (no quotes!). When true, datasecurity and pointsecurity for PIPoints will be sent to Seeq. Note: The fields "Security String" and "Source Security String" may also be transformed using Property Transforms. This makes sense for installations where PI Identities are not synchronized to Seeq and PI Point security will be defined using existing Seeq user groups.
IdentityMappingsDatasourceClass	Required	The class of the datasource that provides Active Directory groups. Possible values: "Windows Auth", "LDAP", "OAuth 2.0". Default value: "Windows Auth". OAuth 2.0 is supported only when the folowing conditions are all true: the identity provider is Azure, IdentitySynchronizationType is set to AZURE (default) in the configuration file the Azure groups have an attribute named `onPremisesSecurityIdentifier` set to the SID of the group in the on prem AD (this is usually true if the Azure identities are joined with the onPrem Identities from AD - see https://docs.microsoft.com/en-us/azure/active-directory-domain-services/synchronization for more information).
IdentityMappingsDatasourceId	Optional	When provided, it must be the ID of the LDAP / "Windows Auth" / "OAuth 2.0" datasource that provides the Active Directory groups that PI Identities are mapped with. The ID may be taken from `LDAP Connector.json` , `Windows Auth Connector.json` or from `OAuth 2.0 Connector.json` from the attribute named "Id". When null, PI Connector will not send / manage the mappings of PI Identities with AD groups. This may be useful in configurations where Active Directory is not used and Seeq users will be added to the PI groups manually in Seeq. Please note that this is not the usual configuration. When IdentityMappingsDatasourceClass and IdentityMappingsDatasourceId are provided, the corresponding authentication connector has to be configured to synchronize the relevant groups into Seeq. See Identity Synchronization using Windows Authentication Connector or LDAP (Active Directory) Authentication Connector
IdentityMappingsStopRegex	Required	Regex used to prevent some PI identity mappings from being sent to Seeq. Default value: "^(BUILTIN\\\\.)$" If for example we don't want BUILTIN users / groups and the user / groups starting with word ”AMAZONA” to be sent, the regex will be set to "^(BUILTIN\\\\.\|AMAZONA.*)$"
PIWorldMapping	Optional	Used when PIWorld PI Identity is not wanted as a group in Seeq and it is intended to use Auth/Seeq/Everyone group (or any other group) instead. Usual value: "Auth/Seeq/Everyone". When not null, PIWorld identity will not be sent to Seeq In PI Point security strings, piworld identity will be replaced with the string specified here

Special considerations

Handling of disabled PI Identities

Disabled PI Identities are sent to Seeq as disabled.

Handling of disabled Identity Mappings

Disabled identity mappings from PI will not be sent to Seeq. Seeq will behave as if the mapping would not exist.

Examples

Example 1

Synchronize PIPOINT security, Identities and mappings and map PIWorld to Everyone group in Seeq:

CODE

{
      "PIServerID": "c29fb683-86c9-4a74-b0af-95b6b9f528fb",
      "SecuritySynchronization": {
        "Identities": true,
        "PointSecurity": true,
        "IdentityMappingsDatasourceClass": "LDAP",
        "IdentityMappingsDatasourceId": "REPLACE WITH YOUR ENABLED LDAP DATASOURCE ID",
        "IdentityMappingsStopRegex": "^(BUILTIN\\\\.*)$",
        "PIWorldMapping": "Auth/Seeq/Everyone"
      }
}

Note: Do not use PIWorldMapping if PIWorld is disabled on the PI server. See troubleshooting section for more information on this issue.

Example 2

Synchronize PIPOINT security, Identities and mappings and treat PIWorld identity as any other identity in Seeq:

CODE

{
      "PIServerID": "c29fb683-86c9-4a74-b0af-95b6b9f528fb",
      "SecuritySynchronization": {
        "Identities": true,
        "PointSecurity": true,
        "IdentityMappingsDatasourceClass": "LDAP",
        "IdentityMappingsDatasourceId": "REPLACE WITH YOUR ENABLED LDAP DATASOURCE ID",
        "IdentityMappingsStopRegex": "^(BUILTIN\\\\.*)$",
        "PIWorldMapping": null
      }
}

Note: PIWorldMapping was set to null in this case

Example 3

Synchronize only PIPOINT security and map the pi identities to already existing Seeq groups:

Assumptions:

In PI we have two identities: piadmins and pieng.
In Seeq we already have two groups: SeeqAdministrators and SeeqEng.
We don't want PI Connector to create any identities in Seeq. Instead just map to already existing identities (piadmins → SeeqAdministrators, pieng → SeeqEng) and use those already existing identities for setting the permissions of signals.

The configuration will look like:

CODE

{
      "PIServerID": "c29fb683-86c9-4a74-b0af-95b6b9f528fb",
      "Transforms": [
        {
          "Inputs": [
            {
              "Property": "Security String",
              "Value": "(?<beforeId>.*)piadmins:(?<afterId>.*)"
            }
          ],
          "Outputs": [
            {
              "Property": "Security String",
              "Value": "${beforeId}Auth/Seeq/SeeqAdministrators:${afterId}",
              "UnitOfMeasure": null
            }
          ],
          "Enabled": true,
          "Log": false
        },
        {
          "Inputs": [
            {
              "Property": "Security String",
              "Value": "(?<beforeId>.*)pieng:(?<afterId>.*)"
            }
          ],
          "Outputs": [
            {
              "Property": "Security String",
              "Value": "${beforeId}Auth/Seeq/SeeqEng:${afterId}",
              "UnitOfMeasure": null
            }
          ],
          "Enabled": true,
          "Log": false
        }
      ],
      "SecuritySynchronization": {
        "Identities": false,
        "PointSecurity": true,
        "IdentityMappingsDatasourceClass": "LDAP",
        "IdentityMappingsDatasourceId" : null,
        "IdentityMappingsStopRegex": "^(BUILTIN\\\\.*)$",
        "PIWorldMapping": null
      }
}

We can see in this configuration that signal transforms are set to change the "Security String" from PI Identities to already existing Seeq groups and Security Synchronization is configured to not send identities to Seeq.

Note: Because we rely on existing Seeq identities, in "SecuritySynchronization" we've set Identities = false, IdentityMappingsDatasourceId = null and PIWorldMapping = null.

Troubleshooting PI Security in Seeq

All users are seeing all the tags even if PIWorld is disabled. This can happen if PIWorldMapping is enabled (is set to Auth/Seeq/Everyone) and PIWorld is disabled in PI. Even if PIWorld is disabled the security string still contains PIWorld. If PIWorld is mapped to Everyone in Seeq then Everyone will be able to see all the tags.

Rollback security

If you want to roll back security you will need to set PointSecurity to false and most likely won't need to synchronize Identities so you can set it to false as well. Once that’s done you will need to revert the security settings for all signals with this two-step process of setting datasource permissions using transforms.

Step one: Set the security string to empty to remove all permissions added by PI

CODE

[
    {
        "Inputs": [
            {
                "Property": "Name",
                "Value": ".*"
            }
        ],
        "Outputs": [
            {
                "Property": "Security String",
                "Value": "",
                "UnitOfMeasure": null
            }
        ],
        "Enabled": true,
        "Log": false
    }
]

Once this is saved the datasource will index, let it finish and then proceed to the next step.

Step two: Set the security string to inherit permissions from the datasource

CODE

[
    {
        "Inputs": [
            {
                "Property": "Name",
                "Value": ".*"
            }
        ],
        "Outputs": [
            {
                "Property": "Security String",
                "Value": "inherit",
                "UnitOfMeasure": null
            }
        ],
        "Enabled": true,
        "Log": false
    }
]

Save it and let it index. Once the index is done you can remove the transform and the security settings will persist.