| Oracle® Collaboration Suite Administrator's Guide 10g Release 1 (10.1.1) for Windows or UNIX Part Number B14476-03 |
|
|
View PDF |
| Oracle® Collaboration Suite Administrator's Guide 10g Release 1 (10.1.1) for Windows or UNIX Part Number B14476-03 |
|
|
View PDF |
As of Oracle Application Server 10g Release 2 (10.1.2.0.2), the Oracle Internet Directory SDK includes a centralized 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:
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:
In order to register with the provisioning system, an application must create a provisioning configuration. Once 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:
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 Content Services. 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 Content-App1 and the type of the application is CONTENT. 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=IFS,cn=Products,cn=OracleContext changetype: add objectclass: orclContainer dn: orclApplicationCommonName=Content-App1,cn=CONTENT,cn=Products,cn=OracleContext changetype: add orclappfullname: Content 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 as well as 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 Content-App2.
dn: orclApplicationCommonName=Content-App2,cn=IFS,cn=Products,cn=OracleContext changetype: add orclappfullname: Content Application Instance 2 userpassword: welcome123 description: This is a test Application 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)
Once 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 C-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 C-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 Content-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=Content-App1,cn=IFS,cn=Products,cn=OracleContext
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 C-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 Identity Management Integration Guide, 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 C-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 C-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 C-1 The Directory Information Tree for Provisioning Configuration 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:
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
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 OracleAS 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.
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 will be provisioned by default
PROVISIONING_NOT_REQUIRED—no users will be 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.
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.
Applications can subscribe for provisioning events using different interfaces: PLSQL, Java, and OID-LDAP. Table C-2, "Interfaces and Their Configuration" lists the supported interfaces and their associated configuration. Note that INTERFACE_VERSION is coupled with provisioning profile version.
Table C-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 backend. 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 will give 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 will be 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 C-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 C-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 |
|
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://acme.com:389/samplegdbname:scott:tiger
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 C-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 orclContentDomain:
dn: cn=orclContentDomain,cn=Attributes,cn=User configuration,cn=Attribute configuration,…… changetype: add orcldasadminmodifiable: 1 orcldasviewable: 1 displayname: Content Domain orcldasismandatory: 1 orcldasuitype: LOV orcldaslov: us.oracle.com orcldaslov: oraclecorp.com orclDASAttrIsUIField: 1 orclDASAttrIsFieldForCreate: 1 orclDASAttrIsFieldForEdit: 1 orclDASAttrToDisplayByDefault: 1 orclDASSelfModifiable: 1 orclDASAttrDisplayOrder: 1 orclDASAttrDefaultValue: oraclecorp.com orclDASAttrObjectClass: orclCONTENTUser objectclass: orclDASConfigAttr
Table C-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 C-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 10g Release 1 (10.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 10g Release 1 (10.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 10g Release 1 (10.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 10g Release 1 (10.1.1). |
|
orclDASAttrIsFieldForEdit |
Whether to expose this attribute only during user editing. |
Not Used in 10g Release 1 (10.1.1). |
|
orclDASAttrToDisplayByDefault |
Whether to hide the attribute by default under a collapsed section. |
Not Used in 10g Release 1 (10.1.1). |
|
orclDASSelfModifiable |
Whether this attribute is modifiable by the user or not. |
Not Used in 10g Release 1 (10.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 10g Release 1 (10.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.
Event propagation configuration parameters vary from one profile version to another. Table C-5, "Event propagation parameters" lists and describes configuration parameters for event propagation.
Table C-5 Event propagation parameters
| Parameter | Supported 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 multi threaded, 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=acme,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=acme,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=acme,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=acme,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=acme,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=acme,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=acme,dc=com specifies that if the object type received is EMP:l=AMERICA:l=AMER,cn=users,dc=acme,dc=com specifies that if the object type received is |
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 Identity Management Integration Guide.
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.
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:
Create, modify, and delete a base user
Create, modify, and delete application-specific user information
Search base users
Retrieve user provisioning status for applications
This section includes the following topics:
The entry point into the user management provisioning API is the oracle.idm.user.UserFactoryBuilder class. You use UserFactoryBuildermethods to create a user factory object, oracle.idm.user.UserFactory. Then you use UserFactory methods to create and manage users. All these methods are documented in the Oracle Internet Directory API reference, under the package oracle.idm.user.
UserFactoryBuilder provides static createUserFactory methods to create a UserFactory object. Some of the UserFactoryBuilder methods use the JNDI access method for the default realm.
You create, modify, delete, and look up users using the UserFactory interface methods. In deployments of Oracle Collaboration Suite, you can use plug-ins to customize provisioning policy evaluation and data validation performed by the UserFactory methods.
See Also:
"Java Plug-ins for User Provisioning"for more information about provisioning plug-ins.The following code snippet shows creation of a UserFactory:
// Context to Identity Management Repository. DirContext dirCtx = new InitialLdapContext(); UserFactory userFactory = UserFactoryBuilder.createUserFactory(dirCtx, "US");
Best practice is to create only one UserFactory object during the initialization phase of your application. Then, whenever you need to create, modify, delete, or look up a user, you use the same UserFactory. For performance reasons, the API does not provide thread safety for UserFactory objects. If you are creating a multi threaded application, you must implement your own thread synchronization.
Alternatively, you can create a pool of UserFactory objects. Then, whenever you need to perform a user management function, you use one of the objects.
A user factory control object, oracle.idm.user.UserFactoryControl, encapsulates information that controls the behavior of the UserFactory class methods. The UserFactoryControl can contain the following information:
The applications for which the user needs to be provisioned
Whether the base user can be created, modified, or deleted
Whether the application-specific user can be created, modified, or deleted
Whether or not to perform the Oracle Delegated Administration Services mandatory attribute check
The stream for writing logging information
Creating a user in the Oracle Identity Management repository consists of two steps:
Creating basic user information in the specified realm. This information is referred to as the base user.
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.
The following UserFactoryControl information affects Oracle Identity Management user creation:
Whether or not to create the base user
Whether or not to create the application user
The list of applications for which the application user needs to be 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.
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:
The user's DN, GUID, or IdmUser object reference.
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.
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.
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
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);
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, "Content",
"ContentInstance");
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();
//
}
This appendix explains how to use plug-ins to customize provisioning policy evaluation and data validation in deployments of Oracle Collaboration Suite. These plug-ins can be used by PL/SQL and Java interfaces.
Oracle Directory Integration and Provisioning cannot support all of the provisioning needs of a deployment. Hence, hooks are provided at various stages of user creation, modification, and deletion. These hooks enable an enterprise to incorporate its own business rules and to tailor footprint creation to its needs. The hooks take the form of Java plug-ins.
The appendix contains these topics:
There are two types of plug-ins:
Data entry plug-ins
Data access plug-ins
Oracle Delegated Administration Services, Oracle Internet Directory Integration and Provisioning, and other mechanisms that affect the base user footprint in the directory invoke these plug-ins when the footprint is created. By configuring a data entry plug-in, a deployment can do any of the following:
Validate attribute values for application users
Validate attribute values for base users
Enhance attribute values for application users
Enhance attribute values for base users
Evaluate provisioning policies
If you want the deployed application to maintain application user information you must configure a data access plug-in for it. This type of plug-in enables you to maintain the application footprint either outside of the directory or within it as several entries.
Data entry and data access plug-ins are typically invoked from one of these environments:
User provisioning console for Oracle Delegated Administration Services
Oracle Directory Integration and Provisioning service
Provisioning API
Bulk Provisioning Tools
All of the plug-ins that you provide for an application must be in a JAR file that can be uploaded to the directory with the standard LDIF template. See "Configuration Template" for an example. The plug-in interface definitions are found in ORACLE_HOME/jlib/ldapjclnt10.jar. Refer to Oracle Internet Directory API Reference and the public interfaces for a more detailed description. If the application requires additional jar files, you can upload them too.
Data entry plug-ins take two forms:
Pre–data-entry plug-ins
Post–data-entry plug-ins
If you want to use either of these plug-ins, you must implement the oracle.idm.provisioning.plugin.IdataEntryPlugin interface. This interface has three methods. Here it is:
/**
* The applications can perform a post data entry operation by
* implementing this method.
*
* @param appCtx the application context
* @param idmUser the IdmUser object
* @param baseUserAttr Base user properties
* @param appUserAttr App user properties
* @throws PluginException when an exception occurs.
*/
public PluginStatus process(ApplicationContext appCtx,
IdmUser idmUser, ModPropertySet baseUserAttr,
ModPropertySet appUserAttr)throws PluginException;
/**
* Returns the Modified Base User properties
*
* @return ModPropertySet modified base user properties.
*/
public ModPropertySet getBaseAttrMods();
/**
* Returns the Modified App User properties
*
* @return ModPropertySet modified app user properties.
*/
public ModPropertySet getAppAttrMods();
Typically the plug-in implementor uses these methods to validate data or to decide whether a user should be provisioned. In the latter case, a base user attribute is used to make the decision.
The application context object contains this information:
LDAP directory context
If you want the application to perform a directory operation, you can have it obtain the LDAP context from the application object. Note that this LDAP context should not be closed in the plug-in.
Plug-in call mode
The plug-in is called from Oracle Delegated Administration Services, Oracle Directory Integration and Provisioning, or another environment that invokes the provisioning API. If the calling environment is Oracle Directory Integration and Provisioning, the provisioning service calls the plug-in. The two possible values are INTERACTIVE_MODE and AUTOMATIC_MODE. The first indicates that the plug-in was invoked through interaction between Oracle Delegated Administration Services and a client application. The second indicates that the plug-in was invoked by Oracle Directory Integration and Provisioning, where user intervention does not occur.
Client locale
The plug-in may want to know what the client locale is, especially if it is invoked from Oracle Delegated Administration Services.
Plug-in call operation
You may decide to have data entry plug-ins for both create and modify user operations. You may even implement these plug-ins in the same class. Under these conditions, the plug-in must determine which operation is invoked. The application context object uses the values OP_CREATE and OP_MODIFY to identify the operation.
Plug-in invocation point
The data entry plug-in is typically used to determine whether a user needs to be provisioned for an application. The policy evaluation and data validation that occurs can be performed in either a pre–data-entry plug-in or a post–data-entry plug-in. You may choose either or both. If you choose both, you can implement them in the same class. The application context object specifies which one is actually invoked. It uses the values PRE_DATA_ENTRY and POST_DATA_ENTY to do this.
Callback context
If you decide to have both pre and post plug-ins for an operation and you want the pre plug-in to share information with the post plug-in, you can set the callback context in the application context object of the pre–data-entry plug-in. The post– data-entry plug-in can then obtain and use this callback context.
Logging
You can use the log methods provided in the application context object to log information for the plug-in.
The calling sequence looks like this:
Download and instantiate a plug-in object based on the configuration information object in Oracle Internet Directory
Construct an application context object that will be passed to the plug-in.
Call process method()
Call getBaseAttrMods() to obtain base user attributes that are modified in process().
Merge the base user attributes returned by getBaseAttrMods() with the base user attributes, depending on the plug-in execution status. The execution status can be either success or failure. The plug-in implementor must return a valid plug-in execution status object. If null is returned, the execution status is considered a failure.Merging of the base user will only be done if the plug-in execution status is successful.
Call getAppAttrMods() for the plug-in. This method obtains application user attributes that are modified in process().
Merge the application user attributes returned by getAppAttrMods() with the application user attributes, depending on the user provisioning status returned by the plug-in.
The pre–data-entry plug-in generates values for application attributes. The attribute defaults specified during application registration are passed to this plug in along with the current base user attributes. The returned values are displayed in the UI if the invocation environment is interactive like Oracle Delegated Administration Services.
The pre–data-entry plug-in can decide whether the user should be provisioned for an application. The plug-in examines base user attributes to make the decision. It is invoked during create and modify operations. You can support both operations with one plug-in class, or you can assign one class to each.
If the application decides to have pre–data- entry plug-ins for create and modify operations, two configuration entries must be created in Oracle Internet Directory under the application container. The first entry is for the create operation:
This
dn: cn=PRE_DATA_ENTRY_CREATE, cn=Plugins, cn=CONTENT, cn=Applications, cn=Provisioning, cn=Directory Integration Platform, cn=Products, cn=OracleContext changetype: add objectClass: orclODIPPlugin orclStatus: ENABLE orclODIPPluginExecName: oracle.myapp.provisioning.UserCreatePlugin orclODIPPluginAddInfo: Pre Data Entry Plugin for CREATE operation
The second entry is for the modify operation:
dn: cn=PRE_DATA_ENTRY_MODIFY, cn=Plugins, cn=CONTENT, cn=Applications, cn=Provisioning, cn=Directory Integration Platform, cn=Products, cn=OracleContext changetype: add objectClass: orclODIPPlugin orclStatus: ENABLE orclODIPPluginExecName: oracle.myapp.provisioning.UserModifyPlugin orclODIPPluginAddInfo: Pre Data Entry Plugin for MODIFY operation
In this example, separate classes for create and modify plug-ins are shown.
The post–data-entry plug-in validates data entered by the user in the UI. In addition, it generates derived attribute values. If the plug in fails for any one application, the UI does not proceed. All applications must successfully validate the data before a user entry can be created in the directory. However, in the case of non-UI environment or automatic route, the plug-in implementor can decide to raise an error or continue, based on the plug-in call mode (INTERACTIVE_MODE or AUTOMATIC_MODE).
Like the pre–data-entry plug-in, the post–data-entry plug-in is invoked during create and modify operations. The application can decide to implement one plug-in class for both operations or a separate class for each.
If you decide to have post–data-entry plug-ins for create and modify operations, create two configuration entries in Oracle Internet Directory under the application container. The first entry is for the create operation:
dn: cn=POST_DATA_ENTRY_CREATE, cn=Plugins, cn=CONTENT, cn=Applications, cn=Provisioning, cn=Directory Integration Platform, cn=Products, cn=OracleContext changetype: add objectClass: orclODIPPlugin orclStatus: ENABLE orclODIPPluginExecName: oracle.myapp.provisioning.UserMgmtPlugin orclODIPPluginAddInfo: Post Data Entry Plugin for CREATE and MODIFY operations
The second entry is for the modify operation:
dn: cn=POST_DATA_ENTRY_MODIFY, cn=Plugins, cn=CONTENT, cn=Applications, cn=Provisioning, cn=Directory Integration Platform, cn=Products, cn=OracleContext changetype: add objectClass: orclODIPPlugin orclStatus: ENABLE orclODIPPluginExecName: oracle.myapp.provisioning.UserMgmtPlugin orclODIPPluginAddInfo: Post Data Entry Plugin for MODIFY and CREATE operation
In this example, too, separate classes for create and modify plug-ins are shown.
The primary purpose of the data access plug in is to manage the application-specific footprint of the user in the directory. You can use this plug-in to create and retrieve the footprint.
The data access plug-in invoked whenever a user is created and is requesting provisioning for an application—whether by Oracle Delegated Administration Services, by Oracle Directory Integration and Provisioning, or by bulk provisioning tools.
The data access plug-in is invoked during modify and delete operations as well. It can update the application footprint or remove it.
If you want to use the data access plug-in, implement the interface oracle.idm.provisioning.plugin.IDataAccessPlugin. Here is the interface:
/**
* The applications can create/modify/delete the user footprint by
* implementing this method.
*
* @param appCtx the application context
* @param idmUser IdmUser object
* @param baseUserAttr Base user properties
* @param appUserAttr App user properties
*
* @return PluginStatus a plugin status object, which must contain
* the either <codE>IdmUser.PROVISION_SUCCESS</CODE> or
* <codE>IdmUser.PROVISION_FAILURE</CODE> provisioning status
*
* @throws PluginException when an exception occurs.
*/
public PluginStatus process(ApplicationContext appCtx,
IdmUser idmUser, ModPropertySet baseUserAttr,
ModPropertySet ppUserAttr) throws PluginException;
/**
* The applications can return their user footprint by
* implementing this method. Use <CODE>
* oracle.ldap.util.VarPropertySet </CODE>
* as the return object
*
* <PRE>
* For Ex.
* PropertySet retPropertySet = null;
* retPropertySet = new VarPropertySet();
*
* //Fetch the App data and add it to retPropertySet
* retPropertySet.addProperty("name", "value");
* ..
* return retPropertySet;
* </PRE>
*
* @throws PluginException when an exception occurs.
*/
public PropertySet getAppUserData(ApplicationContext appCtx,
IdmUser user, String reqAttrs[]) throws PluginException;
If you want to manage the user footprint for an application, create a plug-in configuration entry in the directory under the application container. The example that follows shows what this entry looks like:
dn: cn=DATA_ACCESS, cn=Plugins, cn=FILES, cn=Applications, cn=Provisioning, cn=Directory Integration Platform, cn=Products, cn=OracleContext changetype: add objectClass: orclODIPPlugin orclStatus: ENABLE orclODIPPluginExecName: oracle.myapp.provisioning.UserDataAccPlugin orclODIPPluginAddInfo: Data Access Plugin
Each of the provisioning plug-ins must return an object of the class oracle.idm.provisioning.plugin.PluginStatus This object indicates the execution status, which is either success or failure. The object can return the user provisioning status as well.
The LDIF template provided here is used in Oracle Collaboration Suite 10g Release 1 (10.1.1) to specify the application plug-in. You must create a directory entry for the application and upload the JAR file that contains the classes that implement the plug-in.
dn: cn=Plugins, cn=APPTYPE, cn=Applications, cn=Provisioning, cn=Directory Integration Platform,cn=Products,cn=OracleContext changetype: add add: orclODIPPluginExecData orclODIPPluginExecData: full_path_name_of_the_JAR_file objectclass: orclODIPPluginContainer
dn: cn=PRE_DATA_ENTRY_CREATE, cn=Plugins, cn=APPTYPE, cn=Applications, cn=Provisioning, cn=Directory Integration Platform, cn=Products, cn=OracleContext cn=Provisioning, cn=Directory Integration Platform, cn=Products, cn=OracleContext changetype: add objectClass: orclODIPPlugin orclStatus: ENABLE orclODIPPluginExecName: Name_of_the_class_that_implements_the_plug-in orclODIPPluginAddInfo: Pre Data Entry Plugin for CREATE operation
dn: cn=PRE_DATA_ENTRY_MODIFY, cn=Plugins, cn=APPTYPE, cn=Applications,
cn=Provisioning, cn=Directory Integration Platform, cn=Products,
cn=OracleContext
changetype: add
objectClass: orclODIPPlugin
orclStatus: ENABLE
orclODIPPluginExecName: Name_of_the_class_that_implements_the_plug-in
orclODIPPluginAddInfo: Pre Data Entry Plugin for MODIFY operation
dn: cn=POST_DATA_ENTRY_CREATE, cn=Plugins, cn=APPTYPE, cn=Applications, cn=Provisioning, cn=Directory Integration Platform, cn=Products, cn=OracleContext changetype: add objectClass: orclODIPPlugin orclStatus: ENABLE orclODIPPluginExecName: Name_of_the_class_that_implements_the_plug-in orclODIPPluginAddInfo: Post Data Entry Plugin for CREATE and modify operations
dn: cn=POST_DATA_ENTRY_MODIFY, cn=Plugins, cn=APPTYPE, cn=Applications, cn=Provisioning, cn=Directory Integration Platform, cn=Products, cn=OracleContext changetype: add objectClass: orclODIPPlugin orclStatus: ENABLE orclODIPPluginExecName: Name_of_the_class_that_implements_the_plug-in orclODIPPluginAddInfo: Post Data Entry Plugin for MODIFY and CREATE operation
dn: cn=DATA_ACCESS, cn=Plugins, cn=APPTYPE, cn=Applications, cn=Provisioning, cn=Directory Integration Platform, cn=Products, cn=OracleContext changetype: add objectClass: orclODIPPlugin orclStatus: ENABLE orclODIPPluginExecName: Name_of_the_class_that_implements_the_plug-in orclODIPPluginAddInfo: Data Access Plugin
/* Copyright (c) 2004, Oracle. All rights reserved. */
/**
DESCRIPTION
Sample PRE DATA Entry Plugin for CREATE operation that
validates the attribute.
PRIVATE CLASSES
None.
NOTES
This class implements the PRE_DATA_ENTRY_CREATE plugin ONLY
MODIFIED (MM/DD/YY)
svenugop 12/15/04 \226 Creation
*/
package oracle.ldap.idm;
import java.util.*;
import javax.naming.*;
import javax.naming.ldap.*;
import javax.naming.directory.*;
import oracle.ldap.util.*;
import oracle.idm.provisioning.plugin.*;
/**
* This class implements the PRE_DATA_ENTRY_CREATE plugin ONLY
*
* @author Siva Venugopal
* @since Oracle Collaboration Suite 2.1
*/
public class SamplePreDataEntryCreatePlugin implements IDataEntryPlugin
{
public ModPropertySet mpBaseUser = null;
public ModPropertySet mpAppUser = null;
public PluginStatus process(ApplicationContext appCtx,IdmUser idmuser,
ModPropertySet baseUserAttr, ModPropertySet appUserAttr)
throws PluginException
{
PluginStatus retPluginStatus = null;
String retProvStatus = null;
String retProvStatusMsg = null;
LDIFRecord lRec = null;
LDIFAttribute lAttr = null;
String val = null;
if(null == baseUserAttr.getModPropertyValue(\223departmentNumber\224))
{
mpBaseUser = new ModPropertySet();
mpBaseUser.addProperty("departmentNumber","ST");
appCtx.log(\223Base user attribute \226 departmentNumber missing\224 +
\223Setting default - ST\224);
}
else if ( baseUserAttr.getModPropertyValue(\223departmentNumber\224)
.notIn(\223ST\224, \223APPS\224, \224CRM\224) )
{
throw new PluginException(\223Invalid department Number\224);
}
if((null == appUserAttr) ||
null == appUserAttr.getModPropertyValue(\223emailQouta\224))
{
mpAppUser = new ModPropertySet();
mpAppUser.addProperty("emailQouta","50M");
appCtx.log(\223Application user attribute - email Qouta missing \224 +
\223Setting default - 50M\224);
}
return new PluginStatus(PluginStatus.SUCCESS, null, null);
}
public ModPropertySet getBaseAttrMods()
{
return mpBaseUser;
}
public ModPropertySet getAppAttrMods()
{
return mpAppUser;
}
}
/* Copyright (c) 2004, Oracle. All rights reserved. */
/**
DESCRIPTION
Sample POST DATA Entry Plugin for CREATE operation. Implementing a
policy check to provision only those users who belong to \223SALES\224.
PRIVATE CLASSES
None.
NOTES
This class implements the POST_DATA_ENTRY_CREATE plugin ONLY
MODIFIED (MM/DD/YY)
svenugop 12/15/04 \226 Creation
*/
package oracle.ldap.idm;
import java.util.*;
import javax.naming.*;
import javax.naming.ldap.*;
import javax.naming.directory.*;
import oracle.ldap.util.*;
import oracle.idm.provisioning.plugin.*;
/**
* This class implements the POST_DATA_ENTRY_CREATE plugin ONLY
*
* @author Siva Venugopal
* @since Oracle Collaboration Suite 2.1
*/
public class SamplePostDataEntryCreatePlugin
{
public ModPropertySet mpBaseUser = null;
public ModPropertySet mpAppUser = null;
public PluginStatus process(ApplicationContext appCtx,IdmUser idmuser,
ModPropertySet baseUserAttr, ModPropertySet appUserAttr)
throws PluginException
{
PluginStatus retPluginStatus = null;
String retProvStatus = null;
String retProvStatusMsg = null;
if(null == baseUserAttr.getModPropertyValue(\223deptartmentNumber\224))
{
mpBaseUser = new ModPropertySet();
mpBaseUser.addProperty("deptartmentNumber ","SALES");
appCtx.log("Base user attribute \221c\222 is missing");
retProvStatus = IdmUser.PROVISION_ REQUIRED;
retProvStatusMsg = "Provision policy: Only \221SALES\222\224.
}
else if (baseUserAttr.getModPropertyValue(\223deptartmentNumber\224)
.equals(\223SALES\224))
{
retProvStatus = IdmUser.PROVISION_ REQUIRED;
retProvStatusMsg = "Provision policy: Only \221SALES\222\224.
}
else
{
// do not provision those users who do not belong to SALES.
retProvStatus = IdmUser.PROVISION_NOT_REQUIRED;
retProvStatusMsg =
"Do not provision the person who is not from \221SALES\222";
}
return new PluginStatus(PluginStatus. SUCCESS, retProvStatusMsg,
retProvStatus);
}
public ModPropertySet getBaseAttrMods()
{
return mpBaseUser;
}
public ModPropertySet getAppAttrMods()
{
return mpAppUser;
}
}
/* Copyright (c) 2004, Oracle. All rights reserved. */
/**
DESCRIPTION
Sample DATA Access Plugin.
NOTES
This class implements the DATA_ACCESS plugin
MODIFIED (MM/DD/YY)
svenugop 12/15/04 \226 Creation
*/
package oracle.ldap.idm;
import javax.naming.*;
import javax.naming.ldap.*;
import javax.naming.directory.*;
import oracle.ldap.util.*;
import oracle.idm.provisioning.plugin.*;
/**
* This class implements the DATA_ACCESS plugin ONLY
*
* @author Siva Venugopal
* @since Oracle Collaboration Suite 2.1
*/
public class SampleDataAccessPlugin
{
public PluginStatus process(ApplicationContext appCtx,IdmUser idmuser,
ModPropertySet baseUserAttr,ModPropertySet appUserAttr)
throws PluginException
{
try {
DirContext dirCtx = appCtx.getDirCtx();
if ( appCtx.getCallOp().equals(ApplicationContext.OP_CREATE )
{
// Use the directory context and create the entry.
}
elseif ( appCtx.getCallOp().equals(ApplicationContext.OP_MODIFY)
{
// Use the directory context and modify the entry.
}
} catch (Exception e) {
throw new PluginException(e);
}
return new PluginStatus(PluginStatus.SUCCESS, null, null);
}
public PropertySet getAppUserData(ApplicationContext appCtx,
IdmUser idmuser, String [] reqAttrs) throws PluginException
{
VarPropertySet vpSet = null;
DirContext dirCtx = appCtx.getDirCtx();
try {
Attributes attrs= dirCtx.getAttributes(\223myAppContainer\224);
vpSet = new VarPropertySet(); // Populate the VarPropertySet from attrs
} catch(Exception ne) {
throw new PluginException(e);
}
return vpSet; }
}
