How to use Identity Connectors in YOUR application

This is what we think is one of the biggest advantages of Identity Connectors - it is not bound to any specific identity product. Still not seeing any advantage? How about this - with two small jar files you can (for example) create/update/delete/search users in resources like MS Exchange, MS Active Directory, LDAP or DB2 without even knowing single method of the resource API, moreover using the same Identity Connectors JAVA API! Let's see how to do that...

Step 1 - Setup the IDE 

  •  (Optional) Install IDE if you don't have it - NetBeans, Eclipse or whatever...
  • Download Connector Toolkit zip from Identity Connectors downloads page
  • Unpack the zip, find "dist" directory, you should see connector-framework.jar and connector-framework-internal.jar there, add these two jars to your project libraries (to be precise - the connector-framework.jar can be set as build time library and the connector-framework-internal.jar as runtime library)
  •  Download connector bundles which you would like to use (I'm using databasetable and flatfile connectors in my setup), unzip the connectors to some directory on you disk - they don't need to be part of the project libraries

 Here is how my NetBeans project looks like:

ide libraries

 And the directory structure:

project directory

Step 2 - Locate connector bundles

 Ok, I have the downloaded the following connector bundles: org.identityconnectors.databasetable-1.0.4460.jarorg.identityconnectors.databasetable-1.0.4505.jarorg.identityconnectors.flatfile-1.0.2838.jar. I have them in my bundles directory, now I have to let the connector framework know to make the ready to use, this is done by creating ConnectorInfoManager using the ConnectorInfoManagerFactory:

  File bundleDirectory = new File("/workspace/myapp/bundles");
  URL db1Url = IOUtil.makeURL(bundleDirectory, "org.identityconnectors.databasetable-1.0.4460.jar");
  URL db2Url = IOUtil.makeURL(bundleDirectory, "org.identityconnectors.databasetable-1.0.4505.jar");
  URL flatfileUrl = IOUtil.makeURL(bundleDirectory, "org.identityconnectors.flatfile-1.0.2838.jar");

  ConnectorInfoManagerFactory factory = ConnectorInfoManagerFactory.getInstance();
  ConnectorInfoManager manager = factory.getLocalManager(db1Url, db2Url, flatfileUrl);

The most interesting is the last line where we create local manager with the URLs to connector bundles - we use local manager cause the bundles are deployed locally, we can also use remote manager if we have some connector server running - this topic will be covered in some other post later on.

Now the connector framework should know about our bundles, let's see what it has learned about them: 

  List<ConnectorInfo> connectorInfos = manager.getConnectorInfos();

  System.out.println("Available connector bundles:");
  for (ConnectorInfo connectorInfo : connectorInfos) {
     ConnectorKey key = connectorInfo.getConnectorKey();

when we run it it should give the output:

Available connector bundles:
ConnectorKey( bundleName=org.identityconnectors.databasetable bundleVersion=1.0.4460 connectorName=org.identityconnectors.databasetable.DatabaseTableConnector )
ConnectorKey( bundleName=org.identityconnectors.databasetable bundleVersion=1.0.4505 connectorName=org.identityconnectors.databasetable.DatabaseTableConnector )
ConnectorKey( bundleName=org.identityconnectors.flatfile bundleVersion=1.0.2838 connectorName=org.identityconnectors.flatfile.FlatFileConnector ) 

Looks good, connector framework analyzed the bundles and created ConnectorKey list to hold the informations - before we can use the connector however, we need to configure it first...

Step 3 - Configure the connector

To keep things simple we will use the flat file connector further on, but I'm sure you realized we can use whatever connector I need, even different versions of the same connector can be used from the same code - yes, the connector bundles are loaded by separate classloader.

So we can use the ConnectorInfo obtained in the previous step or we can use something like:

 ConnectorKey ffKey = new ConnectorKey("org.identityconnectors.flatfile",
 ConnectorInfo ffConInfo = manager.findConnectorInfo(ffKey);

To find out what the flat file connector needs to be configured:

 APIConfiguration ffConfig = ffConInfo.createDefaultAPIConfiguration();

 ConfigurationProperties ffConfigProps = ffConfig.getConfigurationProperties();
    for (String name : ffConfigProps.getPropertyNames()) {
       System.out.println("property: " + name);

This gives us:

property: uniqueAttributeName
property: encoding
property: fieldDelimiter
property: file
property: textQualifier

We are now ready to configure the connector and actually get its instance:

 ffConfigProps.setPropertyValue("uniqueAttributeName", "uid");
 ffConfigProps.setPropertyValue("file", new File("./data.txt"));

 ConnectorFacade ffConnector = 

If the above code executed successfully we have configured connector, created its instance and also validated that the connector was configured correctly and is ready to use - cool!

Step 4 - Use the connector

We have the connector instance, but we don't know what operations (Create/Update/Delete/...), object classes (Account/Group) and attributes it supports, we need to get the Schema to find that:

 Schema ffSchema = ffConnector.schema();

We can learn basically all the important information about connector capabilities by exploring the schema - I recommend to spend some time with studying its methods from the connector-framework javadoc coming together with the connector toolkit zip.

Anyway we skip the schema analysis and proceed directly to some user operation - since the flat file connector doesn't support create operation, let's search for all the users:

 ResultsHandler resultsHandler = new ResultsHandler() {
    public boolean handle(ConnectorObject cobject) {
       for (Attribute attribute : cobject.getAttributes()) {
       return true;
 };, null, resultsHandler, null);

The second parameter in search method is filter, null filter means we want to get all objects - running the code we get:

Attribute: {Name=__UID__, Value=[1]}
Attribute: {Name=__NAME__, Value=[1]}
Attribute: {Name=lastname, Value=[Doe]}
Attribute: {Name=firstname, Value=[John]}
Attribute: {Name=__UID__, Value=[2]}
Attribute: {Name=__NAME__, Value=[2]}
Attribute: {Name=lastname, Value=[Smith]}
Attribute: {Name=firstname, Value=[Jane]}

Step 5 - Learn more...

Based on the previous steps you should get idea how to leverage the identity connectors - with just a few lines of code the whole world of various resources is opening to you, your application will be able to talk to the resources like MS Active Directory, MS Exchange, LDAP, Google apps, MySQL, DB2, SPML, VMS and more are coming... 

Find more:


Post a Comment:
Comments are closed for this entry.

Blog of the Identity Connectors team.


« March 2015