Supported operations

The following operations can be defined in your script. If you omit an operation, the connector will report that it is unsupported.

Password verification operations

verify
Purpose: Checks if a given password is the correct, current password for an account. If the application supports the concept of intruder lockout and the verification fails, the intruder lockout counter is incremented.
Returns: Returns 1 for success and 0 for failure.
adminverify
Purpose: Checks if a given password is the correct, current password for an account without triggering an intruder lockout if the password is not correct.
Returns: Returns 1 for success and 0 for failure.
Notes: If the application does not support the concept of intruder lockout, then this operation should not be used.

Password reset operations

change
Purpose: Changes the password for an account, from a known current value to a desired new value. If the application supports the concept of intruder lockout, then the intruder lockout counter is cleared and the account unlocked. If the application supports the concept of password expiry, then the expiry date is set according to the expiry policy of the application.
Returns: Nothing.
Notes: This operation differs from the reset operation in that this operation requires the user’s existing password to be provided during the reset process.
reset
Purpose: Administratively resets an account’s password to a new value. If the application supports the concept of intruder lockout, then the intruder lockout counter is cleared and the account unlocked. If the application supports the concept of password expiry, then the expiry date is set according to the expiry policy of the application. Disabled accounts will remain disabled.
Returns: Nothing.
Notes: This operation differs from the change operation in that this operation does not require the user’s existing password.
resetexpirepw
Purpose: Administratively resets an account’s password to a new value and expires the account’s new password, so that the user is forced to change his password the next time he logs in.
Returns: Nothing.
Notes: If the application does not support the concept of password expiry, then this operation should not be implemented.
verifyreset
Purpose: Verifies if the account’s password matches the new password, and if the verification fails, administratively sets it to the new password. If the verification succeeds, then the reset is not necessary, and the operation returns success.
Returns: Nothing.
Notes: This special reset operation is generally only used by the Password Manager service (idpm ) to improve queue processing performance.
updatesubscriber
Purpose: Updates subscriber attributes, typically password.
Returns: Nothing.
Notes: This operation is similar to the reset operation except that in addition to the reset password replacement string, the following replacement strings must be provided:
%k_resourceType% the same resource types provided in listsubscribers.
%k_resourceURI% the unique URI of the subscriber to be updated. This is the same as the uri column in listsubscribers.
Warning
Functions which reset or verify passwords in scripts used by Bravura Privilege for password randomization must always report the result of the reset or verification accurately. Inaccurate status information may result in checked out passwords not working; additionally, if the credential used to manage the target system is being randomized, Bravura Privilege may invalidate its own managed system credential when an erroneous status is returned. Do not assume scripted password changes are always successful; always check return codes.

Account enable/disable operations

When an account is disabled, a user cannot log in using that account even if the user knows the correct password for the account.

If the application supports the concept of account enable/disable status, then all three of the following operations should be implemented. If the application does not support this concept, then none of the operations should be implemented.

Most applications differentiate between an enabled/disabled state and an unlocked/locked state. If your application does not differentiate between these two concepts, you can choose to implement either set or both sets of operations with the same statements.

isenabled
Purpose: Checks if an account is enabled.
Returns: Returns 1 if the account is enabled and 0 if it is disabled.
enable
Purpose: Enables an account.
Returns: Nothing.
disable
Purpose: Disables an account.
Returns: Nothing.

Intruder lock-out operations

When an account is locked out, the user cannot log in using the account even if the user knows the correct password for the account.

If the application supports the concept of intruder lock-out status, then all of the following operations should be implemented. If the application does not support this concept, then none of the operations should be implemented.

Most applications differentiate between an enabled/disabled state and an unlocked/locked state. If your application does not differentiate between these two concepts, you can either choose to implement either set or both sets of operations with the same statements (if applicable).

islocked
Purpose: Checks if an account is locked.
Returns: Returns 1 if the account is locked out and 0 if the account is not locked out.
lock
Purpose: Locks an account (sets the intruder lockout).
Returns: Nothing.
unlock
Purpose: Unlocks an account (clears the intruder lockout).
Returns: Nothing.

Expiry operations

There are two types of expiry relating to accounts: password expiry and account expiry. When the password is expired, the application will force the user to change it during his next log in after he has successfully authenticated using his current password. When an account is expired, it is no longer usable, and the user cannot log in using the account even if he knows the correct password for the account.

If the application supports the concept of either password expiry or account expiry, then all of the related operations should be implemented. If the application does not support either concept, then none of the related operations should be implemented.

Most applications differentiate between password expiry and account expiry. If your application does not differentiate between the two concepts, you can choose to implement either set or both sets of operations with the same statements (if applicable).

isexpiredpw
Purpose: Checks if an account’s password is expired.
Returns: Returns 1 if the condition is true and 0 if it is false.
expirepw
Purpose: Expires an account’s password.
Returns: Nothing.
unexpirepw
Purpose: Unexpires an account’s password.
Returns: Nothing.
isacctexpired
Purpose: Checks if an account is expired.
Returns: Returns 1 if the condition is true and 0 if it is false.
expireacct
Purpose: Expires an account.
Returns: Nothing.
unexpireacct
Purpose: Unexpires an account.
Returns: Nothing.

Listing operations

All of the listing operations described below are expected to return one or more rows of data. If an operation returns no rows, then the operation is considered to have failed. See Return KVGroup for information about the return KVGroup.

listusers
Purpose: Lists accounts on the target system, and the attributes for each account.
Returns: Returns a row for each user, with the first column being the user’s long ID, the second being the user’s short ID, and the third being the user’s full name, and the rest being attributes. Nothing returned indicates failure.
Notes: This operation requires a "returns" KVGroup that identifies attribute names. The "returns" KVGroup must include the LONGID, SHORTID, and FULLNAME attributes as the first three attribute names.
listgroups
Purpose: Lists groups.
Returns: Returns a row for each group on the target. The first column is the long ID of the group, the second column is the group description, the third column is the long ID of the group owner, the fourth column is the short ID of the group, and the fifth column is a flag indicating if the group owner is a group, "1" or "true" or "t" indicates it is a group, otherwise it is a user. Nothing returned indicates failure.
Notes: This operation is a sequenced operation that is followed by the invocation of the listmembers operation. This operation must only return a maximum of one owner for each group.
listmembers
Purpose: Lists members of a managed group.
Returns: Returns a row for each user that is a member of the group. The first column returned is the long ID of the user that is a member, and the second column indicates if the member is a user or a group, "1" or "true" or "t" indicates the member is a group, otherwise it is a user. Nothing returned indicates failure.
Notes: This operation is a sequenced operation that is preceded by the invocation of the listgroups operation.
listcomputers
Purpose: Lists computer objects on a target system.
Returns: Returns a row for each computer object on the target system. The first four columns must be:
- id Univerally unique identifier for this computer
- name Descriptive name for this computer
- restype the resource type, can be accessed using %k_resourceType% , or a column from real table
- disabled Flag to indicate if this computer is disabled (0=false, 1=true)
You can add columns to specify any computer attributes you want to list, for example:
```
"column" = "ip"
"column" = "os"
"column" = "location"
```
Notes: A replacement string should be passed into the operation, %k_resourceType% , which will be either "ls_compwkstn" or "ls_compsvr" to distinguish between listing workstations and server computers.
listsubscribers
Purpose: Lists subscriber accounts on a target system.
Returns: Returns a row for each subscriber on the target system. The first seven columns must be:
- id Universally unique identifier for this account (optional - if empty will auto-generate to longid+targetid)
- uri Unique identifier for the subscriber
- restype the resource type, can be accessed using %k_resourceType% , or a column from real table
- disabled Flag to indicate if this account is disabled (0=false, 1=true)
- acctid Account name as seen by the subscriber using it
- longid Long identifier for the account; for example FQDN
- shortid Short identifier for the account; for example CN
You can add columns to specify any subscriber attributes you want to list, for example:
```
"column" = "sid"
"column" = "domain"
"column" = "Comment"
"column" = "islocal" 
```
Notes: A replacement string should be passed into the operation, %k_resourceType%, which will be one of:
- ls_taskacct Task subscriber
- ls_iisacct IIS subscriber
- ls_comacct DCOM/COM+ subscriber
- ls_scmacct Service subscriber
- ls_cusacct User defined subscriber
- ls_admmember Administrative group member

Account creation operations

The typical behavior of all built-in connectors is to copy a template account, and then update the attributes of the copy. Scripted connectors are capable of creating accounts using that technique, but they can also bypass the use of template accounts, simply by not including the checktemplate operation in the script.

When the account creation operation is expected to use a template, and the group membership of the template needs to be included during the create operation, then checktemplate should return the group long IDs of the template in an attribute, which the create operation can then parse and add to the new account.

checktemplate
Purpose: Checks if the template to be copied exists on the target system and returns attributes of the template account if it exists.
Returns: Returns a single row and a column for each attribute of the template account. The first three columns returned must be the long ID, short ID, and the full name of the template account. After that, other columns can be returned for other attributes. Nothing returned indicates failure.
Notes: This operation is a sequenced operation that precedes the execution of the create operation. This operation requires a "returns" KVGroup that identifies attribute names. The "returns" KVGroup must include the LONGID, SHORTID, and FULLNAME attributes as the first two attribute names.
create
Purpose: Creates a new account on the target system. This operation creates the account (possibly using a template for some attribute values), then sets other attribute values – including the password for the new account.
Returns: Nothing.
Notes: This operation is a sequenced operation that first attempts to execute the checktemplate operation.
usergroups
Purpose: List group membership of an account.
Returns: Returns a row for each group membership of the user. Each row must be the long id of the group. Nothing returned indicates failure.
Notes: This operation is a sequenced operation that is called after the create operation.

Account delete operations

The typical behavior of all built-in connectors is to first ensure that the account being deleted exists. For scripted connectors, this is accomplished by the use of the checkuser operation.

delete
Purpose: Deletes an existing account on the target system. The typical behavior is to first ensure that the account being deleted exists.
Returns: Nothing.

Account modification operations

The following operations fall into the category of modification, because they are all used to modify an existing account’s properties (attributes, group membership, long ID, or container).

If this application requires group operations, then both groupuseradd and groupuserdelete operations must be implemented.

update
Purpose: Updates attributes for an existing account.
Returns: Nothing.
Notes: This operation is a sequenced operation that first executes the checkuser operation.
groupuseradd
Purpose: Adds an account to a group.
Returns: Nothing.
groupuserdelete
Purpose: Removes an account from a group.
Returns: Nothing.

Group provisioning operations

If this application requires group provisioning operations, then both the groupcreate and groupdelete operations must be implemented.

groupcreate
Purpose: Creates the specified group.
Returns: Nothing.
groupdelete
Purpose: Deletes the specified group.
Returns: Nothing.

Other operations

The userattributes operation is very similar to the checktemplate operation.

checkuser
Purpose: Checks if the account exists on the target system, and if it exists, returns the attributes of the account.
Returns: Returns a single row and a column for each attribute of the account. The first three columns returned must be the long ID, short ID, and full name. After that, other columns can be returned for other attributes (groups should be returned in a single attribute). Nothing returned indicates failure.
Notes: This operation is a sequenced operation that is called by the delete, update, and userattributes operations. This operation requires a "returns" KVGroup that identifies attribute names. The "returns" KVGroup must include the LONGID and SHORTID attributes as the first two attribute names. Any custom attribute that is defined must be returned using checkuser. This operation should be called after the create operation.
userattributes
Purpose: Lists attributes for a specified account.
Returns: Returns single row and a column for each attribute of the account. The first three columns returned must be the long ID, short ID, and fullname. After that, other columns can be returned for other attributes. Nothing returned indicates failure.
Notes: This operation is a sequenced operation that first calls the checkuser operation to ensure the account exists. This operation requires a "returns" KVGroup that identifies attribute names. The "returns" KVGroup must include the LONGID, SHORTID and FULLNAME attributes as the first three attribute names.

Custom operations

You can define custom operations in the database script file with prefix custom_; for example:

  operation "custom_customop" = {
  "outputType" = "xxx"
  }

The "outputType" can be defined in three types:

"outputType" = "none" – no data will return
"outputType" = "single" – single row of data will return in KVGroup output
"outputType" = "multiple" – multiple rows of data will return and will be written to file specified in "customfilename" in agent input. "customfilename" is required in this type, and the operation will fail without providing the file.

In this section:

Supported operations

Warning

Search results