27 Developing Plug-ins

This chapter describes the concepts related to plug-in and how to develop and use a plug-in the following sections:

27.1 Plug-ins and Plug-in Points

A plug-in is a logical component that extends the functionality of features provided by Oracle Identity Manager. The plug-in framework enables you to define, register, and configure plug-ins, which extend the functionality provided by features. Plug-ins can be predefined or custom-developed, and they are utilized at plug-in points. A plug-in point is a specific point in the business logic where extensibility can be provided. An interface definition called the plug-in interface accompanies such a point. You can extend the plug-in interface based on the business requirements and register them as plug-ins. To do this, you develop a Plugin Java class and compile it before archiving in a JAR file, define plug-in metadata in an XML file, and ZIP these artifacts as a plug-in package that is ready to deploy.

For example, user creation is a business operation in Oracle Identity Manager. But this operation exposes a plug-in point for user name generation. If you want to model your custom logic of user name generation, then you must identify the plug-in point specifications and develop a plug-in accordingly.

The concepts related to plug-ins are described in the following sections:

27.1.1 Plug-ins and Event Handlers

Most of the business operations in Oracle Identity Manager, such as user creation, role assignment to user, and user activation, are executed as orchestrations. Therefore, if there is a requirement to induce any custom logic in these operations or orchestrations, then you can model that logic as event handlers at stages, such as validation, preprocess, and postprocess, in which customization is supported.However, you can analyze if any such operation also exposes a plug-in point for inducing the custom logic. If a plug-in point is available, then you can utilize the plug-in point rather than operating the underlying orchestration. For example, you can implement username generation by using the exposed plug-in without writing that as an event handler in the create user orchestration.

Figure 27-1 shows a diagrammatic representation of plug-ins and event handlers.

Figure 27-1 Plug-ins and Event Handlers

Description of Figure 27-1 follows
Description of "Figure 27-1 Plug-ins and Event Handlers"

27.1.2 Plug-in Stores

The plug-in framework can store plug-ins in two types of stores:

  • File system

  • The Oracle Identity Manage database

When looking for plug-ins, the framework first examines plug-ins registered in the database, and looks in the file system.

27.1.2.1 File Store

The File Store consists of one or more directories on the Oracle Identity Manager host and is primarily used in development environments. This type of store is not appropriate for a production environment. File storage is convenient for the developer since there is no need to explicitly register the developed plug-ins with a file store. Users can just drop in the plug-in zips or exploded plug-in directory to the designated location(s).

By default, Plug-in framework looks for the plug-ins under the OIM_HOME/plugins directory. Additional plug-in directories can also be specified.

If a monitoring thread is enabled, then the plug-in framework monitors all the additions, modification, and deletions of plug-in zip files under the registered plug-in directories in the file system, and automatically reloads the plug-ins. Plug-in metadata such as name, version, and ID is read from the plug-in zip and is maintained in memory. This metadata is updated based on any file changes. The latest plug-in zip file is considered to be the current version of the plug-in. For details about how to configure the file store, see "Configuring Plug-ins".

Note:

Oracle recommends not to use the file store in production. File store is more suitable during plug-in development because it is easy to change the plug-in, and you are required to change only the file in the file system. There is no need to register. However, in production, plug-ins are not changed often, and therefore, avoid using the file store because of certain disadvantages. It adds the overhead of file store monitoring. In addition, the plug-ins are required to be replicated in all nodes of a cluster for the clustered deployment of Oracle Identity Manager.

27.1.2.2 Database Store

Plug-ins can be stored in the Oracle Identity Manager database, so that they are accessible from any node in a cluster. The Plug-in Framework uses Operation DB as the database store. This type of store is appropriate for a production environment.

You must explicitly register any plug-ins that are stored in the database. You can use the Plugin Registration Utility, which is a command-line tool, to register and deregister plug-ins. You can also use the registerPlugin API for this purpose. See "Registering and Unregistering Plug-ins By Using APIs" for more information about registering plug-ins.

Note:

After registering a plug-in, the server must be restarted. However, restarting the server might also depend on the feature that defines the plug-in point.

27.2 Using Plug-ins in Deployments

As already mentioned in this document, plug-ins are used for customizing the default functionality in an Oracle Identity Manager deployment. The number of supported plug-in points is a defined and constrained set. Therefore, you can use the plug-in points to extend the functionality only for the list of supported plug-in points. See "Plug-in Points" for a list of the supported plug-in points.

27.3 Plug-in Points

Table 27-1 lists the Java interfaces that act as plug-in points in Oracle Identity Manager:

Table 27-1 Plug-in Points

Plug-in Point Description

oracle.iam.ldapsync.LDAPContainerMapper

This is used by LDAP synchronization to determine which user/role container should be used to create the user/role in LDAP.

oracle.iam.platform.kernel.spi.EventHandler

This is the kernel event handler. See Chapter 28, "Developing Event Handlers" for information about kernel event handlers.

oracle.iam.platform.auth.api.LoginMapper

This is an implementation of a LoginMapper maps the JAAS user principal name to the corresponding Oracle Identity Manager username. This plug-in point is used to override the default mapping of JAAS user principal name to Oracle Identity Manager username for SSO scenarios. The default implementation returns the same value as the JAAS user principal name.This plug-in point is typically used in SSO scenarios where the JAAS user principal name and the Oracle Identity Manager username might be different. For example, the SSO system might set the email as the JAAS username but no user with that username exist in Oracle Identity Manager. For Oracle Identity Manager to recognize that user, the JAAS user principal name must be mapped to the Oracle Identity Manager username. This can be done by implementing a plug-in for LoginMapper, as shown:

public class CustomLoginMapper implements LoginMapper{
public String getOIMUserID(String jaasPrincipal) throws MappingException {
               return getUserName(jassPrincipal);
  }

private String getUserName(String emailID){
               String userName = null;

               //Use usermgmt APIs to get the username corresponding to this email id
               return userName;
 }
}

oracle.iam.identity.usermgmt.api.PasswordVerifier

This is used for verification of old password while changing the user's password. The class that is to be used for this validation is configured in the OIM.OldPasswordValidator system property. By default, use the container based authentication for verifying old password.

oracle.iam.request.plugins.StatusChangeEvent

This allows running of custom code during request status change.

oracle.iam.request.plugins.RequestDataValidator

This is used for custom validation of request data after submission.

oracle.iam.request.plugins.PrePopulationAdapter

This is used to prepopulate an attribute value by running custom code during request creation.

oracle.iam.scheduler.vo.TaskSupport

This is used to run the job in context. Execute method of the task is retrieved through the plug-in and is loaded.

oracle.iam.identity.usermgmt.api.UserNamePolicy

This is an implementation of username policies that are used to generate/validate username.

oracle.iam.identity.usermgmt.api.ReservationInLDAP

This is an implementation for reservation of user attributes in LDAP.

27.4 Configuring Plug-ins

You use the oim-config.xml file in the MDS to configure the following:

See Also:

"Configuring the oim-config.xml File" in the Oracle Fusion Middleware Administrator's Guide for Oracle Identity Manager for information about configuring the oim-config.xml file

  • The directory or directories in which the files store will look for plug-ins.

  • Whether to activate a thread that monitors the file store for any changes; the thread checks the zip files or exploded files in all the plug-in directories.

    The monitoring thread is typically activated in a dynamic development environment since plug-ins are being added or modified in such an environment; it can be inactive in a production system which contains a set of plug-ins . This is tracked by the reloadingEnabled attribute.

  • The time interval at which the monitoring thread wakes up and looks for any changes.

The following is a code snippet from the oim-config.xml file:

<pluginConfig storeType="common">
 
    <storeConfig reloadingEnabled="true"
 
      reloadingInterval="20">
 
      <!--
 
        Plugins present in the OIM_HOME/plugins directory are added by default.
 
        For adding more plugins, specify the plugin directory as below:
 
        <registeredDirs>/scratch/oimplugins</registeredDirs>
 
        <registeredDirs>/scratch/custom</registeredDirs>
 
      -->
 
    </storeConfig>
 
  </pluginConfig>

In this example:

  • The common store designation tells the framework to monitor both database and file stores

    Note:

    Do not modify the Store value; common is appropriate in all environments.

  • One directory is configured; additional directories can be configured by simply adding more <registeredDirs> tags.

  • The monitoring thread is active and looks for plug-in changes every 20 seconds by default.

    Monitoring is typically active in development environments only. If you switch between active and inactive, you must restart the application server for the change to take effect.

    Note:

    Restarting the application server is required for any changes made to plug-in data in the oim-config.xml file.

27.5 Developing Custom Plug-ins

This section describes how to develop custom plug-ins. It contains the following sections:

27.5.1 Developing Plug-ins

To develop a plug-in:

  1. Identify the plug-in point to extend.

  2. Identify the Java class that implements the plug-in point interface. Package the Java class and other dependent classes into a JAR file. Put the JAR file in the lib/ directory.

  3. Create the plugin.xml file. See "Declaring Plug-ins" for details.

  4. Identify the resource files required by the plug-in, such as property files, resource bundles, and image files.

  5. Zip the entire package.

    An Oracle Identity Manager plug-in is distributed as a ZIP file with a specified directory structure. The directory structure is as follows:

    • The plugin.xml file: The XML file contains the metadata associated with all the plug-ins such as the plug-in point it extends, the class implementing the plug-in, name, and the version number. All the fields in the XML are mandatory except the name. If the name is not given, then plugin class name is used as the name.

    • The lib/ directory: The lib/ directory consists of JAR files that contains the classes implementing the plug-in logic and the dependent library JAR files. In most instances, this directory consists of a single JAR file with the implementation of all the plug-ins that are specified in plugin.xml.

    • The resources/ directory: Contains resource files required by the plug-in, such as property files, resource bundles, and image files. These resources given in the resources directory of the plug-in zip can be accessed as follows:

      this.getClass().getClassLoader().getResourceAsStream(<resource_name>);

    • The META-INF/ directory: Contains XML files showing plug-in points for event handlers. Some services, such as the notification service, read the XML files from MDS or from the META-INF/ directory of the plug-in.

    Multiple plug-ins implementing the same plug-in point can be part of the same ZIP file.

    A plug-in has a Java class that implements the plug-in point interface. The plug-in library (JAR) can contain other dependent classes as well, but the class implementing the plug-in is the only one that is exposed to the feature. This class must be specified in plugin.xml.

  6. Place the ZIP file in the file store (the OIM_HOME/plugins/ directory) or database store.

  7. If the ZIP is placed in the database store, then register the plug-in by using the Plug-in Registration Utility, as described in "Registering Plug-ins".

27.5.2 Declaring Plug-ins

To extend the functionality provided by Oracle Identity Manager, you can declare the plug-ins for the application.

A plug-in has a Java class that implements the plug-in point interface. Be sure to assign unique names to all the plug-ins associated with a specific plug-in point. If the plug-in names are non-unique, an exception will be thrown during plug-in registration.

Declare the plug-ins in the plugin.xml file. For example:

<?xml version="1.0" encoding="UTF-8"?>
<oimplugins>
....
<plugins pluginpoint="oracle.iam.sample.passwdmgmt.service.PasswordElement">
        <plugin pluginclass=
        "oracle.iam.sample.passwdmgmt.custom.NumCustomPasswordElement" 
        version="1.0.1" name="num pwd element"/>
        <plugin pluginclass=
        "oracle.iam.sample.passwdmgmt.custom.DictionaryPasswordElement" 
        version="1.0.1" name="Dictionary password element" />        
</plugins>
....
</oimplugins>

Note:

You can have multiple versions of the plug-in stored and the feature can request a specific version of the plug-in from the plug-in framework. By default, all of the current plug-in points load the latest version of the plug-ins.

The XML shows two plug-in declarations. Both the plug-ins extend from the same plug-in point.

27.6 Registering Plug-ins

You can register the plug-ins by using APIs and Plugin Registration Utility.

27.6.1 Registering and Unregistering Plug-ins By Using APIs

You can use the following APIs for registration-related tasks:

  • PlatformService.registerPlugin

  • PlatformService.unRegisterPlugin

Here is an example:

System.out.println("Creating client....");
String ctxFactory = "weblogic.jndi.WLInitialContextFactory";
String serverURL = "t3://OIM_HOSTNAME:OIM_PORT";
System.setProperty("java.security.auth.login.config", "OIM_CLIENT_HOME/conf/authwl.conf");
String username = "USER_NAME";
char[] password = "PASSWORD".toCharArray();
Hashtable env = new Hashtable();
env.put(OIMClient.JAVA_NAMING_FACTORY_INITIAL,ctxFactory);
env.put(OIMClient.JAVA_NAMING_PROVIDER_URL, serverURL);

oimClient = new OIMClient(env);
System.out.println("Logging in");
oimClient.login(username, password);
PlatformService service = platform.getService(PlatformService.class);
File zipFile = new File(fileName);
FileInputStream fis = new FileInputStream(zipFile);
int size = (int) zipFile.length();
byte[] b = new byte[size];
int bytesRead = fis.read(b, 0, size);
while (bytesRead < size) {
bytesRead += fis.read(b, bytesRead, size - bytesRead);
}
fis.close();
service.registerPlugin(b);
service.unRegisterPlugin(pluginID, version);

Note:

"Using OIMClient" for information about using OIMClient for developing clients to integrate with Oracle Identity Manager.

27.6.2 Registering and Unregistering Plug-ins By Using the Plugin Registration Utility

You can use the Plugin Registration Utility for registering and unregistering plug-ins. The utility uses the following files:

  • pluginregistration.xml

  • ant.properties

These files are located in the OIM_HOME/plugin_utility/ directory.

Note:

Plug-in registration utilities require Apache Ant version 1.7 or later.

Before using the utility, perform the following:

  1. Set the values for wls.home and oim.home in ant.properties.

    For example:

    wls.home =.../middleware/wlserver_10.3
oim.home =..../middleware/Oracle_IDM1/server

    In addition, set the path for mw.home in the ant.properties file. Also, uncomment the following:

    #login.config=${oim.home}/config/authwl.conf

  2. Build the wlfullclient.jar in Oracle WebLogic server:

    1. Change directories to WLS_HOME/server/lib.

    2. Run the following command:

      java -jar ../../../modules/com.bea.core.jarbuilder_1.3.0.0.jar

      Note:

      The exact JAR file version can be different based on the WLS. Use the corresponding file with the name as com.bea.core.jarbuilder at the WLS_HOME/../modules/ directory.

Registering a Plug-in

To register a plug-in:

  1. Execute the ant target "register":

    ant -f  pluginregistration.xml register

  2. This will prompt for the Oracle Identity Manager username and password along with the server information and the location of the plugin zip file. Enter the complete path of the zip file location.

Unregister a Plug-in

To unregister a plug-in:

  1. Execute the ant target "unregister":

    ant -f  pluginregistration.xml unregister

  2. This will prompt for the Oracle Identity Manager username and password along with the server information and the classname of the plug-in class. Enter the classname with the complete package.

27.7 Migrating Plug-ins

The Deployment Manager supports migrating plug-ins from one deployement of Oracle Identity Manager to another. For example, the event handlers can be implemented in a test environment, and then migrated to the production environment by using the Deployment Manager. Figure 27-2 shows exporting plug-ins via the Deployment Manager:

Figure 27-2 Exporting Plug-ins

Description of Figure 27-2 follows
Description of "Figure 27-2 Exporting Plug-ins"

See Also:

"Migrating Configurations and Customizations" for information about the Deployment Manager