Synchronizing Security Information from AF

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

Security related information consists of

AF identities and mappings of AF Identities to Active Directory accounts
security strings for assets (AF Elements)
security information on calculations
PIPoint security for AF attributes that map directly to PIPoints

AF Security synchronization requires PI AF Client 2017+ (AFSDK 2.9+)

Overview

Starting with Seeq Server version R54, connector configuration JSON files do not need to be updated manually on the machine running the agent and can instead be managed through the administration page. In the datasources tab, select the datasource of interest and click “Manage” for the associated connection card.

AF Connector may be configured to synchronize security strings and AF Identities with Seeq.

A typical configuration for AF Additional Properties looks like the following. The PISecuritySynchronization and AFSecuritySynchronization sections contain the security related configuration.

CODE

{
      "IgnoreHiddenAttributes": false,
      "IgnoreExcludedAttributes": false,
      "AFServerID": "6d77cda6-254d-4274-8378-38a4a025b3c7",
      "Username": "replace me",
      "Password": "replace me",
      "Databases": [],
      "AdditionalProperties": null,
      "PISecuritySynchronization": {
        "PointSecurity": true,
        "PIWorldMapping": "Auth/Seeq/Everyone"
      },
      "AFSecuritySynchronization": {
        "IdentityMappingsDatasourceClass": "LDAP",
        "IdentityMappingsStopRegex": "^(BUILTIN\\\\.*)$",
        "Identities": true,
        "ElementsSecurity": true,
        "IdentityMappingsDatasourceId": "8239af30-222b-4902-b680-cb0fbf566be5",
        "WorldMapping": "Auth/Seeq/Everyone"
      }
    }
}

Setting PISecuritySynchronization > PointSecurity to true enables the sending of PIPoint security for AF attributes that map directly to PIPoints. The security strings for such AF attributes will reference identities from PI and therefore it is important to enable PI Connector to send PI Identities to Seeq too. Also it is important that PISecuritySynchronization > PIWorldMapping is configured to the same value as the one configured in PI Connector.

AFSecuritySynchronization > Identities controls sending of AF Identities to Seeq. AFSecuritySynchronization > ElementsSecurity controls sending of security information fro AF Elements (assets). Usually when ElementsSecurity is enabled Identities sending is also enabled.

IdentityMappingsDatasourceClass and IdentityMappingsDatasourceId identifies the datasource of the connector storing the Active Directory users and groups and are important to be set when AF Identities - Active Directory Groups mappings are required to be sent to Seeq. IdentityMappingsStopRegex may be used to stop sending some of the Active Directory groups to Seeq (by default the one starting with BUILTIN\).

Configuration

The PISecuritySynchronization section contains the following fields:

Config key

Optional?

Notes

PointSecurity

Required

Whether the security strings for referenced PI Points are sent to Seeq during full or incremental indexing of attributes referencing PI signals.

When true, datasecurity and pointsecurity for PIPoints will be sent to Seeq.

Note 1: The PI identities referenced in the security strings must be already synchronized using PI Connector.

Note 2: 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.

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,

In PI Point security strings, PIWorld identity will be replaced with the string specified here
it is recommended that in PI Connector configuration PIWorldMapping is configured to the same value

The AFSecuritySynchronization section contains the following fields:

Config key	Optional?	Notes
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 AF 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 AF Identities with AD groups. This may be useful in configurations where Active Directory is not used and Seeq users will be added to the AF 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 or OpenID Connect
IdentityMappingsStopRegex	Required	Regex used to prevent some AF 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.*)$"`
Identities	Required	Whether the AF Identities will be synchronized with Seeq. Possible values: true or false (no quotes!). When true, AF 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.
ElementsSecurity	Required	Whether the security strings for AF Elements are sent to Seeq during full or incremental indexing of signals. When true, security for AF Elements will be sent to Seeq. For AF Attributes not directly referencing PI Points from PI (e.g. for analysis attributes, for formula attributes) AF Connector will not send any security strings, corresponding Seeq signals inheriting the permissions from the parent asset. Note: The fields "Security String" and "Source Security Sting" may also be transformed using Property Transforms. This makes sense for installations where AF Identities are not synchronized to Seeq and AF Elements security will be defined using existing Seeq user groups.
WorldMapping	Optional	Used when `World` AF 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, in AF Elements security strings, `World` identity will be replaced with the string specified here.

Special considerations

Considerations on PI Identity synchronization

PointSecurity implies that referenced PI identities are either already synchronized using PI Connector or transforms are used to map pi identities to Seeq identities.

When referencing PI Identities, if security strings for an AF attribute are already sent and the identities are not yet existing in Seeq, synchronization will be successful but the permissions will not be created accordingly. The permissions will be created correctly only when the AF attribute is sent again to Seeq (when attribute is changed or on a full metadata sync) and the referenced identities are already existing.

Considerations on PIWorldMapping

If PIWorldMapping is configured in PI Connector to a non-null value, piworld identity will not be sent to Seeq. If PIWorldMapping remains null in AF Connector then piworld will be referenced in security strings and as a result, permissions for piworld will not be given (because the identity will not be found).

Handling of disabled AF Identities

Disabled AF Identities are sent to Seeq as disabled user groups.

Handling of disabled Identity Mappings

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

Mapping of AF Element permissions to Seeq permissions

The following table shows how AF Element permissions maps to Seeq permissions.

AF Element permission	Seeq permission
None	NONE
All	NONE - When “All” is selected in the interface, all the other permissions are selected and we just map the individual permissions
Read	Read Metadata
Write	Write Metadata
Read Data	Read Data
Write Data	Write Data
Delete	NONE
Annotate	NONE
Subscribe	NONE
SubscribeOthers	NONE
Admin	Read/Write Metadata + Read/Write Data

Note that even if both: data and metadata 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 an asset, it must have in AF read+read_metadata permissions.

Examples

Example 1

Synchronize AF Identities, security for assets, PIPoint security for AF attributes that map directly to PIPoints and inherit permissions for AF calculations, map AF World and PI piworld to Seeq Everyone:

OSIsoft AF Additional Properties:

JS

{
      "AFServerID": "6d77cda6-254d-4274-8378-38a4a025b3c7",
      "Username": "replace me",
      "Password": "replace me",
      "PISecuritySynchronization": {
        "PointSecurity": true,
        "PIWorldMapping": "Auth/Seeq/Everyone"
      },
      "AFSecuritySynchronization": {
        "IdentityMappingsDatasourceClass": "LDAP",
        "IdentityMappingsStopRegex": "^(BUILTIN\\\\.*)$",
        "Identities": true,
        "ElementsSecurity": true,
        "IdentityMappingsDatasourceId": "REPLACE WITH YOUR ENABLED LDAP DATASOURCE ID",
        "WorldMapping": "Auth/Seeq/Everyone"
      }
}

Note: Do not use WorldMapping when World identity is disabled in AF. See troubleshooting section for more information on this issue.

OSIsoft PI Additional Properties:

JS


{
  "Version": "Seeq.Link.Connector.PI.Config.PIConnectorConfigV3",
  "Connections": [
    {
      "Name": "54.200.148.162",
      "Id": "ae0d4ae1-24d3-4ad7-930b-a0a06db3c24d",
      "Enabled": true,
      "IncrementalIndexingFrequency": "1h",
      "PIServerID": "c29fb683-86c9-4a74-b0af-95b6b9f528fb",
      "SecuritySynchronization": {
        "Identities": true,
        "PointSecurity": true,
        "IdentityMappingsDatasourceClass": "LDAP",
        "IdentityMappingsDatasourceId": "REPLACE WITH YOUR ENABLED LDAP DATASOURCE ID",
        "PIWorldMapping": "Auth/Seeq/Everyone"
      }
    }
  ],
  "ApplicationIdentity": null
}

Example 2: Synchronize only PIPoint security for AF attributes that map directly to PIPoints

OSIsoft AF Additional Properties:

JS

{
      "AFServerID": "6d77cda6-254d-4274-8378-38a4a025b3c7",
      "Username": "replace me",
      "Password": "replace me",
      "PISecuritySynchronization": {
        "PointSecurity": true,
        "PIWorldMapping": "Auth/Seeq/Everyone"
      },
      "AFSecuritySynchronization": {
        "IdentityMappingsDatasourceClass": "LDAP",
        "IdentityMappingsStopRegex": "^(BUILTIN\\\\.*)$",
        "Identities": false,
        "ElementsSecurity": false
      }
}

Relevant changes: AFSecuritySynchronization>Identities set to false, AFSecuritySynchronization>ElementsSecurity set to false, no IdentityMappingsDatasourceId provided.

OSIsoft PI Connector Additional Properties:

JS

{
      "IncrementalIndexingFrequency": "1h",
      "PIServerID": "c29fb683-86c9-4a74-b0af-95b6b9f528fb",
      "SecuritySynchronization": {
        "Identities": true,
        "PointSecurity": true,
        "IdentityMappingsDatasourceClass": "LDAP",
        "IdentityMappingsDatasourceId": "REPLACE WITH YOUR ENABLED LDAP DATASOURCE ID",
        "PIWorldMapping": "Auth/Seeq/Everyone"
      }
}

Troubleshooting

All users are seeing all the assets even if World Identity is disabled on AF Server. This can happen if WorldMapping is enabled (is set to Auth/Seeq/Everyone) and World identity is disabled in AF. Even if World is disabled the security string still contains World. If World is mapped to Everyone in Seeq then Everyone will be able to see all the assets.