This is the main interface to declare an identity connector. Many connectors create the connection to the target system when the connection is required, removing the connection when finished with it, and disposing of any resources it has used. The interface provides the init and dispose life cycle methods for this purpose.

Every connector implementation must be annotated with @ConnectorClass. This is required because the ICF would scan all top level .class files in the connector bundle looking for classes that have the @ConnectorClass annotation, therefore, autodiscovering connectors that are defined in the bundle. This annotation requires the following elements:

• configurationClass: This is the configuration class for this connector. This class has all the information about the target that can be used by the connector to connect and perform various provisioning and reconciliation operations. See section The org.identityconnectors.framework.spi.Configuration Interface for more information on how to implement the configuration class.

• displayNameKey: Display name key that must be present in the message catalog.

The following is a sample connector implementation.

/**
 * Flat file connector implementation. This connector supports create, 
 * delete, search and update operations.
 */
@ConnectorClass
  (configurationClass=FlatFileConfigurationImpl.class,
   displayNameKey="FLAT_FILE_CONNECTOR")
public class FlatFileConnector implements Connector,
   CreateOp, DeleteOp,SearchOp<Map<String, String>>,UpdateOp{

Here:

• CreateOp: Helps the connector to create an entity on the target system

• DeleteOp: Helps the connector to delete an entity on the target system

• SearchOp: Helps the connector to search an entity on the target system

• UpdateOp: Helps the connector to update an existing entity on the target system

See Implementing the Operation Interfaces for more information.

The following sections contain information and sample code that illustrates how you might implement the Connector methods.

• Implementing the init Method

• Implementing the dispose Method

• Implementing the getConfiguration Method

The implementation of this interface encapsulates the configuration of a connector. Configuration implementation includes all the necessary information of the target system, which is used by the Connector implementation to connect to the target system and perform various reconciliation and provisioning operations. The implementation should have a default Constructor with setters and getters defined for its properties. Every property declared may not be required but if a property is required, then it should be marked required using the annotation org.identityconnectors.framework.spi.ConfigurationProperty. Configuration implementation is a Java bean and all the instance variables (mandatory or not) do have default values. For example, a string userName is used to connect to the target system and this is a mandatory attribute. This has a default value of null. When userName is a mandatory attribute, ICF expects a value to be provided by Oracle Identity Manager. In other words, Oracle Identity Manager cannot miss out this parameter. If missed, then the connector throws ConfigurationException.

The implementation should check that all required properties are available and validated before passing itself to the Connector. The interface provides a validate method for this purpose. For example, there are three mandatory configuration parameters, such as the IP address of the target, the username to connect to the target, and the password for the user. The validate method implementation can check for non-NULL values and valid IP address by using regex.

The following is the Configuration implementation:

/**
 * Configuration implementation for the flat file connector. 
 */
public class FlatFileConfigurationImpl extends AbstractConfiguration{

The Configuration implementation must provide implementation for the following methods:

• The validate() Method

• The setConnectorMessages() Method

• The getConnectorMessages() Method

Connection pooling by ICF is a feature provided by the ICF in which the framework maintains a pool of connector instances and uses them while performing provisioning and reconciliation operations. Connectors can make use of pooling by implementing the PoolableConnector interface instead of plain Connector interface. To make use of this feature, implement the PoolableConnector interface. If you implement the Connector interface, then ICF creates a new connector instance for every operation, creates a new connection with the target, completes the provisioning/reconciliation operation, removes the connection with the target system, and finally disposes this connector instance. Therefore, the advantages of implementing PoolableConnector is that a pool of configurable connector instances are maintained and are reused for many operations.

Some of configurable options are:

• Maximum connector objects in the pool that are idle and active (_maxObjects)

• Maximum connector objects that are idle (_maxIdle)

• Max time to wait if the pool is waiting for a free object to become available before failing (_maxWait)

• Minimum time to wait before evicting an idle object (_minEvictableIdleTimeMillis)

• Minimum number of idle objects (_minIdle)

These values must be set by connector API developer, and if not provided, then the following default values are used:

• _maxObjects = 10

• _maxIdle = 10

• _maxWait = 150 * 1000 ms

• _minEvictableIdleTimeMillis = 120 * 1000 ms

• _minIdle = 1

The PoolableConnector interface extends the Connector interface. It is implemented to enable identity connector pooling that ICF provides. ICF must make sure that the Connector instance is alive before being used. For this purpose, the interface provides a checkAlive method. The following is a sample flat file PoolableConnector implementation:

/**
 * Flat file connector implementation. This is a poolable connector
   which supports create, delete, search and update operations.
 */
@ConnectorClass
  (configurationClass=FlatFileConfigurationImpl.class,
   displayNameKey="FLAT_FILE_CONNECTOR")
public class FlatFileConnector implements PoolableConnector,
   CreateOp, DeleteOp,SearchOp<Map<String, String>>,UpdateOp{

To implement the PoolableConnector interface, provide an implementation of the checkAlive method along with all the methods discussed in The org.identityconnectors.framework.spi.Connector Interface. The checkAlive method determines if the Connector instance is alive and can be used for operations on the target system. checkAlive can be called often thus the developer should make sure the implementation is fast. The method should throw a specific RuntimeException (if available) when the Connector is no longer alive. The following example illustrates how to implement the checkAlive method:

/**
* Checks if this connector is alive, if not throws a RuntimeException
*/
@Override
public void checkAlive() {
//check if the connector is still connected to target
}

This interface must be implemented by a Connector that needs to normalize any attributes passed to it. A normalizer converts values to a standard form for the purpose of display, consumption, or comparison. For example, a normalizer might convert text values to a specific case, trim whitespace, or order the elements of a DN in a specific way.

The interface defines a normalizeAttribute method for this purpose. This method takes an ObjectClass and an Attribute to be normalized as arguments and returns the normalized Attribute. Attribute normalization is applied during many operations including:

• Filters that are passed to SearchOp

• Results returned from SearchOp

• Results returned from SyncOp

• Attributes passed to UpdateAttributeValuesOp

• Uids returned from UpdateAttributeValuesOp

• Attributes passed to UpdateOp

• Uids returned from UpdateOp

• Attributes passed to CreateOp

• Uids returned from CreateOp

• Uids passed to DeleteOp

The following example illustrates the normalizeAttribute method definition:

public Attribute normalizeAttribute (ObjectClass oClass, Attribute attribute) {
if (attribute instanceof Uid) {
return new Uid(LdapUtil.createUniformUid((String)newValues.get(0), configuration.getSuffix()));
}
}

Each operation interface defines an action that the Connector may perform on a target system, if supported by it. The operation interfaces belong to the org.identityconnectors.framework.spi.operations package. The names of these operation interfaces are listed below, but subsequent sections elaborate on each interface:

• AuthenticateOp

• CreateOp

• DeleteOp

• ResolveUsernameOp

• SchemaOp

• ScriptOnConnectorOp

• ScriptOnResourceOp

• SearchOp<T>SyncOp

• TestOp

• UpdateAttributeValuesOp

• UpdateOp

The SchemaOp interface is implemented to allow the connector to describe the objects it can handle on the target system. The schema that a connector returns describes the object-classes that it exposes for management. Each object-class has a name, a description, and a set of attribute definitions. Each attribute definition has a name, a syntax, and certain flags that describe its properties, such as multi-valued, single-valued, readable, or writeable.

The schema that a connector returns describes the attributes of each type of object that the connector exposes. Sometimes, this requires translation from an internal representation to this Schema format. In other instances, the Schema presents as an attribute; something that is natively available only via calls to the target API. Irrespective of how the SPI implementation accomplishes the mapping between the native representation and the corresponding ConnectorObject, the Schema provides the metadata that describes what a client can expect to find in a ConnectorObject of each type, which is objectClass.

To implement this interface, provide an implementation for the schema method as defined in the following example:

public Schema schema

The implementation should return the schema containing the types of objects that this identity connector supports.

@Override
  public Schema schema() {
      SchemaBuilder flatFileSchemaBldr = new SchemaBuilder(this.getClass());
      Set<AttributeInfo> attrInfos = new HashSet<AttributeInfo>();
      for (String fieldName : flatFileMetadata.getOrderedTextFieldNames()) {
          AttributeInfoBuilder attrBuilder = new AttributeInfoBuilder();
          attrBuilder.setName(fieldName);
          attrBuilder.setCreateable(true);
          attrBuilder.setUpdateable(true);
          attrInfos.add(attrBuilder.build());
      }
      
// Supported class and attributes
      flatFileSchemaBldr.defineObjectClass
        (ObjectClass.ACCOUNT.getDisplayNameKey(), attrInfos);
      return flatFileSchemaBldr.build();
  }

The CreateOp interface is implemented to enable creating objects on the target system. To implement this interface, provide an implementation of the create() method, as shown in the following example:

public Uid create
  (ObjectClass objectClass, Set<Attribute> attributes, 
   OperationOptions options)

This method takes an ObjectClass (for example, account or group), a set object attributes, and operation options. The implementation creates an object on the target system by using passed object attributes and object type defined by ObjectClass. The ObjectClass argument specifies the class of object to create. The class of object to be created is one of the inputs to the create operation. ObjectClass is the first argument to the create() method, as shown in the following example:

@Override
    public Uid create(ObjectClass arg0, Set<Attribute> attrs,
            OperationOptions ops) {
 
        System.out.println("Creating user account " + attrs);
        assertUserObjectClass(arg0);
        try {
            FlatFileUserAccount accountRecord = new FlatFileUserAccount(attrs);
        // Assert uid is there
            assertUidPresence(accountRecord);
 
        // Create the user
            this.flatFileWriter.addAccount(accountRecord);
 
        // Return uid
            String uniqueAttrField = this.flatFileConfig
                    .getUniqueAttributeName();
            String uniqueAttrVal = accountRecord
                    .getAttributeValue(uniqueAttrField);
            System.out.println("User " + uniqueAttrVal + " created");
            
            return new Uid(uniqueAttrVal);
        } catch (Exception ex) {
 
        // If account exists
            if (ex.getMessage().contains("exists"))
                throw new AlreadyExistsException(ex);
 
        // For all other causes
            System.out.println("Error in create " + ex.getMessage());
            throw ConnectorException.wrap(ex);
        }
     }

If the operation is successful, Uid instance representing object identifier on the target system is supposed to be created and returned. The caller can then use the Uid to refer to the created object.

The DeleteOp interface is implemented to enable deleting objects from the target system. To implement this interface, provide an implementation for the delete method as defined in the following example:

public void delete
   (ObjectClass objectClass, Uid uid, OperationOptions options)

This method takes an ObjectClass (for example, account or group), the Uid of the object being deleted from the target system, and operation options. The implementation deletes the object identified by the provided Uid from the target system. if the object does not exist on the target system, then an org.identityconnectors.framework.common.exceptions.UnknownUidException is generated. The following example illustrates how to implement the delete method:

@Override
    public void delete(ObjectClass arg0, Uid arg1, OperationOptions arg2) {
        final String uidVal = arg1.getUidValue();
        this.flatFileWriter.deleteAccount(uidVal);
        log.ok("Account {0} deleted", uidVal);
    }

The SearchOp interface is implemented to enable searching objects on the target system.

This section describes how to implement the SearchOp interface. It contains the following topics:

• About Implementing the SearchOp Interface

• Implementing the createFilterTranslator Method

• Implementing the executeQuery Method

The UpdateOp interface is implemented to enable updating objects on the target system. To implement this interface, provide an implementation of the update method as defined in the following example:

public Uid update(ObjectClass oClass, Uid uid, 
   Set<Attribute> attributes, OperationOptions options)

This method takes an ObjectClass (for example, account or group), Uid of the object being updated, a set of object attributes being updated, and operation options. The implementation updates the object on the target system identified by the Uid with the new values of attributes. If the object identified by the Uid does not exist on the target system, then an UnknowUidException is generated. The following example illustrates how to implement the update method:

@Override
    public Uid update(ObjectClass arg0, Uid arg1, 
       Set<Attribute> arg2, OperationOptions arg3) {
         String accountIdentifier = arg1.getUidValue();
    // Fetch the account
       FlatFileUserAccount accountToBeUpdated = this.flatFileParser
              .getAccount(accountIdentifier);
 
   // Update
        accountToBeUpdated.updateAttributes(arg2);
        this.flatFileWriter
              .modifyAccount(accountIdentifier, accountToBeUpdated);
        log.ok("Account {0} updated", accountIdentifier);
 
   // Return new uid
        String newAccountIdentifier = accountToBeUpdated
              .getAttributeValue
                 (this.flatFileConfig.getUniqueAttributeName());
        return new Uid(newAccountIdentifier);
    }

1. Create a new directory on the computer on which you want to install the Java Connector Server. In this section, CONNECTOR_SERVER_HOME represents this directory.
2. Unzip the Java Connector Server package in your new directory from Step 1. Java Connector Server is available for download in the Oracle Technology Network Web site at the following URL:

   http://www.oracle.com/technetwork/index.html

3. In the ConnectorServer.properties file in the conf/ directory, set the properties as required by your deployment. For information about the properties in the ConnectorServer.properties file, see Properties in the ConnectorServer.properties File.
4. Set the properties in the ConnectorServer.properties file, as follows:

   • To set connectorserver.key, run the Java Connector Server with the /setKey option. See Running the Java Connector Server on Microsoft Windows and Running the Java Connector Server on Solaris and Linux for more information.

   • For all other properties, edit the ConnectorServer.properties file manually.

5. The conf directory also contains the logging.properties file, which you can edit if required by your deployment.

1. Make sure that you have set the properties required by your deployment in the ConnectorServer.properties file, as described in Installing and Configuring a Java Connector Server.
2. Change to the CONNECTOR_SERVER_HOME\bin directory and find the ConnectorServer.bat script.

   For information about the options supported by the options supported by the ConnectorServer.bat script, see Options Supported by the ConnectorServer.bat Script.

3. If you need to stop the Java Connector Server, then stop the respective Microsoft Windows service.

   Note:

   When you run the connectorserver.bat script, you might encounter the following heap memory issue:

   org.identityconnectors.framework.server.impl.ConnectionListener
   processOperationRequest
   
   SEVERE: Java heap space
   
   java.lang.OutOfMemoryError: Java heap space
   
   at
   java.io.BufferedInputStream.fill(BufferedInputStream.java:233)
   
   at
   java.io.BufferedInputStream.read1(BufferedInputStream.java:286)
   
   at
   java.io.BufferedInputStream.read(BufferedInputStream.java:345)
   
   at java.io.DataInputStream.read(DataInputStream.java:149)
   
   at sun.misc.IOUtils.readFully(IOUtils.java:65)
   
   at
   sun.security.provider.JavaKeyStore.engineLoad(JavaKeyStore.java:753)
   
   at
   sun.security.provider.JavaKeyStore$JKS.engineLoad(JavaKeyStore.java:56)
   
   at
   sun.security.provider.KeyStoreDelegator.engineLoad(KeyStoreDelegator.java:224)
   
   at
   sun.security.provider.JavaKeyStore$DualFormatJKS.engineLoad(JavaKeyStore.java:
   70)
   
   at java.security.KeyStore.load(KeyStore.java:1445)
   
   at
   sun.security.ssl.TrustManagerFactoryImpl.getCacertsKeyStore(TrustManagerFactor
   yImpl.java:226)
   
   at
   sun.security.ssl.TrustManagerFactoryImpl.engineInit(TrustManagerFactoryImpl.ja
   va:50)
   
   at
   javax.net.ssl.TrustManagerFactory.init(TrustManagerFactory.java:250)
   
   at
   sun.security.ssl.SSLContextImpl.engineInit(SSLContextImpl.java:72)
   
   at javax.net.ssl.SSLContext.init(SSLContext.java:282)

   To workaround this issue, edit the connectorserver.bat script and change the value 500m to 2048m, as shown:

   set JAVA_OPTS=-Xmx2048m
       "-Djava.util.logging.config.file=%CONNECTOR_SERVER_HOME%\conf\logging.properties"
       "-Djava.io.tmpdir=%CONNECTOR_SERVER_HOME%\temp"

1. Make sure that you have set the properties required by your deployment in the ConnectorServer.properties file, as described in Installing and Configuring a Java Connector Server.
2. Change to the CONNECTOR_SERVER_HOME/bin directory.
3. Use the chmod command to set the permissions to make the connectorserver.sh script executable.
4. Run the connectorserver.sh script. For information about the options supported by the connectorserver.sh script, see Options Supported by the connectorserver.sh Script.

   When you run the connectorserver.sh script, you might encounter the following heap memory issue:

   org.identityconnectors.framework.server.impl.ConnectionListener
   processOperationRequest
   
   SEVERE: Java heap space
   
   java.lang.OutOfMemoryError: Java heap space
   
   at
   java.io.BufferedInputStream.fill(BufferedInputStream.java:233)
   
   at
   java.io.BufferedInputStream.read1(BufferedInputStream.java:286)
   
   at
   java.io.BufferedInputStream.read(BufferedInputStream.java:345)
   
   at java.io.DataInputStream.read(DataInputStream.java:149)
   
   at sun.misc.IOUtils.readFully(IOUtils.java:65)
   
   at
   sun.security.provider.JavaKeyStore.engineLoad(JavaKeyStore.java:753)
   
   at
   sun.security.provider.JavaKeyStore$JKS.engineLoad(JavaKeyStore.java:56)
   
   at
   sun.security.provider.KeyStoreDelegator.engineLoad(KeyStoreDelegator.java:224)
   
   at
   sun.security.provider.JavaKeyStore$DualFormatJKS.engineLoad(JavaKeyStore.java:
   70)
   
   at java.security.KeyStore.load(KeyStore.java:1445)
   
   at
   sun.security.ssl.TrustManagerFactoryImpl.getCacertsKeyStore(TrustManagerFactor
   yImpl.java:226)
   
   at
   sun.security.ssl.TrustManagerFactoryImpl.engineInit(TrustManagerFactoryImpl.ja
   va:50)
   
   at
   javax.net.ssl.TrustManagerFactory.init(TrustManagerFactory.java:250)
   
   at
   sun.security.ssl.SSLContextImpl.engineInit(SSLContextImpl.java:72)
   
   at javax.net.ssl.SSLContext.init(SSLContext.java:282)

   To workaround this issue, edit the connectorserver.sh script and change the value 500m to 2048m, as shown:

   exec "$_RUNJAVA" -Xmx2048m
       -D"java.util.logging.config.file=${CONNECTOR_SERVER_HOME}/conf/logging.propert ies"
       -D"java.io.tmpdir=${CONNECTOR_SERVER_TMPDIR}" $JAVA_OPTS_PARAMS \

1. Change to the bundles directory in your Java Connector Server directory.
2. Copy the Java Connector Bundle JAR to the bundles directory.
3. Add any applicable third party JAR files required by the identity connector to the lib directory.
4. Restart the Java Connector Server.

1. Deploy an SSL certificate to the Connector Server's system.
2. Configure your Connector Server to provide SSL sockets.
3. Configure your application to communicate with the Connector Server using SSL.

   Refer to the target system's manual for specific notes on configuring connections to identity connector servers. You will indicate to your application that an SSL connection is required when establishing a connection for each SSL-enabled connector server. Additionally, if any of the SSL certificates used by your connector servers are issued by a non-standard certificate authority, your application must be configured to respect the additional authorities. Refer to your manual for notes regarding certificate authorities.

   Note:

   Java applications may solve the issue of non-standard certificate authorities by expecting the following Java system properties to be passed when launching the application:

   • javax.net.ssl.trustStorePassword

     For example:

     -Djavax.net.ssl.trustStorePassword=PASSWORD

   • javax.net.ssl.trustStore

     For example:

     -Djavax.net.ssl.trustStore=/usr/myApp_cacerts

   Alternately, the non-standard certificate authorities may be imported to the standard ${JAVA_HOME}/lib/security/cacerts directory.

1. Start the Microsoft Services Console.

   If the .NET Connector Server is running, stop it by stopping the Windows service.

2. Go to the directory where the .NET Connector Server is installed. The default directory is, C:\Program Files(x86)\Idenity Connector\Connector Server.

   Run the following command from the command prompt:

   ConnectorServer.exe /setkey NEW_KEY

   In this command, NEW_KEY is the value for the new key. This key is required by any client that connects to this .NET Connector Server.

3. Update the settings in the .NET Connector Server configuration file (ConnectorServer.exe.config). These settings are in the element named appSettings. For example:

   <add key="connectorserver.port" value="8759"/>
   <add key="connectorserver.usessl" value="false"/>
   <add key="connectorserver.certificatestorename" value="ConnectorServerSSLCertificate"/> 
   <add key="connectorserver.ifaddress" value="0.0.0.0"/> 
   <add key="logging.proxy" value="false"/>
   <!--Possible protocol values are T1s, T1s11, TLS12 -->
   <add key="connectorserver.protocol" value="Tls">

   Note:

   To run the .NET Connector Server on an IPv6 host computer, add the following line to the .NET Connector Server configuration file:

   <add key="connectorserver.ifaddress" value="::0" />

   The most common settings you might want to change are:

   • Port Number: The connectorserver.port property is a key for denoting both SSL and non-SSL connector server port. If the connectorserver.usessl property is set to true, then the connector server listens on a secure channel using the same port. The default SSL and non-SSL port number is 8759. To change the default connector server port, update the connectorserver.port property with the new port number in the connectorserver.exe.config file.

   • SSL Setting: To use SSL, set the value of connectorserver.usessl to true, and set the value of connectorserver.certifacatestorename to the name of the certificate store which is having the trust certificate. Run the following command from the command prompt to create and add the target system trust certificate in certificate store:

     C:\>certutil -f -addstore tlsstore C:\ADSSLCer.cer
     Note: refer the connector guide of respective target system to generate the trust certificate i.e.  C:\ADSSLCer.cer
     

     Note:

     Make sure that the certificate store mentioned in the command does not already exist. The certificate store mentioned in the ConnectorServer.exe.Config file must have only one certificate. If there is more than one certificates, then the .NET Connector Server will not start.

     Run the following command to view the number of certificates present in the certificate store:

     C:\>certutil -viewstoreSTORE_NAME

     And update the connectorserver.protocol to choose the SSL communication protocol that is, TLS 1.0, TLS 1.1, or TLS 1.2.

   • Listening Socket Bind: To change the listening socket bind, set connectorserver.ifaddress to an address other than 0.0.0.0.

4. Save the following configuration information from the .NET Connector Server installation. This information must be specified while configuring the IT resource for the Connector Server:

   • Host name or IP address

   • Connector Server port

   • Connector Server key values

   • If SSL should be enabled

5. After completing all the .NET Connector Server configurations, restart the Windows service or alternately restart the .NET Connector Server by running the following command from the command line interface. Go to the directory where .NET Connector Server is installed, run the following command:

   ConnectorServer.exe /run

The Connector Server uses the standard .NET trace mechanism. Trace settings are defined in the connectorserver.exe.config configuration file. The following example illustrates how they are defined:

<system.diagnostics>
  <trace autoflush="true" indentsize="4">
     <listeners>
       <remove name="Default" />
       <add name="myListener" 
            type="System.Diagnostics.TextWriterTraceListener" 
            initializeData="c:\connectorserver2.log"    
            traceOutputOptions="DateTime">
       <filter type="System.Diagnostics.EventTypeFilter" 
               initializeData="Information" />
       </add>
    </listeners>
  </trace>
</system.diagnostics>

The default settings are a good starting point but you may change these settings as follows.

• For less tracing, change the filter type's initializeData setting to Warning or Error.

• For more verbose logging, set the value to Verbose or All.

  Caution:

  The amount of logging performed has a direct effect on the performance of the Connector Servers.

Any configuration changes require that the Connector Server be stopped and restarted.

The best way to run the .NET Connector Server is as a Windows Service. During installation, the Connector Server is installed as a Windows service. If this is not adequate for your environment, the Connector Server may be installed or uninstalled as a Windows Service by using the /install or /uninstall arguments at the command prompt.

To run the Connector Server interactively, open the command prompt, go to the directory where .NET Connector Server is installed, run the following command:

ConnectorServer.exe /run

To install new identity connectors, change to the directory where the Connector Server was installed, extract the new identity connector ZIP into it, and restart the Connector Server.