Skip Headers
Oracle® Fusion Middleware Application Developer's Guide for Oracle Identity Management
11g Release 1 (11.1.1)
E10186-02
  Go To Documentation Library
Library
Go To Product List
Product
Go To Table Of Contents
Contents
Go To Index
Index

Previous
Previous
 
Next
Next
 

12 Oracle Directory Integration and Provisioning Java API Reference

As of 10g (10.1.4.0.1), Oracle offers two complementary provisioning products, optimized for different use cases.

The Oracle Internet Directory SDK includes an Oracle Directory Integration and Provisioning user provisioning API, which enables you to manage users and their application properties in the Oracle Identity Management infrastructure. This chapter describes the main features of the API and explains how to use them.

This chapter contains the following sections:

12.1 Application Configuration

Applications must register with the provisioning system in order to be recognized as provisionable. They must also create their own configuration in Oracle Internet Directory using the command-line interface. Java classes exist for viewing application configurations.

This section contains the following topics:

12.1.1 Application Registration and Provisioning Configuration

In order to register with the provisioning system, an application must create a provisioning configuration. After the provisioning configuration exists, the provisioning system identifies the application as directory-enabled and provisionable.

The application must perform the following steps to create a provisioning configuration:

  1. Application Registration

  2. Provisioning Configuration

12.1.1.1 Application Registration

Oracle applications typically register themselves by using the repository APIs in the repository.jar file under $ORACLE_HOME/jlib. This file is provided during installation specifically for application registration. In addition to creating an application entry in Oracle Internet Directory, repository APIs can be used to add the application to privileged groups.

Applications written by customers, however, cannot use the repository.jar APIs to perform application registration. So application developers must use LDIF templates and create application entries in Oracle Internet Directory using LDAP commands.

An application must create a container for itself under one of these containers:

  • "cn=Products,cn=OracleContext"—for applications that service users in multiple realms

  • "cn=Products,cn=OracleContext,RealmDN"—for applications that service users in a specific realm

If an application is configured for a specific realm, then that application cannot manage users in other realms. In most cases, you should create the application outside any identity management realm so that the application is not tied to a specific realm in Oracle Internet Directory.

Whenever a new instance of the application installs, a separate entry for the application instance is created under the application's container. Some of the provisioning configuration is common to all the instances of a particular type and some is specific to the instance. When multiple instances of an application are deployed in an enterprise, each instance is independent of the others. Each instance is defined as a separate provisionable application. Users can be provisioned for one or more instances of this application, so that the user can get access to one or more instances of this application.

The examples in this section are for a sample application similar to Oracle Files. When the first instance of this application installs, specific entries must be created in Oracle Internet Directory. In the following example, the name of this application, chosen at run time, is Files-App1 and the type of the application is FILES. The application can have LDIF templates that can be instantiated if required and then uploaded to Oracle Internet Directory. In this example, the application identity is outside any realm. That is, it is under the "cn=Products,cn=OracleContext" container.

dn: cn=FILES,cn=Products,cn=OracleContext
changetype: add
objectclass: orclContainer

dn: orclApplicationCommonName=Files-App1,cn=FILES,cn=Products,cn=OracleContext
changetype: add
orclappfullname: Files Application Instance 1
userpassword: welcome123
description: This is a test Appliction instance.
protocolInformation: xxxxx
orclVersion: 1.0
orclaci: access to entry by group="cn=odisgroup,cn=DIPAdmins,
 cn=Directory Integration  Platform,cn=Products,
 cn=OracleContext" (browse,proxy) by group="cn=User Provisioning Admins,
 cn=Groups,cn=OracleContext" (browse,proxy)
orclaci: access to attr=(*) by group="cn=odisgroup,cn=DIPAdmins,
 cn=Directory Integration Platform,cn=Products,
 cn=OracleContext" (search,read,write,compare) 
 by group="cn=User Provisioning Admins,
 cn=Groups,cn=OracleContext" (search,read,write,compare)

The ACLs shown in the example are discussed in the "Application User Data Location" section.

The application is expected to grant certain privileges to some provisioning services and provisioning administrators.

When the second instance of this application installs, the following entries must be created in Oracle Directory Integration and Provisioning, assuming the name of this application, decided at run time, is Files-App2.

dn: orclApplicationCommonName=Files-App2,cn=FILES,cn=Products,cn=OracleContext 
changetype: add
orclappfullname: Files Application Instance 2
userpassword: welcome123
description: This is a test Appliction instance.
orclVersion: 1.0
orclaci: access to entry by group="cn=odisgroup,
 cn=DIPAdmins,cn=Directory Integration Platform,cn=Products,
 cn=OracleContext" (browse,proxy) by group="cn=User Provisioning Admins,
 cn=Groups,cn=OracleContext" (browse,proxy)
orclaci: access to attr=(*) by group="cn=odisgroup,cn=DIPAdmins,
 cn=Directory Integration Platform,cn=Products,
 cn=OracleContext" (search,read,write,compare) by 
 group="cn=User Provisioning Admins,cn=Groups,cn=OracleContext"
 (search,read,write,compare)

After the application creates its entries successfully, the application's identity is registered in Oracle Internet Directory. At this point, the application can add itself to certain privileged groups in Oracle Internet Directory, if it needs specific privileges. Table 12-1, "Some Useful Privilege Groups" shows some of the privileged groups that an application can add itself to. Each of these groups exists in every realm and also in the RootOracleContext. The RootOracleContext Group is a member of the group in all the realms

Table 12-1 Some Useful Privilege Groups

Group Name Privilege

OracleDASCreateUser

Create a public user

OracleDASEditUser

Edit a public user

OracleDASDeleteUser

Delete a public user

OracleDASCreateGroup

Create a new public group

OracleDASEditGroup

Edit a public group

OracleDASDeleteGroup

Delete a public group


For example, the following LDIF file adds the Files-App1 application to cn=OracleCreateUser, which gives it the privilege to create users in all realms.

dn:cn=OracleCreateUser,cn=Groups,cn=OracleContext 
changetype: modify
add: uniquemember
uniquemember: orclApplicationCommonName=Files-App1,cn=FILES,cn=Products,cn=OracleContext

12.1.1.2 Provisioning Configuration

An application's provisioning configuration is maintained in its provisioning profile. The provisioning system supports three different provisioning profile versions: Versions 1.1, 2.0 and 3.0. The provisioning service provides different service for the different profile version. Some generic configuration details are common to all applications, regardless of version.

Differences Between Provisioning Configuration Versions

The differences between the Version 3.0 profile and the Version 2.0 and Version 1.1 profiles are as follows:

  • The new provisioning framework recognizes only Version 3.0 applications. Therefore, only applications with provisioning profile Version 3.0 show up as target applications to be provisioned in Oracle Provisioning Console. Applications with Version 2.0 and Version 1.1 profiles do not show them up as applications to be provisioned in the Provisioning Console. Still, the applications are notified about the events that the applications have configured for.

  • Creating the provisioning configuration of an application is a multi step process for Version 3.0 profiles. For the earlier version profiles, provisioning registration requires only a single step, running the oidprovtool command.

  • Applications can subscribe for provisioning events using different interfaces. Two of the interfaces, Java and OID-LDAP, are available only for interface Version 3.0, which is coupled with provisioning configuration Version 3.0. See Table 12-2, "Interfaces and Their Configuration".

  • An application can specify its application-specific user attributes configuration in an LDIF file. This is supported only for interface Version 3.0, which is coupled with provisioning configuration Version 3.0. See "Application User Attribute and Defaults Configuration"

  • The provisioning status of the user, discussed in the Oracle Fusion Middleware Administrator's Guide for Oracle Directory Integration Platform, is maintained only for Version 3.0 applications. It is not maintained for applications having profiles earlier than Version 3.0.

  • Event propagation configuration parameters vary from one version to another. See Table 12-5, "Event propagation parameters".

Version 3.0-Specific Provisioning Configuration

Unless otherwise stated, the remainder of this section describes the Version 3.0-specific provisioning configuration. Figure 12-1 shows the DIT in Oracle Internet Directory used to store the provisioning configuration. All the provisioning configuration information is located under the following container:

cn=Provisioning,cn=Directory Integration Platform,cn=Products,cn=OracleContext

Common provisioning configuration information is stored in entries under the container:

cn=Profiles,cn=Provisioning,cn=Directory Integration Platform,
 cn=Products,cn=OracleContext

The rest of the provisioning configuration for an application is located under:

cn=ApplicationType,cn=Applications,cn=Provisioning,
 cn=Directory Integration Platform,cn=Products,cn=OracleContext

All the instances of a specific application type share the configuration under this container. That is, whenever a second instance of an existing application type creates a provisioning profile, all the configuration information under the "cn=ApplicationType" container is shared.

Figure 12-1 The Directory Information Tree for Provisioning Configuration Data

DIT containing Provisioning Config Data

The Profiles container contains the following types of configuration information:

Whenever an instance of an application creates a profile, the new profile is stored as a separate entry under the Profiles container in the following naming format:

orclODIPProfileName=GUID_of_the_Realm_Entry_GUID_of_the_Application_Identity,….

An application must specify the following information when creating a provisioning configuration:

12.1.1.2.1 Application Identity Information

An instance of an application is uniquely identified by the following parameters:

  • Application DN—A unique DN in the Oracle Internet Directory representing the application. This is a mandatory parameter.

  • Application Type— A parameter that is common to all instances of the same application. Multiple instances of a particular type can share some configuration. This is a mandatory parameter.

  • Application Name—This can be separately specified. If not specified, it is extracted from the DN. This is an optional parameter.

  • Application Display Name—A user-friendly name for the application. This shows up on the Provisioning Console as a target provisionable application. This is an optional parameter.

You provide these application identity parameters while creating the provisioning profile by using the following arguments to the $ORACLE_HOME/bin/oidprovtool command line utility, respectively:

  • application_type

  • application_dn

  • application_name

  • application_display_name


See Also:

The oidprovtool command-line tool reference in Oracle Fusion Middleware Reference for Oracle Identity Management.

12.1.1.2.2 Application Identity Realm Information

An application registers for a specific realm in order to provide services to the users of that realm only. An application must create a separate provisioning profile for each of the realms it provides services for. In a multi realm scenario, such as a hosted Oracle Portal scenario, applications must register for individual realms.

Whenever a provisioning administrator for a realm accesses the Provisioning Console, only the applications that are registered for that realm are shown as provisionable target applications.

The application specifies realm information while creating the provisioning profile by using the $ORACLE_HOME/bin/oidprovtool command line utility with the argument organization_dn.


See Also:

The oidprovtool command-line tool reference inOracle Fusion Middleware Administrator's Guide for Oracle Internet Directory.

12.1.1.2.3 Application Provisioning and Default Policy

While creating a provisioning profile, an application can specify whether the Provisioning Console should manage provisioning to that application or not. If not, the application does not show up on the Provisioning Console as an application to be provisioned. However, Oracle Directory Integration and Provisioning still processes this profile and propagates the events as expected.

An application specifies this information while creating the provisioning profile by using the application_isdasvisible argument to the $ORACLE_HOME/bin/oidprovtool command line utility. The default value is TRUE.

An application can configure a default policy determining whether all the users in that realm should be provisioned for that application by default or no users should be provisioned by default. The valid values are

  • PROVISIONING_REQUIRED—all users are provisioned by default

  • PROVISIONING_NOT_REQUIRED—no users are provisioned by default

The default is set to PROVISIONING_REQUIRED

You can override the default policy with application-provided policy plug-ins at run time. In addition, an administrator can override both the default policy and the decision of the policy plug-in.

An application provides the default policy information by using the default_provisioning_policy argument to the $ORACLE_HOME/bin/oidprovtool command line utility.

12.1.1.2.4 Application User Data Location

Application-specific user information is stored in the application-specific containers. If this data is to be managed by the provisioning system, the application must specify the location of these containers during provisioning registration. An application specifies its user data location by using the user_data_location argument to the $ORACLE_HOME/bin/oidprovtool command line utility. The application must ensure that the ACLs on this container allow Oracle Delegated Administration Services and Oracle Directory Integration and Provisioning to manage the information in this container.

12.1.1.2.5 Event Interface Configuration

Applications can subscribe for provisioning events using different interfaces: PLSQL, Java, and OID-LDAP. Table 12-2, "Interfaces and Their Configuration" lists the supported interfaces and their associated configuration. Note that INTERFACE_VERSION is coupled with provisioning profile version.

Table 12-2 Interfaces and Their Configuration

Configuration Parameter PLSQL Java OID-LDAP

INTERFACE_VERSION

1.1, 2.0, 3.0

3.0

3.0

INTERFACE_NAME

The name of the PLSQL package that implements the Interface

Not used

Not used

INTERFACE_CONNECT_INFO

The Database Connect String. Multiple formats supported for all versions.

Not used

Not used

INTERFACE_ADDITIONAL_INFO

Not used

Not used

Not used

Plugin types

PRE_DATA_ENTRY, POST_DATA_ENTRY, DATA_ACCESS

PRE_DATA_ENTRY, POST_DATA_ENTRY, DATA_ACCESS, EVENT_DELIVERY (MUST)

PRE_DATA_ENTRY, POST_DATA_ENTRY, DATA_ACCESS

Description

Mainly for applications that have an Oracle Database back end. The DIP Server pushes the event to the remote Database by invoking the PLSQL procedure.

If the Interface Type is JAVA, an event delivering plug-in must be configured or the server gives errors. The plug-in configuration determines the rest of the configuration. See Application Provisioning Plug-in Configuration.

Mainly used in cases where the application is very tightly bound to Oracle Internet Directory and event delivery through the PLSQL interface or the JAVA Event Delivery Plug-in is unnecessary. This interface is deprecated in future. Please use the JAVA Interface instead.


Applications can use the following arguments to $ORACLE_HOME/bin/oidprovtool when specifying an event interface configuration:

  • interface_type (Default is PLSQL)

  • interface_version (Default is 2.0)

  • interface_name

  • interface_connect_info

  • interface_additional_info

Table 12-3, "Information Formats Supported by the PLSQL Interface" lists the interface connection information formats that the PL/SQL interface supports when it connects to a remote database. All the formats are supported for all interface versions.

Table 12-3 Information Formats Supported by the PLSQL Interface

Format Description

dbHost:dbPort:dbSID:username:password

Old format, not recommended. Oracle Directory Integration and Provisioning passes this to the thin JDBC Driver.

dbHost:dbPort:dbServiceName:username:password

Newer format. Not Recommended for High Availability implementations, as the database host and port might change in such scenarios. DIP passes this to the thin JDBC Driver.

DBSVC=DB_TNS_Connect_Sring_Alias:username:password

Used by JDBC thick OCI Driver. The local tnsnames.ora file must contain this alias on the node where DIP is running.

DBURL=ldap://LDAP_host:LDAP_port/ServiceName,cn=OracleContext

Recommended format, as it takes care of High Availability requirements. DIP passes this to the thin JDBC Driver and the driver looks up the Database Registration entry in Oracle Internet Directory to get the actual Database connection information.


Some examples of supported formats are:

   localhost:1521:iasdb:scott:tiger
   localhost:1521:iasdbsvc:scott:tiger
   DBSVC=TNSALIAS:scott:tiger
   DBURL=ldap://example.com:3060/samplegdbname:scott:tiger
12.1.1.2.6 Application User Attribute and Defaults Configuration

An application can specify its application-specific user attributes configuration in an LDIF file. This is supported only for interface version 3.0.

As shown in Figure 12-1, "The Directory Information Tree for Provisioning Configuration Data", the configuration for a particular attribute is stored as a separate entry under the container:

"cn=Attributes,cn=User Configuration,cn=Attribute configuration,
 cn=Application_Type,cn=Applications,cn=Provisioning,
 cn=Directory Integration Platform,cn=Products,cn=OracleContext" 

There is no argument to oidprovtool for uploading this information. The application must use an LDAP file and command-line tools to upload its attribute configuration information to Oracle Internet Directory.

Each application-specific attribute is represented as a separate entry. The following example is for the attribute orclFilesDomain:

dn: cn=orclFilesDomain,cn=Attributes,cn=User configuration,cn=Attribute configuration,……
changetype: add
orcldasadminmodifiable: 1
orcldasviewable: 1
displayname: Files Domain
orcldasismandatory: 1
orcldasuitype: LOV
orcldaslov: us.example.com
orcldaslov: oraclecorp.com
orclDASAttrIsUIField: 1
orclDASAttrIsFieldForCreate: 1
orclDASAttrIsFieldForEdit: 1
orclDASAttrToDisplayByDefault: 1
orclDASSelfModifiable: 1
orclDASAttrDisplayOrder: 1
orclDASAttrDefaultValue: oraclecorp.com
orclDASAttrObjectClass: orclFILESUser
objectclass: orclDASConfigAttr
objectclass: orclcontainer

Table 12-4, "Properties Stored as Attributes in the Attribute Configuration Entry" explains the significance of each of the properties that are stored as attributes in the attribute configuration entry.

Table 12-4 Properties Stored as Attributes in the Attribute Configuration Entry

Property Name Description Comments

orclDASIsUIField

Whether this property is to be shown in the DAS Console or not

Not Used in 11g Release 1 (11.1.1). All attributes are shown.

orclDASUIType

The Type of the UI Field: singletext, multitext, LOV, DATE, Number, password

Used by Oracle Internet Directory Self-Service Console only

orclDASAdminModifiable

Whether the field is modifiable by the administrator or not

Not Used in 11g Release 1 (11.1.1). All attributes are modifiable by administrator.

orclDASViewAble

Whether this attribute is a read-only attribute in the Oracle Internet Directory Self-Service Console

Not Used in 11g Release 1 (11.1.1)

displayName

The Localized Name of the attribute as it shows on the Oracle Internet Directory Self-Service Console


orclDASIsMandatory

Whether this attribute is mandatory or not

If a mandatory attribute is not populated, the Oracle Internet Directory Self-Service Console complains

orclDASAttrIsFieldForCreate

Whether to expose this attribute only during user creation

Not Used in 11g Release 1 (11.1.1)

orclDASAttrIsFieldForEdit

Whether to expose this attribute only during user editing

Not Used in 11g Release 1 (11.1.1)

orclDASAttrToDisplayByDefault

Whether to hide the attribute by default under a collapsed section

Not Used in 11g Release 1 (11.1.1)

orclDASSelfModifiable

Whether this attribute is modifiable by the user or not

Not Used in 11g Release 1 (11.1.1), as Oracle Internet Directory Self-Service Console is only for application-specific attributes. Users cannot change their user preferences from the Oracle Internet Directory Self-Service Console.

OrclDASAttrDisplayOrder

The order is which the attribute is to be displayed in the application-specific section

Not Used in 11g Release 1 (11.1.1)

OrclDASAttrDefaultValue

The initial default value for the attribute that is used by the provisioning components: Oracle Internet Directory Self-Service Console, Oracle Directory Integration and Provisioning, Bulk Provisioning Tool

Can be changed using the Oracle Internet Directory Self-Service Console Application Management Page. The Plug-ins or the administrator can override the initial default values.

OrclDASAttrObjectClass

The LDAP object class that the attribute belongs to.

Used to create the application-specific user entries that the provisioning system maintains.


If an application has application-specific attributes, you can specify that the provisioning system manage its attributes defaults. You do that by using the manage_application_defaults argument to $ORACLE_HOME/bin/oidprovtool. This argument is TRUE by default.

12.1.1.2.7 Application Provisioning Plug-in Configuration

Application provisioning plug-ins are discussed in

Appendix A, "Java Plug-ins for User Provisioning".

12.1.1.2.8 Application Propagation Configuration

Event propagation configuration parameters vary from one profile version to another. Table 12-5, "Event propagation parameters" lists and describes configuration parameters for event propagation.

Table 12-5 Event propagation parameters

Parameter Supported Provisioning Profile Version Description

profile_mode

2.0,.3.0

Whether the application is to receive outbound provisioning events from Oracle Internet Directory, to send inbound events, or both. Values are OUTBOUND (default), INBOUND, and BOTH.

Schedule

1.1, 2.0, 3.0

The scheduling interval after which pending events are propagated

enable_bootstrap

3.0

Enables events for application bootstrapping. This specifies that the application should be notified of users that existed in Oracle Internet Directory before the application created its provisioning profile.

enable_upgrade

3.0

Enables events for application user upgrade. This specifies that the application should be notified of users that existed in Oracle Internet Directory before the upgrade. If the application was present before the upgrade, users might already exist in the application. For such users, Oracle Directory Integration and Provisioning sends an Upgrade Event to the application so that the user is handled differently from a normal new user.

lastchangenumber

3.0

The change number in Oracle Internet Directoryfrom which the events need to be sent to the application.

max_prov_failure_limit

3.0

The maximum number of retries that the Oracle Directory Integration and Provisioning server attempts when provisioning a user for that application.

max_events_per_invocation

2.0, 3.0

For bulk event propagation, this specifies the maximum number of events that can be packaged and sent during one invocation of the event interface.

max_events_per_schedule

2.0

Maximum number of events that Oracle Directory Integration and Provisioning sends to an application in one execution of the profile. The default is 25. In deployments with many profiles and applications, this enables Oracle Directory Integration and Provisioning, which is multithreaded, to execute threads for multiple profiles.

event_subscription

1.1, 2.0, 3.0

Defines the types of OUTBOUND events an application is to receive from the event propagation service. The format is:

Object_Type:Domain:Operation(Attributes,…)

For example:

USER:cn=users,dc=example,dc=com:ADD(*)

specifies that USER_ADD event should be sent if the user that was created is under the specified domain and that all attributes should also be sent.

USER:cn=users,dc=example,dc=com:MODIFY(cn,sn.mail,telephonenumber)

specifies that USER_MODIFY event should be sent if the user that was modified is under the specified domain and any of the listed attributes were modified

USER:cn=users,dc=example,dc=com:DELETE

specifies that USER_DELETE event should be sent if a user under the specified domain was deleted

event_permitted_operations

2.0

Defines the types of INBOUND events an application is privileged to send to the Oracle Directory Integration and Provisioning server. The format is:

Object_Type:Domain:Operation(Attributes,…)

For example:

IDENTITY:cn=users,dc=example,dc=com:ADD(*)

specifies that IDENTITY_ADD event is allowed for the specified domain and all attributes are also allowed. This means that the application is allowed to create users in Oracle Internet Directory.

 IDENTITY:cn=users,dc=example,dc=com:MODIFY(cn,sn.mail,telephonenumber)

Specifies that IDENTITY_MODIFY is allowed for only the attributes in the list. Other attributes are silently ignored. This means that the application is allowed to modify the listed attributes of the users in Oracle Internet Directory.

IDENTITY:cn=users,dc=example,dc=com:DELETE

Specifies that the application is allowed to delete users in Oracle Internet Directory

event_mapping_rules

2.0

For INBOUND profiles, this specifies the type of object received from an application and a qualifying filter condition to determine the domain of interest for this event. Multiple rules are allowed. The format is:

Object_Type: Filter_condition: Domain_Of_Interest

For example:

EMP::cn=users,dc=example,dc=com

specifies that if the object type received is EMP, the event is meant for the domain "cn=users,dc=example,dc=com".

EMP:l=AMERICA:l=AMER,cn=users,dc=example,dc=com

specifies that if the object type received is EMP, and the event has the attribute l (locality) and its value is AMERICA, the event is meant for the domain "l=AMER,cn=users,dc=example,dc=com".


12.1.1.2.9 Application Event Propagation Run Time Status

The Oracle Provisioning Service records a user's provisioning status in Oracle Internet Directory for each provisioning-integrated application. This is described in the Deploying and Configuring Provisioning chapter of Oracle Fusion Middleware Administrator's Guide for Oracle Directory Integration Platform.

12.1.2 Application Configuration Classes

The oracle.idm.user.provisioning.configuration.Configuration class enables you to obtain provisioning schema information. The oracle.idm.user.provisioning.configuration.Application class enables you to obtain metadata for registered applications. These classes are documented under the package oracle.idm.provisioning.configuration.

The Configuration class provides access to application configurations. To construct, a Configuration object, you must specify the realm. For example:

Configuration cfg = new Configuration ("us");

Then you use Configuration class methods to get one or all application configurations in a realm. You must supply the LDAP context of the realm.

The Configuration object is a fairly heavy weight object, as its creation requires access to the Oracle Internet Directory metadata. Best practice is to create a Configuration object once during initialization of an application, then to reuse it for all operations that require it.

The Application object represents an application instance. Its methods provide metadata about a registered application in the infrastructure.

12.2 User Management

When Oracle Directory Integration and Provisioning or Oracle Delegated Administration Services invokes a provisioning plug-in, it passes information about the user being provisioned. A deployed application can use the user object to modify the user.

The user management provisioning classes provide the following operations:

This section includes the following topics:

12.2.1 Creating a User

Creating a user in the Oracle Identity Management repository consists of two steps:

  1. Creating basic user information in the specified realm. This information is referred to as the base user.

  2. Creating the application-specific user attributes, or footprint. This information is referred to as the application user.

The combination of the base user and application user in the repository is referred to as the Oracle Identity Management user. Some methods create only the base user and other create both components of the Oracle Identity Management user.

The minimum information required to create a user is a set of attributes representing the base user. The attributes are in the form of name-value pairs. These user attributes are represented as Java objects using the class oracle.ldap.util.ModPropertySet.

Some user creation methods require you to specify the DN of the entry that you want to create in the Oracle Identity Management user repository. Other methods do not require the DN. Instead, they construct the Oracle Identity Management user using the metadata configuration information from the Realm in which the user is created.

If the creation of the base user and application user succeeds, then the creation method returns an IdmUser object. You use this object to manage the attributes of the base user and application user.

12.2.2 Modifying a User

Modifying a base user in the Oracle Identity Management repository results in

  • Modifying the base user information

  • Creating or modifying application user information

You must supply the following information in order to modify an Oracle Identity Management user:

  1. The user's DN, GUID, or IdmUser object reference

  2. The desired changes to the base user attributes, represented as an oracle.ldap.util.ModPropertySet

Some user modification methods modify only the base user attributes. Others modify the application user attributes as well.

12.2.3 Deleting a User

Deleting a base user in the Oracle Identity Management repository produces the following results:

  • Deleting the base user information

  • Deleting the application user information

To modify an Oracle Identity Management user, you must supply the DN, GUID, or IdmUser object reference.

As result of this operation, the base user and the application user attributes are deleted.

12.2.4 Looking Up a User

The lookup methods provide two lookup options:

  • Look up a specific Oracle Identity Management user using GUID or DN

  • Look up a set of Oracle Identity Management users using a search filter

In order to look up Oracle Identity Management users, you must provide the DN or GUID.

The output of a lookup method is one of the following:

  • A single IdmUser object

  • A list of IdmUser objects

12.3 Debugging

Set UtilDebug.MODE_PROVISIONING_API mode to enable debugging and trace information. If you do not specify an output stream for the log messages, they are written to standard output.

The following snippet shows how to set UtilDebug.MODE_PROVISIONING_API mode and specify an output stream:

Import oracle.ldap.util.UtilDebug;
        FileOutputStream logStream = new FileOutputStream("ProvAPI.log")
        …
        UtilDebug.setDebugMode(UtilDebug.MODE_PROVISIONING_API);
UtilDebug.setPrintStream(logStream);

12.4 Sample Code

The following code example shows how to create, modify, and look up a user and how to get user provisioning status for an application.

UtilDebug.setDebugMode(UtilDebug.MODE_PROVISIONING_API);
…
Configuration cfg = new Configuration(realm);
    try {
      debug("Connecting...");
      InitialLdapContext ctx =
          ConnectionUtil.getDefaultDirCtx(hostName, port, bindDn, passwd);
      debug("Connected...");
      UserFactory factory = UserFactoryBuilder.createUserFactory(ctx, cfg);

      // Create 
      ModPropertySet mpSet = new ModPropertySet(); 
      mpSet.addProperty("cn","Heman");
      mpSet.addProperty("sn","The Master");
      mpSet.addProperty("uid","Heman");
      IdmUser idmUser = factory.createUser(mpSet);

      // Modify 
      mpSet = new ModPropertySet();
      mpSet.addProperty(LDIF.ATTRIBUTE_CHANGE_TYPE_REPLACE,"sn",
            "Heman The Master");
      mpSet.addProperty("givenName","Master of the Universe");
      factory.modifyUser(idmUser, mpSet);

              // Lookup         List users = factory.searchUsers(Util.IDTYPE_SIMPLE, "Hema*", null);
        ….

        // Get user provisioning status for an application.
              Application app = cfg.getApplication(lCtx, "Files", "FilesInstace");
        String  status = idmUser.getProvisioningStatus(app);


      // Another way to get user provisioning status
              String userDn = idmUser.getDNn();
        String  status = ProvUtil.getUserProvisioningStatus(dirctx, 
            Util.IDTYPE_DN, userDn, app.getType(), app.getName());
    } catch (Exception ex) {
      ex.printStackTrace();
       //
   }