The Scripting driver provides a complete Microsoft VBScript API for interacting with identity management systems whose tools (including APIs) are available on Windows. The Identity Vault and Identity Manager can run on any supported operating system. Identity Manager can communicate with any supported system on which the driver is installed via an encrypted network connection.
Before beginning script development, review the preceding topics in this section for information on defining what data is synchronized between identity management systems.
With additional development work, the driver can also be adapted to support any scripting language that supports command line operation.
Developing a custom driver with VBScript is discussed in this section. Topics include
To change the data in your external application, you need to know how to use the application’s tools or API (Application Programming Interface). These tools must provide automated operation and not require user input.
An application often provides command line tools. These tools are manually executed from the Windows command prompt, and they can be executed from scripts. For example, suppose the application provides a tool to add identities with a program called appadd.exe.
appadd -n "Bob Smith" -t "818-555-2100"
This command adds an identity named “Bob Smith” with the specified phone number. The strings following the program name are called parameters or arguments. The Scripting driver provides a function called IDMExecute to execute external programs.
CommandLine = "appadd -n " & UserName & " -t " & PhoneNumber ExitCode = IDMExecute(CommandLine)
There is also a function called IDMExecuteIO that allows you to pass information on the program’s standard input, and receive output from the program’s standard output and standard error.
Dim Input(1) Input(0) = "USERNAME=bobsmith" Input(1) = "TELEPHONE=818-555-2100" Output = IDMExecuteIO("appadd", Input) ExitCode = Output(0)
IDMExecuteIO’s first parameter is the command line, and its second parameter is an array of strings (or Empty) that is submitted as lines to the command program. It returns an array, the first element of which is the program’s exit code, and then strings that represent lines returned on the program’s standard output and standard error.
For command line tools, you can construct the command line’s parameters using the values passed to the script, then execute the program.
Another way to modify application data is through Windows COM (Common Object Model) objects. Consult your application’s documentation to see whether it exposes any COM objects. These COM objects can be loaded directly in VBScript:
Set AppObject = WScript.CreateObject("MyApplication.MyObject") AppObject.AddIdentity("Bob Smith", "818-555-2100")
There are no guarantees regarding what types of tools are available, or even whether any tools are available. You must determine if sufficient tools are provided by the application. If they are not, you can contact the application’s developers and request that such tools be made available.
You should make a list of what tools can be used for each event type. The application might provide one program that can be used for any event type, or it might provide multiple tools.
You also need to determine what tools are available for monitoring event changes in the application. The Scripting driver works on a polling system. It periodically calls a polling script to determine what has changed in the external application. You can use the following ideas for monitoring changes:
The first time the polling script is run, a list of identities and relevant attributes is read from the application using an application-provided tool. This list is stored as a file. On subsequent polls, a new list is generated and compared to the old list. Any differences are submitted as events to the driver.
The application provides a tool that allows you to request all identities that have changed after a certain point in time. The polling script requests events that have occurred since the previous poll.
The application allows a script to be run when an event occurs. You write a script that stores the event data into a file. When the Scripting driver polling script runs, it consumes this file and submits the data as an event to the driver.
Monitoring the application’s changes might be the most difficult aspect of developing your driver. You must study your application’s tools to determine the best way to achieve synchronization.
At this point you should have a list of what data will be synchronized, how events will be handled, and what application tools are available. It is time to develop the heart of your driver in policies and scripts.
Many types of tasks can be handled in driver policies. You can import the driver configuration provided with the Scripting driver, and then edit policies in Novell iManager. You can also edit policies and simulate their operation in Novell Designer. The extensive functionality of policies is outside the scope of this document, so you should refer to your Novell Identity Manager 3.6.1 Policy guides for help.
Tasks that don’t interact with the external application might be more suited to policies. On the other hand, if you are more familiar with your scripting language than policies, you can develop your driver more quickly by using scripts.
Event data is submitted to the scripts in name/value pair format. This format consists of lines containing a name, an equal sign (=) and a value. Therefore, each line is a name/value pair. Each name/value pair is unique, but there can be multiple name/value pairs with identical names but different values.
ASSOCIATION=BobUser ADD_TELEPHONE=818-555-2100 ADD_TELEPHONE=818-555-9842
You typically don’t have to worry about the format. The script library provides functions for retrieving event data.
After all policy processing is complete, Identity Manager submits the event in XML format to the driver shim. The driver shim submits the event data to the scripts.
In the default Scripting driver, the Subscriber.wsf script in the scripts folder is called. This script does some preliminary processing, and then calls a routine from an included script. The included scripts correspond to the Subscriber event types: Add.vbs, Modify.vbs, ModifyPassword.vbs, Delete.vbs, Rename.vbs, Move.vbs, and Query.vbs.
For each event type, you should retrieve the information you need from the event data, submit changes to the external application using application-provided tools and return a status (such as success or failure) to Identity Manager.
Event data is retrieved primarily using the IDMGetEventValues function. This function returns an array of values corresponding to the name specified as the function’s parameter. (IDMGetEventValue is available for single-valued items.) The following table shows many item names.
Table 5-19 Item Names
The association value indicates which identity has been changed. If the identity has no association, an association must be generated for it using an implementation-specific rule that you have adopted. When Identity Manager processes an event for an identity with no association, it executes the driver’s Matching policy. This policy attempts to match the event’s identity to an identity on the external application’s system. Doing this usually involves executing a query. The default Matching policy included with the Scripting driver queries for matching Users and Groups based on the CN attribute. If the event’s identity matches an identity on the external application, both identities must be assigned the new association. Assigning this association can be done as part of the query-handling script. (Handling queries is discussed in Handling Query Events.) If no identity matches, an Add event is issued, and the new association can be assigned as part of the Add event-handling script:
IDMSetCommand "ADD_ASSOCIATION" IDMWriteValue "ASSOCIATION", MyAssociation (etc.)
The example above also illustrates the IDMSetCommand function. This function sets a command value which indicates what action Identity Manager should perform. The ADD_ASSOCIATION command assigns an association to an identity, as discussed above. The Subscriber can also issue MODIFY_ASSOCIATION and REMOVE_ASSOCIATION commands.
On the Subscriber channel, you often do not need Identity Manager to perform an action, but simply need to report a status. The IDMStatus subroutines noted below can be used to indicate a status to Identity Manager. They take a message to be logged as the parameter.
Table 5-20 Subroutines
IDMSetCommand and/or a status subroutine must be called before specifying values with IDMWriteValues. IDMWriteValues (or its single-valued version IDMWriteValue) is used to set values to return to Identity Manager. It is passed a value name and an array of values. In the ADD_ASSOCIATION example above, IDMWriteValue is used to set the ASSOCIATION value. You can specify values for items listed in the table above.
For Query events, Identity Manager submits values that define the parameters of a search of the external application’s identity management system. Queries are usually issued from the policies you have defined for your system. The table below specifies values that can be specified in queries. Not all values are relevant to your external application.
Table 5-21 Query Values
Execute the query against the external application using application-provided tools. Then return each identity by setting an INSTANCE command, followed by relevant values from the list below.
Table 5-22 Query Values
After returning all identities, call IDMStatusSuccess to indicate a successful query.
Below is a more detailed summary of the actions to take for a non-Query event.
Gather information about the event using IDMGetEventValues. Return a warning or error if there is a problem.
Submit the event data to the external application using application-provided tools.
Set a command using IDMSetCommand and/or a status with the IDMStatus subroutines, based on the result of the event.
Set event values with IDMWriteValues.
If you have not already done so, set a status with an IDMStatus subroutine.
Below is an example of the Add.vbs script, which forms an association from an identity’s CN and class name, and uses a hypothetical tool called appadd.
Sub ADD ClassName = IDMGetEventValue("CLASS_NAME") CN = IDMGetEventValue("CN") PhoneNumber = IDMGetEventValue("Telephone") If IsEmpty(ClassName) Or IsEmpty(CN) Then IDMStatusError "Add event: missing CLASS_NAME and/or CN" Else Command = "appadd -n """ & CN & """ -t """ & PhoneNumber & """" ExitCode = IDMExecute(Command) If ExitCode = 0 Then IDMSetCommand "ADD_ASSOCIATION" IDMWriteValue "ASSOCIATION", CN & ClassName IDMWriteValue "DEST_DN", IDMGetEventValue("SRC_DN") IDMStatusSuccess "Add event succeeded" Else IDMStatusError "Add event failed with error code " & ExitCode End If End If End Sub
Handling a query is similar, except you return INSTANCE items rather than use other commands. Below is an example Query.vbs that searches an external application for a telephone number. It uses a hypothetical tool called appsearch.
Sub QUERY SearchName = IDMGetEventValue("SEARCH_ATTR_CN") If IsEmpty(SearchName) Then IDMStatusError "Query: no search value" Else Command = "appsearch -n " & SearchName Results = IDMExecuteIO(Command, Empty) If Results(0) = 0 Then Phone = Results(1) IDMSetCommand "INSTANCE" IDMWriteValue "CLASS_NAME", IDMGetEventValue("CLASS_NAME") IDMWriteValue "ASSOCIATION", IDMGetEventValue("ASSOCIATION") IDMWriteValue "ATTR_Telephone", Phone IDMStatusSuccess "Query succeeded" Else ' Return success with no results IDMStatusSuccess "Query succeeded (no matches)" End If End If End Sub
Events that occur on the external application are submitted to Identity Manager on the Publisher channel. The Scripting driver periodically polls the external application for events. How this poll detects events is implementation-specific and must be defined by you.
The Driver calls Poll.wsf to detect application events. Poll.wsf should be implemented as follows:
Use application-provided tools to detect events in your application. (See Step 2.)
For each event:
Call the IDMPublishInit function to set the appropriate command.
Call IDMPublishValues to set event values.
Call IDMPublish to submit the event to Identity Manager.
If there were events, call an IDMStatus function to report the status.
IDMPublishInit takes a command name as its single parameter. Below is a list of valid command names for IDMPublishInit.
Table 5-23 Command Names
Below is an example of a Poll.wsf that checks for a password change. It uses a hypothetical application tool called apppwd.
Results = IDMExecuteIO("apppwd --changes", Empty) For I = 1 To UBound(Results) ' Entries are in the format "association=password" Association = Left(Results(I), InStr(Results(I), "=")-1) Password = Mid(Results(I), InStr(Results(I), "=")+1) IDMPublishInit "MODIFY_PASSWORD" IDMPublishValue "ASSOCIATION", Association IDMPublishValue "PASSWORD", Password IDMPublish Next IDMStatusSuccess "Poll succeeded"
Events submitted using IDMPublish are processed through your driver’s Publisher channel policies. See the Novell Identity Manager 3.6.1 Policy guides for more information.
Another script executed in the Publisher Channel is Heartbeat.wsf. This script is executed when the Publisher channel is idle for the interval specified in the driver parameters. (You can set the interval to 0 so no heartbeat is issued.) You can use the heartbeat to check the availability of the external system or do “idle state” tasks. The IDMHeartbeatSuccess, IDMHeartbeatWarning, and IDMHeartbeatError subroutines can be used to indicate the result of the heartbeat. Below is an example based on a hypothetical tool called apphealth.
ExitCode = IDMExecute("apphealth") If ExitCode = 0 Then IDMHeartbeatSuccess "Heartbeat succeeded" Else IDMHeartbeatError "Heartbeat failed with error code " & ExitCode End If
The response to the heartbeat is implementation-dependent, and can be defined in policies or in the script itself. You could send a message to auditing using Novell Audit. You could store a value in a file, and have Subscriber scripts read the file and call IDMStatusRetry if they find that value in the file.
A driver has values known as driver parameters. The driver parameters are divided into driver settings applicable to the whole driver, and Subscriber and Publisher Settings for their respective channels. The IDMGetDriverParam, IDMGetSubscriberParam, and IDMGetPublisherParam functions can be used to retrieve these values. The table below shows parameters in the default Scripting driver. Other parameters can be added to the driver’s XML Configuration file (see “Managing Identity Manager Drivers” in the Novell Identity Manager 3.6.1 Administration Guide).
Table 5-24 Driver Parameters
In the following example, a script retrieves the Publisher polling interval.
PollingInterval = IDMGetPublisherParam("pub-polling-interval")
Scripts might need to retrieve information from the Identity Vault. They can do this by issuing a query.
Initialize the query with IDMQueryInit.
Set query search parameters using functions listed below.
Execute the query with IDMQuery.
Read the result (instance) using functions listed below.
Currently query support is limited. It will only return one instance based on the specified association or DN. (If both association and DN are specified, association is used.) The functions below allow you to retrieve information from the instance.
The following is an example of a query of the Identity Vault that retrieves the address and ZIP code for users living in Provo, Utah.
IDMQueryInit IDMSetQueryAssociation IDMGetEventValue("ASSOCIATION") IDMAddSearchAttr "City", "Provo" IDMAddSearchAttr "S", "UT" ' State IDMAddReadAttr "SA" ' Street Address IDMAddReadAttr "Postal Code" If IDMQuery Then Address = IDMQueryGetInstanceAttrValue("SA") ZIPCode = IDMQueryGetInstanceAttrValue("Postal Code") ' ... etc. ... End If
The IDMTrace function allows you to write a message to the Script Trace File specified in the Driver Parameters. Tracing is useful for script debugging and auditing.
IDMTrace "Trace message"
When developing scripts, you might need to do some debugging to track down problems. The following list indicates some facilities for debugging.
The Driver traces activity to its Trace file (logs\trace.log by default). The trace level setting in conf\wsdrv.conf controls how much debugging is written to the log.
The trace level is set using the -trace option in wsdrv.conf, for example. -trace 9.
You can view the trace file through a Web browser:
Use a Web browser to access the driver shim at https://driver-address:8091. Substitute the DNS name or IP address of your driver for driver-address.
Authenticate by using any username and the password that you specified as the Remote Loader password.
Click
.The IDMTrace function described above writes output to the trace file specified in the Driver Parameters (logs\script-trace.log by default).
The eDirectory tool DSTrace can be used to monitor Identity Manager activity. Set the tracing level for the Driver in iManager. DSTrace shows the XML documents being submitted to the Driver for events, and how Policies are evaluated. It also shows the status and message for each event.
The Status Log is written to logs\dirxml.log. It shows a summary of the events that have been recorded on the Subscriber and Publisher channels.
You can view the Status Log through a Web browser:
Use a Web browser to access the driver shim at https://driver-address:8091. Substitute the DNS name or IP address of your driver for driver-address.
Authenticate by using any username and the password that you specified as the Remote Loader password.
Click
.Although it is best to run the driver as a service in production environments, you can run wsdriver.exe as a standard program. When you do so, a console window displays trace messages (see above) for the driver. Also, text written to standard output from scripts (such as using WScript.Echo in VBScript) is displayed in this window.
VBScript programs can be debugged using programs such as Microsoft Visual Studio and Microsoft Script Debugger. Change the Script Command driver parameter to use the //x option: cscript //nologo //x. When the driver shim executes a script, you are prompted to debug the script execution.
The Scripting driver is installed by using a setup program. See Section 3.2, Installing the Windows Scripting Driver for information on installing the default driver.
To deploy your custom driver, the end user should first run the Windows Scripting driver installation program provided by the installation media (see Section 3.2, Installing the Windows Scripting Driver for more information.) This program installs core files needed by the driver. Then, your custom driver files can be deployed in any convenient way, whether through an installation program or even simply an archive file. The table below shows the directory structure below the installation directory and what files are installed.
Table 5-25 Directory Structure and Files
If you are using an installation program, you can obtain the driver’s installation path from the following registry value:
HKEY_LOCAL_MACHINE\SOFTWARE\Novell\Windows Script Driver\Path
Or for the x86 driver running an x64 version of Windows, use the path from the following registry value:
HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Novell \Windows Script Driver\Path
The formats of wsdrv.conf and schema.def can be viewed in Section 4.2, The Driver Shim Configuration File and Section 5.2, The Connected System Schema File.
If SSL encryption is desired for communication between the driver shim and Identity Manager engine, a certificate must be retrieved from the Identity Vault. Run the following command and follow the prompts to retrieve the certificate:
wsdriver.exe -s
The certificate will be stored in the keys\ directory. You must have LDAP with SSL available for the Metadirectory. When making an installation program for deployment, you might want to include this command as part of the installation:
To ensure that only authorized systems access the Metadirectory, a Driver Object password and Remote Loader password are used. Run the following command and enter the passwords at the prompts:
wsdriver.exe -sp
This action also can be incorporated into an installation program.
You should run a Scripting driver as a service. To the install the service, run the following command or include it as part of an installation program:
wsdriver.exe -installService
The service, which can then be run from the Services applet, can be removed as follows:
wsdriver.exe -removeService
You should distribute the XML configuration file that contains parameters and policies your driver needs. The user can then select it when installing your driver.