AF SDK Reference

AFSecurityMappings.Add Method (String, String, AFSecurityIdentity, AFSecurityMappingType)

Save PDF

AFSecurityMappings.Add Method (String, String, AFSecurityIdentity, AFSecurityMappingType)

Save PDF

Last UpdatedNov 18, 2025
4 minute read

The Add method creates a new AFSecurityMapping from the specified OpenId Connect account to a AFSecurityIdentity and adds it to the collection.

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

Syntax

public AFSecurityMapping Add(
	string name,
	string account,
	AFSecurityIdentity securityIdentity,
	AFSecurityMappingType mappingType
)

Public Function Add ( 
	name As String,
	account As String,
	securityIdentity As AFSecurityIdentity,
	mappingType As AFSecurityMappingType
) As AFSecurityMapping

Dim instance As AFSecurityMappings
Dim name As String
Dim account As String
Dim securityIdentity As AFSecurityIdentity
Dim mappingType As AFSecurityMappingType
Dim returnValue As AFSecurityMapping

returnValue = instance.Add(name, account, 
	securityIdentity, mappingType)

public:
AFSecurityMapping^ Add(
	String^ name, 
	String^ account, 
	AFSecurityIdentity^ securityIdentity, 
	AFSecurityMappingType mappingType
)

member Add : 
        name : string * 
        account : string * 
        securityIdentity : AFSecurityIdentity * 
        mappingType : AFSecurityMappingType -> AFSecurityMapping

Parameters

name: Type: SystemString
The name for the new object, which must be unique within the collection. If not specified, then the user name associated with the specified account will be used with an asterisk (*) to ensure the name is unique.. If the specified name ends with an asterisk (*), then a unique name will be generated based on the supplied name. See the ValidateName(String, String) method for a description of what is valid when setting the name of the object.
account: Type: SystemString
The String to be used when creating the new mapping.
securityIdentity: Type: OSIsoft.AFAFSecurityIdentity
The AFSecurityIdentity that the account should be mapped.
mappingType: Type: OSIsoft.AFAFSecurityMappingType
AFSecurityMappingType used to determine the type of mapping being added.

Return Value

Type: AFSecurityMapping
Returns the newly created AFSecurityMapping that was added to the collection.

Exceptions

Exception	Condition
ArgumentException	This exception is thrown when attempting to add a duplicate account to an AFSecurityIdentity.
InvalidOperationException	This exception can be thrown when attempting to call this method on a reference collection which does not own the object, or when attempting to create an Open ID Connect mapping and the AFServer failed to read list of supported Providers and Roles from the AIM Server.

Remarks

The new AFSecurityMapping will be created from the specified account to a AFSecurityIdentity. If the name is not specified, then the Name of the new mapping will be the user name associated with the account. The Account of the created mapping will be the Role Id of the specified account parameter. The SecurityIdentity of the created mapping will be set to the specified securityIdentity parameter.

Examples

// This example shows how to create AF Security Mappings used for OpenId Connections
// to the PI AF Server.

// Get the PISystem
PISystems myPISystems = new PISystems();
PISystem myPISystem = myPISystems.DefaultPISystem;

// Retrieve the Administrators AFSecurityIdentity
AFSecurityIdentity siAdmin = myPISystem.SecurityIdentities["Administrators"];

// Add a new Security Mapping for the aaAdministrators group on the Identity Server
string securityMappingName = @"Windows\aaAdministrators";
string securityMappingId = $@"Windows\{AIMDirectory}\aaAdministrators";

// Example for removing a Role mapping
AFSecurityMapping tmpMapping = myPISystem.SecurityMappings[securityMappingName];
if (tmpMapping != null)
{
    myPISystem.SecurityMappings.Remove(securityMappingName);
    myPISystem.CheckIn();
}

// Example for creating a Role mapping
AFSecurityMapping myMapping1 = myPISystem.SecurityMappings.Add(securityMappingName, securityMappingId, siAdmin, AFSecurityMappingType.Role);
myMapping1.Description = "Administrators on AIM Identity Server";
myPISystem.CheckIn();

// Connect to AF Server using Open Id Connection for user in the Administrators group
myPISystem.Connect(TestAccountAccessToken);
Console.WriteLine("CurrentUserName = {0}", myPISystem.CurrentUserName);
Console.WriteLine("AuthenticationType = {0}", myPISystem.ConnectionInfo.AuthenticationType);
Console.WriteLine("Security HasAdmin = {0}", myPISystem.Security.HasAdmin);
Console.WriteLine("Security CanWrite = {0}", myPISystem.Security.CanWrite);

// Lookup the Administrators AFSecurityIdentity
siAdmin = myPISystem.SecurityIdentities["Administrators"];

// Example for creating a ClientCredential mapping
// Mapping of Client Ids requires AFServer connection with Administrator permissions on the Identity Server.
AFSecurityMapping myMapping2 = myPISystem.SecurityMappings.Add(TestClientId, TestClientId, siAdmin, AFSecurityMappingType.ClientCredential);
myMapping2.Description = "ClientId mapping";
myPISystem.CheckIn();

myPISystem.Connect(TestClientId, TestClientSecret);
Console.WriteLine("CurrentUserName = {0}", myPISystem.CurrentUserName);
Console.WriteLine("AuthenticationType = {0}", myPISystem.ConnectionInfo.AuthenticationType);
Console.WriteLine("Security HasAdmin = {0}", myPISystem.Security.HasAdmin);
Console.WriteLine("Security CanWrite = {0}", myPISystem.Security.CanWrite);

Version Information

AFSDK

Supported in: 3.1.1, 3.1.0, 3.0.2, 3.0.1, 3.0.0

AF SDK Reference