Chapter 57 Identity Connectors Overview

This chapter introduces Identity Connectors, a newly supported feature of Waveset. 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:

• Introduction to Identity Connectors

• Migrating from Existing Resources

• Configuring and Managing Connectors

• Additional Management Topics

• Debugging and Troubleshooting

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.

Introduction to Identity Connectors

An identity connector is a component, similar to a resource adapter, that provides a link between Waveset 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 Waveset 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. Waveset automatically detects any newly deployed connectors.

• Connector release cycles do not rely upon Waveset release cycles. Connector releases can differ from Waveset releases , and you can add or update connectors in your deployment with less dependence on the particular version of Waveset you are currently using.

• Waveset loads each connector in a separate class loader. This enhances support for using multiple versions of a native API from within a single Waveset 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 Waveset APIs.

Migrating from Existing Resources

Connectors will eventually replace resource adapters. For this release, however, Waveset 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>.

Migrating to a Connector-Based Resource: General Steps

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.

1. Install the new connector (if not already installed)

2. Follow all the Waveset-specific installation steps documented for the connector, including importing any needed Exchange files.

3. Follow the migration procedure documented for the connector. Typically, this involves running a declared migration server task from Server Tasks > Run Tasks.

Configuring and Managing Connectors

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:

Listing Available Connectors

For this release, Waveset is shipping connectors for Active Directory and SPML2 resources. For more information about these connectors, see Chapter 58, Active Directory Connector and Chapter 59, SPML Connector.

1. Login in to Waveset Administrator Interface as an administrator who has the Resource Administrator capability

2. Select Resources > Resource Type Actions > Configure Managed Resources. The Resource Connectors area lists all the connectors that Waveset currently recognizes.

Downloading Connectors

You can download additional Waveset-supported identity connectors from https://identityconnectors.dev.java.net.

Downloading Java Connectors

An Waveset-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 Waveset web application

• Extract the ZIP file into the Waveset web application.

For a more detailed explanation, see Installing a Java Connector.

Downloading .NET Connectors

An Waveset-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 Waveset web application.

For a more detailed explanation, see Installing a .NET Connector.

Installing Java Connectors

Installing a Java Connector

A Java connector is delivered as one jar file and one ZIP file.

1. Stop your Waveset web application.

2. Copy the connector jar file into the WEB-INF/bundles directory of your Waveset web application.

3. Extract the connector ZIP file into the your Waveset web application directory.

4. Start your Waveset web application, and follow any additional connector-specific installation notes.

   Your newly installed Java connector should now be visible to Waveset. Log in to the Waveset 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).

5. (Optional) You may be required to import one or more Exchange files before using the new connector.

Installing .NET Connectors

Success installation of a .NET connector requires these steps:

• Installing a .NET Connector Executable Zip File

• Installing a .NET Connector Waveset Zip File

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 Waveset and the .NET bundles. A .NET connector server is roughly analogous to the Waveset gateway. For more information, see

• Installing a .NET Connector Server

• Registering a Connector Server

Installing a .NET Connector Executable Zip File

.NET connector bundles are delivered as two ZIP files.

---

Note –

You must install a .NET connector server before installing the .NET executable connector zip file.

---

To install the .NET connector's executable zip file:

1. If the connector server is already installed and running, stop the Connector Server service.

2. Unzip the ZIP file into the connector server installation directory.

3. Start the Connector Server service. If the connector server is not yet declared in Waveset, see Registering a Connector Server.

Installing a .NET Connector Waveset Zip File

1. Stop your Waveset web application.

2. Extract the connector ZIP file into the your Waveset web application directory, and restart your Waveset.

3. Follow any additional connector-specific installation notes.

4. (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 Waveset. To confirm this, log in to the Waveset 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.

Installing a .NET Connector Server

You install and run a .NET connector server when using a .NET connector from Waveset. A connector server manages one or more .NET bundles, and handles requests between Waveset and the .NET bundles. A .NET connector server is roughly analogous to the Waveset 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 Waveset.

Registering a Connector Server

You must declare within Waveset the connection information needed to communicate with each .NET connector server. If this connection information is not correctly declared, then Waveset will not have access to the .NET connectors deployed within the .NET connector server.

1. Log on to the Waveset as an administrator who has the Resource Administrator capability.

2. Select Configuration > Connector Servers.

3. Click New in the Manage Connector Servers Definitions page.

4. Complete the required fields in the New Connector Server. See the online help for information about each field.

5. Click Save. Waveset will display “Available” in the Status column for the new Connector Server definition if Waveset can successfully communicate with the remote connector server.

Additional Management Topics

The following sections describe the following connector-related management tasks in an Waveset deployment:

• Changing the Connector Server or Version Used by a Resource

• Setting a Time-Out for a Connector-Based Resource

• Editing Connection Pool Parameters

• Using Resource Actions with Connector-Based Resources

• Removing a Connector from Deployment

Changing the Connector Server or Version Used by a Resource

When you create a resource, Waveset 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.

To Change Connector Server Information in the Resource Object

1. From the Resource page, select the resource you want to edit.

2. Select the Resource Actions > Change Connector Parameters menu option. Note that Waveset 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.

Setting a Time-Out for a Connector-Based Resource

When you are editing or creating a connector-based resource, Waveset displays a set of fields known as operation time-outs. By default, Waveset 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. Waveset 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.

Editing Connection Pool Parameters

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

Using Resource Actions with Connector-Based Resources

Connector-based resources follow the same rules as adapter-based resources in terms of defining resources actions to use as before and after actions. Waveset supports the use of before and after actions, including create, update, delete, disable, and enable operations.

Removing a Connector from Deployment

You remove a connector from deployment by removing its corresponding .jar or DLL file. Once the connector is removed, Waveset can no longer access it. If you remove a connector from deployment while Waveset resources still reference it for their implementation, any further use of that resource within Waveset will result in run-time errors. To help prevent this problem, run the Connectors-In-Use report before removing connectors from deployment.

Debugging and Troubleshooting

Waveset Tracing

Waveset provides the following types of tracing for connector performance:

• API-Layer Tracing

• Java Connector-Specific Tracing

• Java Connector Framework Tracing

• .NET Tracing

---

Note –

Tracing of local Java connectors can be limited on a class level only. This differs from the method-level tracing supported for other classes. Waveset does not support the ability to manage tracing on remote connectors.

---

API-Layer Tracing

Use this level of tracing to determine whether the problem is within Waveset or the connector itself. This trace method works for both remote and local connectors. To enable connector API-level tracing, enable level 4 Waveset 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.

Java Connector-Specific Tracing

Use this level of tracing to troubleshoot problems within a connector. This trace method works only for local Java connectors. To implement, enable Waveset tracing for the connector Java classes (for example, org.identityconnectors.datebasetable.DatabaseTableConnector). It traces all log calls made by the connector code into the Waveset trace file.

Java Connector Framework Tracing

To implement, enable Waveset 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 Tracing

.NET connectors call the standard .NET trace API. No centralized tracing control by Waveset. You cannot view .NET trace files from within Waveset. You must edit the local connector server configuration file to configure .NET tracing.

JMX Monitoring of Connectors

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 Waveset tracing debug page. The connector's log calls will write to the same trace file as all Waveset 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 Waveset, 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.