Custom Connectors

Connector Overview

We use connectors to connect with external systems. EmpowerID will create an account store, which represents a connection to an external system. In the connector, you define whether you are bringing in only users, users and groups, or only users along with their external roles or external locations. We have two types of connectors: Custom Connectors and SCIM Connectors. In this training, we will focus solely on Custom Connectors.

Architecture Diagram:
The above image shows the architecture of how we retrieve data from an external system, process it, and then push it to the external system.

---

Connector Framework

If you are trying to connect with a system that has a backend in SQL or Oracle, we use stored procedures to retrieve or update the data. Similarly, we use REST APIs for systems that support REST APIs. For SAP, we use ABAP, and for Active Directory, we use LDAP, among other methods.

---

Inbound Processing

1. Account Inbox Job Processor
   The Account Inbox Job Processor examines any orphaned accounts. This permanent workflow is responsible for the joiner process. It can provision a person or associate an account with an existing person.

2. Attribute Sync (Attribute Flow Processor)
   This processor examines all the data inventory that has been created to determine if attributes have changed. If so, the job will update the person or attribute accordingly. For example, if HR indicates that your job title has changed from its previous value to a new value, then this job will update the person's record accordingly.

3. Role/Location Processor
   Typically used in conjunction with HR inventory processes. For example, if HR requires an employee to move from Germany to France, this job will facilitate that change.

4. Inventory
   Inventory is responsible for running the inventory for every account store. Through inventory, data is integrated into EmpowerID. Every connector must implement the Inventory method.

---

Outbound Processing

1. Provisioning Policies
   Provisioning policies (also known as Resource Entitlement Policies or RETS) automate the provisioning, movement, deactivation, and de-provisioning of resources such as Active Directory accounts, Exchange mailboxes, and Home folders for employees. These policies enable administrators to manage resource allocations based on roles, memberships, and locations. They are evaluated whenever an EmpowerID Person is created or assigned to a Business Role and Location, Management Role, group, or Query-Based Collection. Provisioning policies can target various actor types including Business Roles and Locations, Management Roles, Management Role Definitions, Query-Based Collections, groups, and individual people. They can be configured to automatically modify resource allocations in response to changes, making the provisioning process more efficient.

2. Group Reconciliation
   The Group Reconciliation Job checks and reconciles group memberships to ensure that the system accurately reflects these memberships. It involves tasks such as checking membership counts, identifying groups causing timeouts, and enforcing RBAC assignments. This job is essential for maintaining the accuracy and integrity of group memberships.

3. Attribute Sync (Attribute Flow Processor)
   In the outbound process, this attribute flow processor handles the data being sent from EmpowerID to an external system.

4. Dynamic Hierarchy
   Dynamic Hierarchy policies allow groups to be generated dynamically based on organizational business hierarchy. These policies can create nested groups in systems like Active Directory and Azure Active Directory. The process runs completely automated, leveraging enterprise data from HR or other authoritative sources to automatically create and maintain valuable groups. For example, new nested groups can be created when a new department is added to HR or when an employee is promoted. Dynamic Hierarchies save organizations time, money, and improve collaboration.

---

Custom Connector Classes

When using the Connector template, the following classes are created. For example, CustomDeltaConnector.cs is a class that we created (it was not part of the template) and it contains the Inventory method. The Inventory job is going to invoke this method.

This is what our Inventory method in CustomDeltaConnector.cs looks like. The Inventory job is going to invoke this method.

Inventory Providers

Under the Inventory Providers folder, there are five types of inventory classes:

• AccountInventoryProvider
• GroupInventoryProvider
• MappingProvider
• RolesInventoryProvider
• ZonesInventoryProvider

If you open the AccountInventoryProvider.cs class, you will see three methods that override the default behavior:

1. GetAllEntries
   Retrieves users from the external system and saves them in an AccountStoreIdentityEntry as a T List.

2. SynchToEntity
   Handles the situation where data from the external system (stored as an AccountStoreIdentityEntry) needs to be saved to the Account table.

3. IsSynchedWithEntity
   In this method, we compare the data coming from the external system with the existing data in our table to determine if it has changed. If it has changed, then we synchronize it; otherwise, we do not. Let's say we retrieve data from SAP and, before inserting it into the SQL database (specifically, the Account table), we check whether the data has been modified. If it has been modified, we'll insert it. We might also have a condition where the data in SAP has been modified, but the specific data we are interested in, such as the first name or last name, has not changed. From the EmpowerID perspective, the data remains unchanged. Such logic can be implemented inside this method.

   

ASIE Providers

Under the ASIE Providers folder, there are two classes:

• GroupMembershipProvider
• UserASIEProvider

In the UserASIEProvider.cs class, one important method is:

1. GetAll
   This method calls all the inventory providers. It centralizes both user and group inventories, distinguishing them by the objectClass.

   

---

Understanding the Account Store Identity Entry (ASIE)

The Account Store Identity Entry (ASIE) is an intermediate object where raw data received from the external system is stored in a dictionary. Transformations (such as trimming or data formatting) can be applied at this level. An ASIE is created for every record received, and it serves as the basis for producing a T list of AccountStoreIdentityEntry.

In the first code shape (DB Table User), we have a table called User. To read data from this table, we use a Reader. This process is independent of EmpowerID and is a standard way of interacting with the system. Here, we're just representing it. Then, we work with AccountStoreIdentityEntry(ASIE).

In the connector, the initial action involves making a call to the database using the ConnectionString, invoking the stored procedure, and then reading the data into AccountStoreIdentityEntry. After reading data from SQL, we convert it into ASIE. The next step is to convert this ASIE depending on its type. ASIE is essentially a dictionary, and the conversion depends on the Object class or the type of the entry, whether it’s a user, group, mailbox, or computer. Depending on the type, EmpowerID will call different methods to create the corresponding component entry. For example, if it's an Account, the data will go to the Account table; if it's a Group, it will go to the Group table, and so on and so forth.

info

Key Concept: EmpowerID workflows and API calls operate against Components, not AccountStoreIdentityEntry. This means that the same workflows will work for objects in any system. Any new connected system can use the existing workflows.

note

Before we start creating Custom Connector, we should have a good understanding of following concepts

1. Account Store
2. Security Boundary Type
3. Resource System Type
4. Manage Schema (Page on the EmpowerID UI)

In order to understand the concept mentioned above, refer to the Admin training. However, we'll also provide a basic definition of them below. Additionally, in the lab, we will create all of these, where you will gain a more thorough understanding of the topic.

---

Account Store

An Account Store refers to external directories or applications that manage their own accounts and groups. EmpowerID provides connectors for a wide range of user directories and resource systems, enabling administrators to quickly connect EmpowerID to their organization's identity-aware systems and applications. Once connected, administrators can manage:

• User and group data inventory
• Creation, updating, and deletion of records
• Enabling and disabling accounts
• Password resets for user accounts

In EmpowerID terminology, external systems containing user accounts are known as Account Stores. For instance, an external Active Directory is considered an Account Store.

How to view your tasks and requests in My Tasks.

---

Security Boundary Type

A Security Boundary Type in EmpowerID is a classification that defines the connector used for creating, updating, deleting, and the attribute schema of the native objects directly managed in an external system. It maintains information pointing to the definition of the connector used for Create, Update, Delete, and the attribute schema of the native objects directly managed in an external system. Security Boundary Types are part of the EmpowerID system and are used to represent the trust relationship between domains and the Active Directory Forest concept. Each Account Store within the Active Directory Forest belongs to a single Security Boundary in EmpowerID, representing that forest. These Security Boundaries are part of a specific Security Boundary Type, which defines the connector used for creating, updating, and deleting objects in the external system and their attribute schema. Therefore, for resources contained in account stores, there will always be at least one resource system, account store, security boundary, and security boundary type in EmpowerID.

Resource System Type

The Resource System Type in EmpowerID is the definition of the connector for inventorying data from an external system. This differs from Security Boundary Types, which contains the connector definition for Create, Update, Delete, and the attribute schema of the native objects directly managed in an external system. Each system that contains protected resources must be registered as a Resource System in the EmpowerID Identity Warehouse and is assigned a unique ResourceSystemID and ResourceSystemGUID.

Manage Schema (About the EmpowerID Schema)

All objects of any type (such as EmpowerID Persons, user accounts, and groups, etc.) managed by EmpowerID have an entry in a table of the EmpowerID Identity Warehouse that corresponds to the object’s type. Whenever you create a new object in EmpowerID, you are creating a new instance of that object, which adds a new entry for that instance to the appropriate table. The properties or attributes of the object determine the table where these can be inserted.

The EmpowerID schema defines which objects can have which properties, what values those properties can have and how users might interact with them. EmpowerID has two types of attributes:

• Built-in: Properties that are predefined by the EmpowerID schema.
• Extension: Properties that are provided for adding custom attributes. For example, if you’ve connected to an external directory with a user attribute not defined by the EmpowerID Schema, you can flow that attribute to the EmpowerID Account and Person tables by using an extension property on those objects.

When it comes to defining objects by object type, the EmpowerID Schema provides the following components. These components make is possible to map attributes in an external system to EmpowerID.

Object Attributes

Object Attributes represent a catalog of abstract properties in EmpowerID that an object can have in any given system. Object attributes are conceptual; they are not the actual name of properties in those systems. For example, “Last Name” is a concept. Each user has a Last Name element in most directory systems. Depending on the system, this information can be referred to as surname, FamilyName, last_name and so on. Active Directory’s field to store this data is simply labeled sn. EmpowerID has a single Object Attribute for LastName to represent a user’s Last Name in each of those systems.

Example Object Attributes

Object Attribute (EmpowerID)	Object Attribute Type Name
AboutMe	String
AccountExpires	DateTime
Active	Boolean
LastName	String

Security Boundary Attributes

To accurately connect fields—such as the last name field in a given system—with corresponding EmpowerID objects, it is important to identify whether a system recognizes the concept of a last name. If it does, the specific field name used by that system must be defined. This is where Security Boundary Attributes come into play.

Security Boundary Attributes act as connectors between external systems and EmpowerID. They store key details about how each system labels specific properties, such as a user's last name, and ensure that EmpowerID can understand those labels, even if they differ across platforms.

Example Security Boundary Attributes

Security Boundary Attribute	Security Boundary Type	Object Attribute (EmpowerID)	Attribute Type
AboutMe	Microsoft SharePoint	AboutMe	String
accountExpires	Active Directory Domain Services	AccountExpires	DateTime
address[?(@.type=='work')].streetAddress	Azure AD SCIM	StreetAddress	String
last_name	ServiceNow	LastName	String

The table above illustrates the relationship between Object Attributes in EmpowerID and Security Boundary Attributes across different systems. It shows four example Security Boundary Attributes, each representing a field from a different system type (Security Boundary Type). Each of these attributes maps directly to a corresponding Object Attribute in EmpowerID.

This mapping ensures seamless data synchronization. When external directories are inventoried, the correct field values flow into the Person and Account records within EmpowerID. Furthermore, if attribute flow is enabled, any changes made in the external systems will automatically update the corresponding values in EmpowerID, keeping records consistent and up to date.