This chapter introduces Identity Connectors, a newly supported feature of Identity Manager. Connectors provide an alternative to resource adapters for managing identities and other object types in native resources. This chapter includes the following connector-related topics:
For updated information on identity connector development and implementation issues, a road map of connector development, and code downloads, visit https://identityconnectors.dev.java.net.
An identity connector is a component, similar to a resource adapter, that provides a link between Identity Manager and a native resource, such as a database, LDAP, or an ERP system.
Identity connectors provide advantages over resource adapters, including the following:
Simplified deployment and management because connectors are less tightly bound with Identity Manager than resource adapters. By placing Java connector bundles in the appropriate directory within your web application, or placing .NET bundles in the appropriate directory in a remote .NET directory, you can extend on-demand the types of native resources that you can manage. Identity Manager automatically detects any newly deployed connectors.
Connector release cycles do not rely upon Identity Manager release cycles. Connector releases can differ from Identity Manager releases , and you can add or update connectors in your deployment with less dependence on the particular version of Identity Manager you are currently using.
Identity Manager loads each connector in a separate class loader. This enhances support for using multiple versions of a native API from within a single Identity Manager server.
Use of the separate and less complex identity connector SPI to develop connectors (Java or .NET). You do not need to know or use any Identity Manager APIs.
Connectors will eventually replace resource adapters. For this release, however, Identity Manager will continue to support all previous resource adapters. Although it is not strictly required to migrate to the connector equivalent when one is available, it is recommended.
When there is a new connector type available that can replace an existing resource adapter, a migration path is provided to enable customers to switch over to use the connector.
In general, the greater the number and the more complex your customized forms and workflows, the more complicated the conversion process. To prepare to migrate from an adapter-based resource to a connector-based one,
Evaluate all existing forms and workflows that are related to the migrated resource for instances where searchFilter is set to a string.
Replace each occurrence with connectorFilter. The value of the connectorFilter entry will be an instance of a filter, which is made by using the FilterBuilder class by an <invoke>.
Do not perform this migration in a production environment. The migration does an in-place upgrade of the existing resource, changing it to use the connector instead of the previous resource adapter. All previous user account assignments to the resource will remain after the migration. While considerable effort is made in the migration to preserve backward-compatibility, it is recommended that the converted resource be tested before promoting to production.
Install the new connector (if not already installed)
Follow all the Identity Manager-specific installation steps documented for the connector, including importing any needed Exchange files.
Follow the migration procedure documented for the connector. Typically, this involves running a declared migration server task from Server Tasks > Run Tasks.
This section describes how to list the available connectors in your deployment, download connector code, install connectors, and register a connector server. It describes the following topics:
For this release, Identity Manager is shipping connectors for Active Directory and SPML2 resources. For more information about these connectors, see Chapter 57, Active Directory Connector and Chapter 58, SPML Connector.
Login in to Identity Manager Administrator Interface as an administrator who has the Resource Administrator capability
Select Resources > Resource Type Actions > Configure Managed Resources. The Resource Connectors area lists all the connectors that Identity Manager currently recognizes.
You can download additional Identity Manager-supported identity connectors from https://identityconnectors.dev.java.net.
An Identity Manager-supported Java connector is distributed as one jar file and one ZIP file. To download successfully, you must:
Copy the jar file binary into the WEB-INF/bundles directory of the Identity Manager web application
Extract the ZIP file into the Identity Manager web application.
For a more detailed explanation, see Installing a Java Connector.
An Identity Manager-supported .NET connector is distributed as two ZIP files. You must
Install one zip file under a remote .NET connector server.
Extract the additional ZIP file into the Identity Manager web application.
For a more detailed explanation, see Installing a .NET Connector.
A Java connector is delivered as one jar file and one ZIP file.
Stop your Identity Manager web application.
Copy the connector jar file into the WEB-INF/bundles directory of your Identity Manager web application.
Extract the connector ZIP file into the your Identity Manager web application directory.
Start your Identity Manager web application, and follow any additional connector-specific installation notes.
Your newly installed Java connector should now be visible to Identity Manager. Log in to the Identity Manager Administrator interface as an Administrator who has the Resource Administrator capability. Select Resources > Resource Type Actions > Configure Managed Resources, and confirm that the new Java connector is listed (associated in the displayed table with the LOCAL connector server).
(Optional) You may be required to import one or more Exchange files before using the new connector.
Success installation of a .NET connector requires these steps:
Note that before you install the .NET zip files, you must install and register a .NET connector server. A connector server manages one or more .NET bundles, and handles requests between Identity Manager and the .NET bundles. A .NET connector server is roughly analogous to the Identity Manager gateway. For more information, see
.NET connector bundles are delivered as two ZIP files.
You must install a .NET connector server before installing the .NET executable connector zip file.
To install the .NET connector's executable zip file:
If the connector server is already installed and running, stop the Connector Server service.
Unzip the ZIP file into the connector server installation directory.
Start the Connector Server service. If the connector server is not yet declared in Identity Manager, see Registering a Connector Server.
Stop your Identity Manager web application.
Extract the connector ZIP file into the your Identity Manager web application directory, and restart your Identity Manager.
Follow any additional connector-specific installation notes.
(Optional) You may be required to import one or more Exchange files before using the new connector.
After following this procedure, the new .NET connector should now be visible to Identity Manager. To confirm this, log in to the Identity Manager Administrator Interface as an administrator who has the Resource Administrator capability. Confirm that the .NET connector is listed in the displayed table with the appropriate connector server by checking Resources > Resource Type Actions > Configure Managed Resources.
You install and run a .NET connector server when using a .NET connector from Identity Manager. A connector server manages one or more .NET bundles, and handles requests between Identity Manager and the .NET bundles. A .NET connector server is roughly analogous to the Identity Manager gateway. However, you can easily extend the .NET connector server (to add additional connectors), and it is coded in .NET.
The minimal requirements for a machine that will run a connector server include:
Windows Server 2003 or 2008
.NET 3.5 or later
To install a connector server on a Windows host, refer to the connector server installation notes on https://identityconnectors.dev.java.net. You must record for later use the following information regarding your connector server installation:
Host name or IP address
Connector server port
Connector server key
whether SSL is enabled
See Registering a Connector Server to declare the newly installed connector server within Identity Manager.
You must declare within Identity Manager the connection information needed to communicate with each .NET connector server. If this connection information is not correctly declared, then Identity Manager will not have access to the .NET connectors deployed within the .NET connector server.
Log on to the Identity Manager as an administrator who has the Resource Administrator capability.
Select Configuration > Connector Servers.
Click New in the Manage Connector Servers Definitions page.
Complete the required fields in the New Connector Server. See the online help for information about each field.
Click Save. Identity Manager will display “Available” in the Status column for the new Connector Server definition if Identity Manager can successfully communicate with the remote connector server.
The following sections describe the following connector-related management tasks in an Identity Manager deployment:
When you create a resource, Identity Manager writes information about the selected connector server to the resource object. You can change the connector server of an existing resource, or change the version of the connector.
From the Resource page, select the resource you want to edit.
Select the Resource Actions > Change Connector Parameters menu option. Note that Identity Manager permits you to select only a connector server that has at least one version of the connector available. The only versions displayed are those provided by the selected connector server.
When you are editing or creating a connector-based resource, Identity Manager displays a set of fields known as operation time-outs. By default, Identity Manager sets operation time-outs to a value of -1, which represents no time-out. When you set this field to a non-zero value, the operation times out with an error if the connector does not complete the operation sooner than the specified time-out interval. Identity Manager stores time out values in the Resource XML object under the <OperationTimeouts> tag. Time-outs with a value of -1 are not stored in the XML.
When editing a connector-based resource, you will see the Connector Pooling configuration fields on the final page of the resource wizard. From that page, you can set values for these attributes:
maxObjects
maxIdle
minIdle
evictTimeout
maxWait
Connector-based resources follow the same rules as adapter-based resources in terms of defining resources actions to use as before and after actions. Identity Manager supports the use of before and after actions, including create, update, delete, disable, and enable operations.
You remove a connector from deployment by removing its corresponding .jar or DLL file. Once the connector is removed, Identity Manager can no longer access it. If you remove a connector from deployment while Identity Manager resources still reference it for their implementation, any further use of that resource within Identity Manager will result in run-time errors. To help prevent this problem, run the Connectors-In-Use report before removing connectors from deployment.
Identity Manager provides the following types of tracing for connector performance:
Tracing of local Java connectors can be limited on a class level only. This differs from the method-level tracing supported for other classes. Identity Manager does not support the ability to manage tracing on remote connectors.
Use this level of tracing to determine whether the problem is within Identity Manager or the connector itself. This trace method works for both remote and local connectors. To enable connector API-level tracing, enable level 4 Identity Manager tracing for class org.identityconnectors.framework.impl.api.LoggingProxy. This type of tracing focuses on the arguments and return values of every connector API method call.
Use this level of tracing to troubleshoot problems within a connector. This trace method works only for local Java connectors. To implement, enable Identity Manager tracing for the connector Java classes (for example, org.identityconnectors.datebasetable.DatabaseTableConnector). It traces all log calls made by the connector code into the Identity Manager trace file.
To implement, enable Identity Manager tracing for the connector Java classes (or example, org.identityconnectorsframework.*). This trace method works with all log calls made internally by the framework implementation classes.
.NET connectors call the standard .NET trace API. No centralized tracing control by Identity Manager. You cannot view .NET trace files from within Identity Manager. You must edit the local connector server configuration file to configure .NET tracing.
Connector-based resources support the same standard JMX monitoring as resource adapter-based resources:
Standard ActiveSync JMX
Standard (new) resource JMX
You can enable the tracing of local Java connectors by using the standard Identity Manager tracing debug page. The connector's log calls will write to the same trace file as all Identity Manager tracing.
You cannot manage logging for remote connectors. Instead, you must use the native Windows tools to configure logging for remote connectors locally on the machine where the remote connector host is running.
Because a connector-based resource looks like a typical resource to the rest of Identity Manager, you can use the JMX tools already present for resources and resource adapters (including Active Sync JMX) to monitor the use and performance of connector-based resources.
The connector framework API maintains the connection pool used by local Java connectors, and there is currently no visibility or management for that information. There is also no such tool provided by the connector API for remote connectors.