Connector/Agent functional overview

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.