Building a custom PowerShell connector for OpenIAM

OpenIAM provides the ability to create your own custom PowerShell connector. This can be done using the special 'Generic' connector, which serves as a template that you can use for your own PowerShell connector development. This script represents the business logic of a connector, which is fully separated from the rest of the internal implementation. The internal implementation handles processes such as maintaining the connection with OpenIAM, exchanging data, managing tasks, parallelizing them, writing logs, etc., allowing you to focus on implementing your business logic while the connector core takes care of the rest.

This connector, like any other type of OpenIAM connector, supports the following operations. For each of the operations below, this script contains placeholder functions that you can implement:

• SAVE is a Save-Identity function.
• SEARCH is a Search-Data function.
• DELETE is a Remove-Identity function.
• RESET_PASSWORD is a Reset-IdentityPassword function.
• LOGIN is a Test-IdentityPassword function.
• SUSPEND is a Suspend-Identity function.
• RESUME is a Resume-Identity function.
• TEST is a Test-ConnectorConnection function.

In each of the functions above, you have access to global variables (defined at the beginning) as follows:

headerAttributes contains information from the managed system level and general information about the request. Here are examples of accessing commonly used properties:

• $headerAttributes.Type represents the type of identity. Common values are USER and GROUP. For example, if you receive a SAVE operation, you may have different logic for saving users, groups, or other objects.
• $headerAttributes.Login and $headerAttributes.Password are used for accessing the service account login and password, respectively.
• $headerAttributes.Url is used for accessing the hostname property defined in the managed system.
• $headerAttributes.IdentityName is used for the principal name of the target identity for which you need to run the current operation. For example, if you need to save a user found in your organization by 'user@yourOrg.com', this property would contain 'user@yourOrg.com' in this case.
• $headerAttributes.OriginalIdentityValue contains the principal name of an identity used for renaming operations. For instance, if OpenIAM requests renaming 'userA@yourOrg.com' to 'userB@yourOrg.com', it would send two attributes: $headerAttributes.OriginalIdentityValue with 'userA@yourOrg.com' and $headerAttributes.IdentityName with 'userB@yourOrg.com'.
• $headerAttributes.attributes.SEARCH_QUERY.Value is for accessing the search query and is used only in SEARCH operations.
• oiamAttributes contains policy map information defined on the OpenIAM side. Each attribute contains a value and an operation that indicates what you need to do with this value. For example:
  • $oiamAttributes.Name.Value accesses the 'Name' attribute value defined in the policy map.
  • $oiamAttributes.Name.Operation tells you what to do with the value above. Possible values include ADD, REPLACE, DELETE, and NO_CHANGE.
  • searchAttributes is used only in the SEARCH operation type. It contains properties that OpenIAM requests the connector to return.

Please note that OpenIAM is case-sensitive, so imagine that this list contains just two attributes: UserPrincipalName and NaME. This means that you should run a search request (defined in the $headerAttributes.attributes.SEARCH_QUERY.Value, as explained above), and filter only those two properties. However, if your target system returned a 'Name' property, you should transform it to 'NaME' to match exactly what was requested by OpenIAM.

For writing logs, you can use Write-DebugLog, Write-InfoLog, Write-WarningLog, or Write-ErrorLog depending on the severity. Logs will be sent to the target location defined inside the Connector.config file.

Installing the generic connector

The generic connector is installed the same way as any other connector.

1. Click on the installer file and launch the installation.
2. Choose a folder to install the connector and click Next.
3. Choose the desired options for logs and debug logs, then click Next.
4. Out-of-the-box, you can specify the hostname of the OpenIAM or RabbitMQ host on the next screen. Here, you can also test the connection by clicking Test Connection. The rest of the parameters are pre-configured but can be customized as needed. Click Next after checking the connection and setting the parameters.
5. Click Install to complete the installation.

After the installation is successfully completed, the connector folder will appear in the specified directory. Inside this folder, you will find a Connector.config file. This file contains a template of the connector script with a brief explanation of the parameters and their usage to implement the needed logic. Depending on the operation, you can modify these functions. Inside the functions, you will see the global variables and properties used. There are also several examples of what can be accessed and used for specific logic. The functions, variables, and parameters are also described earlier in this document.

With this information, you can start writing your logic based on the ability to access these parameters from the managed system level or a policy map. The connector core will handle the rest of the operations. For example, if you need to stop an operation, you can throw an exception in the script, and the connector will take care of the rest, including formatting an appropriate response to OpenIAM. The connector will communicate with the server and perform the necessary actions based on what you included in the script.

Hence, a generic connector is exactly the same as any other connector, with the exception that you have the power to create your own logic using the Connector.config file script after installation.