Custom Connector Building

The connectors communicate with Bravura Security Fabric through proprietary API so input and output to the connectors is handled in a standard way. The product executes the connectors through standard functionality exposed through the UI or can be customized programmatically via Python. The client calling API and the underlying connector API in our programmatic connectors preserve connector compatibility. As a result, connectors written in the past are generally fully compatible in an upgrade. Due to this separation of connectors from product, newer connectors and the connector pack, generally run in older versions of the product without issue. The reverse is not true, however, as new functionality added to the product often relies on lock step functionality added to the connector pack.

Most connectors list account objects and act on those account objects with an array of other operations. Similarly, most connectors list group objects and act on those group objects.

Operations include, but are not limited to:

In addition, listing resource objects, such as computers or tokens, is possible through connectors.

In any customized script the serverinfo (server information) must succeed; if it is missing or fails, the listing operation will fail. Whichever types of listing are enabled for the Target system information must succeed; for example: if you have "list accounts" checked and the connector returns ACOperationNotSupported when listing accounts, that is treated as a listing failure.

For a full list and explanation of each connector operation, see Connector operations.

See also the Python Agent API Reference for details on specific connector operations.

It is also entirely possible to build a connector that deviates from typical behavior. For example, you could create a connector that operates on a custom operation, not explicitly exposed in the product but is called through workflow in a complicated use case. There are also interceptor connectors, which are intended to be called in exit traps and generally act on a ticketing systems like ServiceNOW, by opening and closing tickets.

For this document, we will focus on the typical use case of listing of account objects and group objects and the operations that act on these objects.

When developing connectors, be aware that the terminology may differ between the Bravura Security product and the target system. From the Bravura Security product side it may appear like we are listing groups, but from the external program this might be viewed as collecting user role information, even though these semantics are similar enough as to not be an issue. Also understand that the operations may be asymmetrical in meaning, for example, unlocking an account in Bravura Security terminology means that the intrusion lock is reset, however, in some targets, unlock can mean to enable an account. Take the time to understand how the Bravura Security product objects and operations map to the end target.

A connector is identified by its type name which is internally known in the product as its platform name. When you set up a target under Manage the System > Resources > Target systems > Manually defined the connector is selected when you choose the Type.

Also note that a connector’s type or platform is further grouped into common categories such as Network Operating System, in the example above.

The type of connector you select for your target system affects the required fields needed in the target address configuration. The target address configuration options are used to configure connector behavior in the UI. After setting up a target under Manage the System > Resources > Target systems > Manually defined and choosing your Type, you can select the Change button on the Address field and configure the target address options.

It is essential to understand these concepts before connector development. Developing a connector involves defining a connector type, setting its category and defining its target address options.

The auto discovery and account policy sections gray out functionality if certain features are not exposed. For example:

The Allow users to change passwords or Allow users to verify passwords options require both the reset and verify operations respectively. The Allow users to unlock accounts option requires the unlock/islocked operations. The Allow enabling accounts option requires the enable/disable/isenabled operations.

Provide a connector file along with your Python script and any files you might import with your Python script. This file is placed beside your script and used to associate your custom Python connector with a platform type and define a category and short description. For example, the agtsfrest agent connector file looks like this:

# KVGROUP-V2.0
 agtsfrest = {
 agent = agtpython.exe;
 script = agtsfrest.py;
 category = HRMS;
 platform = SFREST;
 description = !!!PLATFORM_SUCCESSFACTORSREST_DESC;
 system = true;
}

In your connector file, since you are writing a Python connector, the agent key value will always be agtpython.exe. The script key value specifies the name of your Python script. The category key value specifies the category. This is used when grouping your connector in the pulldown menu item when targeting your connector. Allowed categories are as follows:

The platform key value defines a short uppercase name for your platform that will be used internally in the product to uniquely identify your platform. Finally, the description key value allows you to specify a short description that gets displayed on the pulldown menu item when targeting your connector.

Credentials are grouped into administrator and system credentials. The primary credentials are the administrator and if there are a pair of credentials, the secondary credentials are the system. What is considered primary and secondary credentials is arbitrarily up to the connector developer. Historically, there has never been a connector with more than two credentials.

The Python credential variables are special in that they are encrypted until used. A best practice during development suggests retrieving credentials only when they are needed, reducing the window where credentials can be compromised. Additionally, there are security implications during development where passwords may be exposed through logging. After development is completed ensure that credentials are not logged or written out to disk.

Generally, development of a connector starts with the serverinfo operation and list user operation, in that order. The target system Test connection tab can be used to test connectivity by running the serverinfo operation. This is followed by testing the list operation with the "Test user list" operation, on the same Test connection page. These tests do not catch all the errors, but it is an easy sanity check when building your connector and can be safely run in production environments.

For other operations, it is recommended when developing and testing a connector that you are not using a production target system.

Multiple credentials (admin and system)

Both the admin and system creds handle multiple credentials by attempting a connect operation over both the admin and system creds until either an ACSuccess or ACNotConnected are returned. The logs indicate an connection attempt failure for each credential with the following logging:

Cannot connect to address [Address] by using [adminID] [sysID]

The return code ACNotConnected is a special case to indicate all connection attempts fail and this error code is used specifically to attempt the next failover in the proxy list. When implementing the connect function, do not return ACNotConnected for credential check failure.

Looking at the agtpython-simple.py comment section, the sample script documents:

Several useful variables for inputs from the Bravura Security product.

Following the comment section are code samples for integrating all the operations, generally in the order of precedence.

The addressattr definition allows you to expose target address attributes in your custom connector. These address attributes are parameters that expose configuration when targeting your connector. For example, our SuccessFactor EC rest connector (which is written in Python) provides the following target system address configuration:

And this is exposed via the following addressattr function:

def addressattrs(cinfo):
 """ Target address settings must specify:
 """
 agent.addAddressAttr(
   
   "url", "SuccessFactors OData REST API URL", "string", "", True)
   
 agent.addAddressAttr("proxy", "Proxy server to use", "string", "", False)
 agent.addAddressAttr("groupTypes",
        "GroupType(s) to list",
        "string",
        "permission",
        False)

The connect/disconnect definitions allow you to implement the connection/disconnection logic to your target. These definitions are called automatically before and after an operation function such as listusers or reset are called. The provided sample script as-is does not connect to anything but shows what variables are useful during connection. Note that cinfo Python dictionary often exposes many of the inputs from the connector framework. There are also commented out lines in the sample which present how to validate addressattr values passed in from the target system address configuration, such as port numbers. Also noteworthy is the log.info example to log to our logging facility (to the idmsuite.log):

log.info("connecting as adminid [{0}] sysid [{1}] with address line [{2}] "
       "timeout [{3}] settings [{4}]".format(adminid,
                                 sysid,
                                 address,
                                 timeout,
                                 settings))

And the agent.error example to return an error code and an error message back through the connector framework to the caller of the connector:

agent.error("Port number option must be defined");
 return ACUnknownError

The serverinfo function is mandatory with the list operation. The serverinfo operation is also used to test your connection on the Test connection tab of your target configuration in the product UI. This operation, and the function itself returns general information on the target, such as its version or any general functionality that this target might offer. Generally, the information returned is inconsequential and returning any version value is fine. As is the case in the provided sample using the agent.serverInfo callback:

attr_dict = {'attr1': ['value1-1'], 'attr2': ['value1-2']}
agent.serverInfo("1.1", attr_dict)

The listusers,listgroups,listcomputers,listsubscribers definitions provide the ability to return list information on the associated objects. The samples fill in mock data, but it shows how you can return account/group/computer/subscriber information through the connector framework using the provided agent.addAccount/agent.addGroup/agent.addComputer/agent.addSubcriber callbacks. These callbacks write the object information into the connector sqlite db files stored in psconfig, and these files are read by the iddiscover service into the product database.

There are other operations in the sample script, for example, verify, change, reset, expirepw, etc, that are unimplemented and return success. The operations and their respective Python definitions are generally considered push operations. Sometimes, they return attribute information, but generally, their main intent is to update the end target. As a result, they are generally easier to implement except for create and update.

Finally, the custom operations and the challengeresponse operation require detailed knowledge of the product and are complicated to implement. These are not operations we recommend writing yourself.

Prerequisites

Bravura Security Fabric is installed.

Steps

The primary keys of a connector are:

The stableid, longid and shortid all must uniquely identify an object. In other words, there cannot be duplicates across multiple objects per target.

Selective attribute listing and incremental listing are another layer of complexity in writing a connector. Generally, these are used to enhance performance. These can be exposed in your custom connector but generally, they are only warranted if your connector’s performance is a concern. Contact Bravura Security support for an explanation if this is an improving connector performance.

The connector list file contains the following tables:

Prerequisites

Use the target configured in Demo/Lab: Targeting with SQLite example .

Steps

The following are some useful SQL Queries when working with connector list db files:

When running commands that include Python that ties in with Bravura Security products, an instance command prompt is needed.

To open a new instance of the command prompt, search cmd and select Bravura Security Fabric Command Prompt.

Notice that now your instance name appears at the start of your command prompt line.

When testing to see if a script or feature is working correctly in Bravura Security Fabric you may find it useful to clear out the logs so that you can trigger the event you are troubleshooting and see what processes are succeeding and failing. To clear these logs, we complete the following command in an instance prompt:

In Windows File explorer, when you navigate to <Program Files path>\Bravura Security\Bravura Security Fabric\Logs\<instance> you will notice that the idmsuite.log file has been cleared. Now you can run the event you are trying to troubleshoot and see the resulting logs more clearly.

Each time an operation is executed in an agent, a PerfConnector log line is issued. These are often useful to track complicated workflows. In the idmsuite logs, look for something like the following log line:

Perf: PerfConnector. Address: {[server=cpcpk1ci.cpggpc.ca;system=00;client=100;version=7.5;resetmethod=loginreset;usecuagroups=false;nocache=true;gettableswork=true;unlocktype=islocked;listuserselectionrange=[LOGONDATA|UFLAG|I|NE|32|;LOGONDATA|USTYP|I|EQ|A|;];]}
      | AdminID: {ZCHITACHIP} | Duration: {135} | Event: {connector-operation} | Message: {} | Operation: {listgroups} | Result: {0} | SysID: {} | TargetID:
      {SAP_PK1_100}

This shows the address line, the operation, the message, and the result code from the operation.

There may be times where your script/connector/task is failing, but the logs are not verbose enough to tell you where. In this case we can increase the debugging level by running the following command in an instance prompt:

This will give you logs with more detail about each process that runs with Python so that you can look deeper into where the issue lies. We use agtpython as the program because if you look within the <instance>/agent directory, there are many .exe programs contained within that folder and agtpython is the connector program that runs Python scripts for "Python script" target types. The reason we define the program instead of increasing the level for everything is because if you increase debugging for all programs and processes to level 5, your log file will be very large. If allowed to run at level 5 for a long period of time, this will fill up your log files and memory and start to impact the usability of Bravura Security Fabric .

This method was demonstrated in Demo/Lab: Pstee and replaying operations on connectors . If the idmsuite logs are not giving you enough information, it is often useful to enable pstee to examine the communication between Bravura Security Fabric and the connector.

For example, when you are testing a target connection by pressing the "Test credentials" button in the Test connection tab of the target configuration page (or any other UI button in the product that interacts with the connector), Bravura Security Fabric is calling out to the connector. It is important to note, once you capture that input message, you can keep using that input message in a command prompt instead of having to repeat complicated reproduction steps in the UI.

This communication both to the connector and from the connector is in the format of a KVGroup. KVGroup format is a proprietary Bravura Security format which is somewhat similar to JSON.

This communication is done using stdin and stdout via command pipes. What this means is when a connector is called, an input stream (also known as an input KVGroup) is sent to the connector. The connector executes the operations in the input stream and sends an output stream (also known as an output KVGroup). These can be pasted in the command prompt after invoking an agent, or they can be streamed to the agent as files using a redirector or a pipe. For example, a redirector execution of a connector might look like this:

agtpython < input.kvg

And a pipe execution might look like this:

type input.kvg | agtpython

The following example outlines the process of pasting the input KVGroup into an agent’s stream: