> For the complete documentation index, see [llms.txt](https://docs.openiam.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.openiam.com/connector-configuration/microsoft/15-powershell-generic.md). # Building a custom PowerShell connector This page describes how to build a custom PowerShell connector for OpenIAM using a PowerShell generic connector. 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 '', this property would contain '' in this case. * `$headerAttributes.OriginalIdentityValue` contains the principal name of an identity used for renaming operations. For instance, if OpenIAM requests renaming '' to '', it would send two attributes: `$headerAttributes.OriginalIdentityValue` with '' and `$headerAttributes.IdentityName` with ''. * `$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. {% stepper %} {% step %} **Launch the installer** Click on the installer file and launch the installation. {% endstep %} {% step %} **Choose the install folder** Choose a folder to install the connector and click **Next**. {% endstep %} {% step %} **Choose the logging options** Choose the desired options for logs and debug logs, then click **Next**. {% endstep %} {% step %} **Point it at OpenIAM** 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. {% endstep %} {% step %} **Install** Click **Install** to complete the installation. {% endstep %} {% endstepper %} 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. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.openiam.com/connector-configuration/microsoft/15-powershell-generic.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.