User Permissions and Write-Back

Most on-prem PI deployments are not federated with the identity provider that IOTA uses for sign-in. This page explains how the AF-Driver bridges the two, and how to configure permissions so that some IOTA users can write values back to PI while everyone else stays read-only.

Use this page when you need per-user access control. If every IOTA user should have identical access in PI and AF, the driver-level setup in Configuration is all you need.

Why a mapping is required

IOTA and the PI System were built around different identity systems.

	Identifies users by	Grants permissions through
IOTA	Single Sign-On (SSO). The identity provider — Microsoft Entra ID, Okta, Ping — issues an access token containing claims about the user, typically including a list of groups.	Roles inside IOTA.
PI Data Archive and PI AF	Windows Integrated Security (Active Directory, sometimes via LDAP or Kerberos).	A PI or AF identity, which a PI mapping links to a Windows account or AD group.

These two systems have no knowledge of each other. An "Alice" in your identity provider is not automatically the "Alice" that PI sees, and PI cannot read the SSO token that IOTA receives.

The AF-Driver runs as a single Windows service account, so from PI's perspective every request from IOTA arrives over that one account regardless of which IOTA user triggered it. That is fine when all users should have the same access. The moment you want different users to read or write different data, the driver has to make that decision itself — and the groupMappings section of iota.afdrv.json is the lookup table that lets it.

How authorization works

The AF-Driver does not impersonate users in PI or AF. Understanding this is the key to getting permissions right.

1. The user signs into IOTA through SSO. Their access token carries a list of identity provider groups.
2. IOTA forwards the request and the groups claim to the AF-Driver.
3. The driver connects to PI and AF using its own Windows service account.
4. The driver reads the security definitions (ACLs, or "security strings") on the target PI tag or AF object.
5. The driver compares the user's groups against groupMappings to determine which PI and AF identities that user should be treated as.
6. The driver enforces the result internally — filtering data the user may not see, and refusing writes the user is not permitted to make.

Because the driver is the party actually performing the read or write on the connection, two independent checks must both pass:

#	Check	Performed by	What it asks
1	Driver-to-PI	PI Data Archive / AF Server	Is the driver's service account allowed to do this?
2	User-to-driver	The AF-Driver itself	Is this user allowed to do this, based on their groups?

Permissions the driver needs

Because the driver performs every operation under its own account, its identity must hold a superset of everything any IOTA user is allowed to do. If a user is permitted to write to a tag but the driver's identity cannot write to it, the write fails.

At minimum the driver's identity requires:

Permission	Purpose
PIPOINT database Read	Discover and validate tags
tag PointSecurity Read	Read tag security definitions
tag DataSecurity Read	Read tag data
tag DataSecurity Write	Perform write-back

Note that PointSecurity needs Read only, even for write-back — writing values is governed by DataSecurity.

For a writeable tag, the resulting security strings look like this:

PointSecurity = "PIWorld: A(r) | Tag-DataWriter: A(r) | IOTA-AFDriver: A(r)"
DataSecurity  = "PIWorld: A(r) | Tag-DataWriter: A(r,w) | IOTA-AFDriver: A(r,w)"

• PointSecurity controls whether an identity can discover the tag and read its configuration and security definitions.
• DataSecurity controls whether an identity can read and write data values.

Writing to an AF attribute backed by a PI Point

If an AF attribute uses a PI Point data reference, write permission is required on both the AF element or attribute and the underlying PI Point. If either is missing, the write fails even though the user can browse the element normally. This is the most common cause of a write-back that appears to be configured correctly but silently does not work.

Choosing an identity design

Separate read access from write access by group — for example, Plant-DataWriters may write to approved tags and attributes, while Plant-Viewers stay read-only. Two designs are supported.

Option 1 — shared driver and writer identities. The driver reuses the same identities used for write-back.

Account / group	PI identity	AF identity	Access
AF-Driver service account	Tag-DataWriter	AF-DataWriter	Read / write data, read PointSecurity
Plant-DataWriters	Tag-DataWriter	AF-DataWriter	Limited write
Plant-Viewers	PIWorld	AF-Reader	Read only

Best for smaller or simpler deployments.

Option 2 — separate driver and writer identities. The driver uses dedicated system identities, and users map to separate write identities.

Account / group	PI identity	AF identity	Access
AF-Driver service account	IOTA-AFDriver	AF-Driver	Read / write data, read PointSecurity
Plant-DataWriters	Tag-DataWriter	AF-DataWriter	Limited write
Plant-Viewers	PIWorld	AF-Reader	Read only

Best for enterprise or regulated environments, and anywhere you need stronger auditability and separation.

Whichever you choose, keep to least privilege:

• Grant write access only on the PI tags and AF objects that genuinely need it.
• Keep read-only users in separate groups from write-enabled users.
• Avoid granting broad PI administrative access to the driver.

Configuring access

Step 1: Create the driver service account

Create a dedicated Windows domain account for the driver, for example DOMAIN\IOTA-AFDriverSvc. Use a dedicated account rather than running the service as LocalSystem.

Step 2: Configure the driver service

On the driver host, open services.msc and locate the service named Iota AF-Driver <region> <site>. Open its properties and set Log On → This account to the account from Step 1.

Grant that account read and write access to the driver's configuration folder, C:\ProgramData\IOTA\Drivers\AF-Driver_<region>_<site>, so it can read configuration files, store runtime data, access certificates, and write logs.

Steps 1 and 2 are covered in more detail in Configuration.

Step 3: Create PI identities and mappings for the driver

In PI System Management Tools, go to Security → Identities, Users & Groups and create the identity the driver will use, for example IOTA-AFDriver. Then go to Security → Mappings & Trusts and map the Windows service account to it:

Windows account	PI identity
DOMAIN\IOTA-AFDriverSvc	IOTA-AFDriver

Grant that identity the permissions listed in Permissions the driver needs.

Step 4: Create PI identities for end users

Create the identities that represent each level of user access. These are what groupMappings matches against.

User group	PI identity	Access
Plant-Viewers	PIWorld	Read only
Plant-DataWriters	Tag-DataWriter	Read and write on selected tags

Step 5: Set PI tag and AF security

Configure the target objects so the identities from Steps 3 and 4 have the access they need. For PI tag write-back, set both PointSecurity and DataSecurity as shown in Permissions the driver needs. Use the Point Builder add-on for Excel if you need to update more than a handful of tags.

For AF, right-click the element, attribute, or template and choose Security to open the Security Configuration dialog. You can apply a change recursively to all descendants of an element. To let IOTA users acknowledge or annotate event frames, grant Annotate on the event frame template.

Step 6: Configure groupMappings

Edit C:\ProgramData\IOTA\Drivers\AF-Driver_<region>_<site>\iota.afdrv.json and add a groupMappings section:

{
  "groupMappings": {
    "Plant-DataWriters": {
      "roles": [ "Tag-DataWriter" ]
    },
    "Plant-Viewers": {
      "roles": [ "PIWorld", "World" ]
    }
  }
}

Each key is an identity provider group exactly as it appears in the SSO token. Each string in roles is a PI or AF identity name, again matched exactly — the driver does a plain string comparison, with no wildcards or fuzzy matching.

Save the file and restart the driver service.

PIWorld and World are not implicit

Once groupMappings is in use, the driver no longer maps users to the built-in PIWorld or World identities automatically. Any group that should keep default read access must list them explicitly, as Plant-Viewers does above. Omitting them is how you deliberately restrict a group to a subset of data. A user whose groups match nothing in groupMappings is treated as having no PI or AF permissions at all, so searches return empty.

Identity names share a single namespace

The driver does not track which system an identity name came from. When it evaluates roles, it compares each string against every security object it knows about, across the PI Data Archive, PI AF, and any additional archives the same driver connects to.

• Do not reuse a name across the PI Data Archive and PI AF. Creating IOTA Writers as both a PI identity and an AF identity means "IOTA Writers" in roles matches both, even if you intended only one. Use distinguishable names such as Tag-DataWriter on PI and AF-DataWriter on AF.
• If one driver connects to multiple PI Data Archives, identities on each archive must have different names. Identical names collapse into a single roles entry, so you lose the ability to grant write access on one archive while staying read-only on another. Prefix or suffix with the archive name, for example ArchiveA-Writer.

Step 7: Validate

Test with one read-only user and one write-enabled user.

• Read-only user — sign in as a member of Plant-Viewers, confirm they can view PI and AF data, and confirm they cannot write back.
• Write-enabled user — sign in as a member of Plant-DataWriters, confirm they can view data, confirm they can write to the approved tags and attributes, and confirm they cannot write outside that scope.

Examples

Write access for a subset of users

IOTA can write to PI and AF in three ways: writing a value to a PI tag, writing a value to an AF attribute (which may or may not be bound to a PI tag), and acknowledging or annotating an event frame. It is common to restrict all three to a subset of users.

Suppose your identity provider defines the groups IOTA Users, IOTA Operators, and IOTA Engineers, and you have these identities: IOTA Driver (in both PI and AF), Manual Data Writer (PI), and Event Frame Annotator (AF). The goal:

• IOTA Operators may manually write data to a fixed set of PI tags through a form in IOTA.
• IOTA Engineers may acknowledge and annotate event frames.
• Everyone else is read-only.

To configure it:

1. Map the driver service account to the IOTA Driver identity in both PI and AF.
2. In PI, grant IOTA Driver Write on DataSecurity for the tags that will hold manually entered data. It needs only Read on the PIPOINT database and on PointSecurity.
3. In AF, grant IOTA Driver Annotate on the event frame template you want to work with in IOTA.
4. Add to the driver config:

{
  "groupMappings": {
    "IOTA Users": {
      "roles": [ "PIWorld", "World" ]
    },
    "IOTA Operators": {
      "roles": [ "Manual Data Writer" ]
    },
    "IOTA Engineers": {
      "roles": [ "Event Frame Annotator" ]
    }
  }
}

How this plays out:

• Alice belongs to IOTA Users and IOTA Engineers. She opens a view showing event frames. The driver connects and AF grants it IOTA Driver plus World, which allows the read. Alice's IOTA Users membership maps to World, so the driver returns the event frames.
• Alice clicks to acknowledge an event frame. Her IOTA Engineers membership maps to Event Frame Annotator, which holds Annotate, so the driver permits it — and the driver's own IOTA Driver identity has Annotate on the template, so AF accepts the write.
• Bob belongs to IOTA Users only. He can read the same event frames, but when he tries to acknowledge one the driver blocks it, because none of his groups map to an identity with Annotate. Note the driver itself is authorized to perform the acknowledgement — it declines because Bob is not.

Different read access for different users

Suppose you aggregate two plants into the same PI and AF servers, and each plant's workers should see only their own data. With groups Plant A Workers and Plant B Workers, and identities IOTA Driver, Plant A Reader, and Plant B Reader:

1. Map the driver service account to IOTA Driver. If PIWorld and World are still enabled, the driver already has read access to everything, so no per-tag changes are needed for reads.
2. Confirm Plant A's tags are readable by Plant A Reader and Plant B's by Plant B Reader. In the PI security strings you should see entries like Plant A Reader: A(r).
3. Add to the driver config:

{
  "groupMappings": {
    "Plant A Workers": {
      "roles": [ "Plant A Reader" ]
    },
    "Plant B Workers": {
      "roles": [ "Plant B Reader" ]
    }
  }
}

Note that no group is mapped to PIWorld or World here. That is deliberate: those identities grant read access to both plants, so mapping any group to them would let that group read the other plant's data.

The result: the driver process still reads everything (it holds IOTA Driver plus PIWorld/World), but it only returns each user the data their own plant's identity permits. A Plant A worker requesting a Plant B tag is blocked by the driver, because none of their groups map to an identity allowed to read Plant B objects.

Verifying what the driver sees

Because everything depends on a string comparison between group names and the keys in groupMappings, the most common failure is a mismatch — a typo, a missing prefix, or an identity provider that emits group IDs instead of names.

Check the actual contents of a user's token using the procedure in Verifying the Groups Claim. Whatever appears there is exactly what the driver compares against your groupMappings keys, so it must match character for character.

Two results worth calling out:

• The groups show as GUIDs (for example 5f8b…e3a1) rather than names. Either use those GUIDs as the groupMappings keys, or reconfigure the identity provider to emit names.
• Only your company's email domain appears, with no groups at all. The identity provider is not emitting a groups claim, and groupMappings cannot work without one. Fix that before going any further.

Troubleshooting

• Check the user's session for the expected group information, as described above.
• Verify the keys and roles values in groupMappings match the real group and identity names exactly.
• Confirm the PI mapping of the driver's Windows account resolves to the expected identity.
• Verify the driver identity holds the full superset of permissions, including DataSecurity Write on any writeable tag.
• For AF attributes backed by a PI Point, confirm write permission exists on both the attribute and the PI Point.
• Review the PI access logs and the driver log.

Related

• Configuration — driver-level authentication, the config file reference, and data source setup
• Overview — what the AF-Driver does and which PI object types it supports
• Install/Uninstall — installing and updating the driver service