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.
{
"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 Usual value: "Auth/Seeq/Everyone". When not null,
|
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:
|
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 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: If for example we don't want BUILTIN users / groups and the user / groups starting with word |
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 Usual value: "Auth/Seeq/Everyone". When not null, in AF Elements security strings, |
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:
{
"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:
{
"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:
{
"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:
{
"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.