AF SDK Reference

AFSecurity.CheckSecurity Method (WindowsIdentity)

Save PDF

TABLE OF CONTENTS

AFSecurity.CheckSecurity Method (WindowsIdentity)

Save PDF

Last UpdatedNov 18, 2025
7 minute read

Evaluate the AFSecurityRights of the specified user for the object.

Namespace: OSIsoft.AF
Assembly: OSIsoft.AFSDK (in OSIsoft.AFSDK.dll) Version: 3.1.1.1182

Syntax

public AFSecurityRights CheckSecurity(
	WindowsIdentity userIdentity
)

Public Function CheckSecurity ( 
	userIdentity As WindowsIdentity
) As AFSecurityRights

Dim instance As AFSecurity
Dim userIdentity As WindowsIdentity
Dim returnValue As AFSecurityRights

returnValue = instance.CheckSecurity(userIdentity)

public:
AFSecurityRights CheckSecurity(
	WindowsIdentity^ userIdentity
)

member CheckSecurity : 
        userIdentity : WindowsIdentity -> AFSecurityRights

Parameters

userIdentity: Type: System.Security.PrincipalWindowsIdentity
The WindowsIdentity of the user for the security rights to be checked. If , then the security rights of the current user are checked. Only domain accounts or local accounts on the PI AF Server are supported by this method.

Return Value

Type: AFSecurityRights
Returns the AFSecurityRights of the specified user for the object.

Exceptions

Exception	Condition
ArgumentException	For a 2.7 or later server, this exception is thrown when a local account is specified for the userIdentity parameter.
COMException	For a 2.6 or earlier server, this exception with HRESULT 0x8007051D is thrown when the specified userIdentity is a primary token and not an impersonation token. This method does not care whether the thread is actually impersonated.

Remarks

This method will evaluate and return the security rights for the user identified by the specified WindowsIdentity for the object. This can be used to check the security permissions of a different user other than the current user. Use the IAFSecurable.Security property to check security for the current user of an object.

The security rights are evaluated on the server initially for each unique user and then cached in the client. This improves performance of the security check for the same user if the object has the same security permissions. The cache is cleared when calling ClearSecurityRightsCache(PISystem), PISystem.Disconnect, or one of the PISystem.Refresh methods.

Caution
Normally, security is checked on the computer running the PI AF Server. When using a 2.7 or later version of the PI AF Server, this check will be performed on the server and will not have an issue with built-in groups. For older versions of the server, this method will perform the security check on the client and will not work correctly if built-in groups are used in the security descriptor.

Caution

Normally, security is checked on the computer running the PI AF Server. When using a 2.7 or later version of the PI AF Server, this check will be performed on the server and will not have an issue with built-in groups.

For older versions of the server, this method will perform the security check on the client and will not work correctly if built-in groups are used in the security descriptor.

Examples

This example shows how to call CheckSecurity for a single user on a single object or with a bulk call on several objects.

// Get the Database
PISystems myPISystems = new PISystems();
PISystem myPISystem = myPISystems.DefaultPISystem;
AFDatabase myDB = myPISystem.Databases.DefaultDatabase;

// Create the Elements
List<AFElement> elements = new List<AFElement>();
AFElement myElement1 = myDB.Elements.Add("MyElement#1");
myElement1.CheckIn();
elements.Add(myElement1);
AFElement myElement2 = myDB.Elements.Add("MyElement#2");
myElement2.CheckIn();
elements.Add(myElement2);

// Obtain the WindowsIdentity of an impersonated user. This
//   can be done with the following code if the current thread
//   has impersonated a user.
//  WindowsIdentity user = WindowsIdentity.GetCurrent();
// Obtain the WindowsIdentity of a different domain user. This
//   can be done with the following code.
//  WindowsIdentity user = new WindowsIdentity("username@domain");
int notFoundCount = 0;
using (WindowsIdentity user = windowsIdentityOfADifferentUser)
{

    // Check Security Rights of a Different User
    AFSecurity security1 = myElement1.Security;
    AFSecurityRights rights = security1.CheckSecurity(user);
    Console.WriteLine("SecurityRights for '{0}': '{1}'", myElement1.Name, rights);
    Console.WriteLine("    CanRead={0}", rights.CanRead());
    Console.WriteLine("    CanWrite={0}", rights.CanWrite());
    Console.WriteLine();

    // Check Security Rights of a Different User in Bulk
    List<AFSecurityRightsToken> tokens = new List<AFSecurityRightsToken>();
    tokens.Add(security1.Token);
    tokens.Add(myElement2.Security.Token);
    IDictionary<Guid, AFSecurityRights> rightsDict = AFSecurity.CheckSecurity(myPISystem, user, tokens);
    foreach (AFElement element in elements)
    {
        if (rightsDict.TryGetValue(element.ID, out rights))
        {
            Console.WriteLine("SecurityRights for '{0}': '{1}'", element.Name, rights);
            Console.WriteLine("    CanRead={0}", rights.CanRead());
            Console.WriteLine("    CanWrite={0}", rights.CanWrite());
            Console.WriteLine();
        }
        else
        {
            notFoundCount++;
        }
    }
}

' Get the Database
Dim myPISystems As New PISystems
Dim myPISystem As PISystem = myPISystems.DefaultPISystem
Dim myDB As AFDatabase = myPISystem.Databases.DefaultDatabase

' Create the Elements
Dim elements As New List(Of AFElement)()
Dim myElement1 As AFElement = myDB.Elements.Add("MyElement#1")
myElement1.CheckIn()
elements.Add(myElement1)
Dim myElement2 As AFElement = myDB.Elements.Add("MyElement#2")
myElement2.CheckIn()
elements.Add(myElement2)

' Obtain the WindowsIdentity of an impersonated user. This
'   can be done with the following code if the current thread
'   has impersonated a user.
'  Dim user As WindowsIdentity = WindowsIdentity.GetCurrent()
' Obtain the WindowsIdentity of a different domain user. This
'   can be done with the following code.
'  Dim user As WindowsIdentity = New WindowsIdentity("username@domain")
Dim notFoundCount As Integer = 0
Using user As WindowsIdentity = windowsIdentityOfADifferentUser
    ' Check Security Rights of a Different User
    Dim security1 As AFSecurity = myElement1.Security
    Dim rights As AFSecurityRights = security1.CheckSecurity(user)
    Console.WriteLine("SecurityRights for '{0}': '{1}'", myElement1.Name, rights)
    Console.WriteLine("    CanRead={0}", rights.CanRead())
    Console.WriteLine("    CanWrite={0}", rights.CanWrite())
    Console.WriteLine()

    ' Check Security Rights of a Different User in Bulk
    Dim tokens As New List(Of AFSecurityRightsToken)()
    tokens.Add(security1.Token)
    tokens.Add(myElement2.Security.Token)
    Dim rightsDict As IDictionary(Of Guid, AFSecurityRights) = AFSecurity.CheckSecurity(myPISystem, user, tokens)
    For Each element As AFElement In elements
        If rightsDict.TryGetValue(element.ID, rights) Then
            Console.WriteLine("SecurityRights for '{0}': '{1}'", element.Name, rights)
            Console.WriteLine("    CanRead={0}", rights.CanRead())
            Console.WriteLine("    CanWrite={0}", rights.CanWrite())
            Console.WriteLine()
        Else
            notFoundCount += 1
        End If
    Next
End Using

No code example is currently available or this language may not be supported.

This example shows how to search for the object's Security Token and make a bulk call to check security on several objects for the current user.

// Get the Database
PISystems myPISystems = new PISystems();
PISystem myPISystem = myPISystems.DefaultPISystem;
if (myPISystem == null)
    throw new InvalidOperationException("Default PISystem was not found.");
AFDatabase myDB = myPISystem.Databases[dbName];
if (myDB == null)
    throw new InvalidOperationException("Database was not found.");

// Create a search to find all the event frames created from the 'Event'
// template and its 'Level' attribute value is less than 90.
int count;
using (var search = new AFEventFrameSearch(myDB, "FindEventFields", @"Template:'Event' |Level:<90.0"))
{
    search.CacheTimeout = TimeSpan.FromMinutes(10);

    // Do the search
    // 
    // Return event frame security tokens as list and check security for current user.
    count = 0;
    var foundItems4 = search.FindObjectFields("SecurityToken", i => (AFSecurityRightsToken)i[0]);
    Console.WriteLine("Find Object SecurityTokens and Check Security:");
    foreach (var tokenList in foundItems4.ChunkedBy(500))
    {
        // Check Security using Windows Identity.
        var rights = AFSecurity.CheckSecurity(myPISystem, WindowsIdentity.GetCurrent(), tokenList);
        foreach (var rightsItem in rights)
        {
            Console.WriteLine($"  Security Rights for '{myPISystem.CurrentUserName}': {rightsItem.Key} = {rightsItem.Value}");
        }

        // Check Security using Identities.
        rights = AFSecurity.CheckSecurity(myPISystem, myPISystem.CurrentUserIdentities, tokenList, myPISystem.CurrentUserName);
        foreach (var rightsItem in rights)
        {
            Console.WriteLine($"  Security Rights for '{myPISystem.CurrentUserIdentityString}': {rightsItem.Key} = {rightsItem.Value}");
        }
        count += tokenList.Count;
    }
    Console.WriteLine("Found {0} EventFrames.", count);
}

' Get the Database
Dim myPISystems As New PISystems()
Dim myPISystem As PISystem = myPISystems.DefaultPISystem
If myPISystem Is Nothing Then
    Throw New InvalidOperationException("Default PISystem was not found.")
End If
Dim myDB As AFDatabase = myPISystem.Databases(dbName)
If myDB Is Nothing Then
    Throw New InvalidOperationException("Database was not found.")
End If

' Create a search to find all the event frames created from the 'Event'
' template and its 'Level' attribute value is less than 90.
Dim count As Integer
Using search As New AFEventFrameSearch(myDB, "FindEventFields", "Template:'Event' |Level:<90.0")

    search.CacheTimeout = TimeSpan.FromMinutes(10)

    ' Do the search

    ' Return event frame security tokens as list and check security for current user.
    count = 0
    Dim foundItems4 = search.FindObjectFields("SecurityToken", Function(i) CType(i(0), AFSecurityRightsToken))
    Console.WriteLine("Find Object SecurityTokens and Check Security:")
    For Each tokenList In foundItems4.ChunkedBy(500)
        ' Check Security using Windows Identity.
        Dim rights = AFSecurity.CheckSecurity(myPISystem, WindowsIdentity.GetCurrent, tokenList)
        For Each rightsItem In rights
            Console.WriteLine($"  Security Rights for '{myPISystem.CurrentUserName}': {rightsItem.Key} = {rightsItem.Value}")
        Next

        ' Check Security using Identities.
        rights = AFSecurity.CheckSecurity(myPISystem, myPISystem.CurrentUserIdentities, tokenList, myPISystem.CurrentUserName)
        For Each rightsItem In rights
            Console.WriteLine($"  Security Rights for '{myPISystem.CurrentUserIdentityString}': {rightsItem.Key} = {rightsItem.Value}")
        Next
        count = (count + tokenList.Count)
    Next
    Console.WriteLine("Found {0} EventFrames.", count)

End Using

No code example is currently available or this language may not be supported.

AF SDK Reference