Skip Headers
Oracle® Identity Management User Reference
10g Release 2 (10.1.2)
B15883-01
  Go To Documentation Library
Home
Go To Product List
Solution Area
Go To Table Of Contents
Contents
Go To Index
Index

Previous
Previous
Next
Next
 

6.3 oidprovtool

Provisioning enables you to ensure that an application is notified of directory changes, such as changes to user or group information. Such changes can affect whether the application allows a user access to its processes and resources.

When you install an application that you want to provision, you must create a provisioning integration profile for it by using the Provisioning Registration Tool (oidprovtool). Use this tool to:

The Provisioning Registration Tool shields the location and schema details of the provisioning profile entries from the callers of the tool. From the callers' perspective, the combination of an application and a realm uniquely identify a provisioning profile. The constraint in the system is that there can be only one provisioning profile for each application for each realm.

Once a profile is created, its mode—that is, INBOUND, OUTBOUND, or BOTH—cannot be changed by using the modify operation. To change the mode, you must delete, then re-create, the profile.

The Oracle directory integration and provisioning server automatically monitors provisioning profile configuration changes in Oracle Internet Directory, including the creation, modification, and deletion of provisioning profiles. For this reason, you do not need to manually enable or disable a provisioning profile.

6.3.1 Syntax for oidprovtool

oidprovtool operation=[create|modify] ldap_host=oid_hostname ldap_port=port \
ldap_user_dn="bindDN" ldap_user_password=password \
[profile_mode=INBOUND|OUTBOUND|BOTH]
application_dn="DN" application_type=type [application_name=name] \
[application_display_name=display name] organization_dn=DN \
[application_isdasvisible=TRUE|FALSE] [manage_application_defaults=TRUE|FALSE] \
[enable_bootstrap=TRUE|FALSE]  [user_data_location=DN] \
[default_provisioning_policy=PROVISIONING_REQUIRED|PROVISIONING_NOT_REQUIRED] \
interface_name=SCHEMA.PACKAGE [interface_type=PLSQL|JAVA] \
interface_version=1.1|2.0|3.0] interface_connect_info=connection_string \
schedule=number_seconds lastchangenumber=number   \
max_prov_failure_limit=number  \ 
max_events_per_schedule=number max_events_per_invocation=number \
event_mapping_rules="OBJECT_TYPE:FILTER:DOMAIN" \
event_permitted_operations="OBJECT:DOMAIN:OPERATION(attributes,...)" \
event_subscription="USER|GROUP:DOMAIN:OPERATION(attributes,...)" \
max_events_per_schedule=number max_retries=number profile_group=number \
profile_status=ENABLED | DISABLED profile_debug=debug_level 

oidprovtool {operation=enable|disable|delete|status|reset} 
application_dn=DN [organization_dn=DN] [ldap_host=oid_hostname] [ldap_port=port]
[ldap_user_dn=bindDN] [ldap_user_password=password] [profile_debug=debug_level]

6.3.2 Arguments for oidprovtool

operation=create | modify | enable | disable | delete | status | reset

Required. The operation to perform using oidprovtool. You can only perform one operation at a time. The operations are:

  • create - Creates a new provisioning profile.

  • modify - Modifies the given properties of an existing provisioning profile.

  • enable - Enables a provisioning profile.

  • disable - Disables a provisioning profile.

  • delete - Deletes a provisioning profile.

  • status - Shows the current status of a given provisioning profile.

  • reset - Clears all errors for a provisioning profile.

ldap_host=oid_hostname

Optional. The host name of the Oracle Internet Directory server. If not provided then the name of the local host is used.

ldap_port=port

Optional. The LDAP listening port of Oracle Internet Directory. The default is 389.

ldap_user_dn=bindDN

The DN of the super user or a user that has sufficient permissions to perform provisioning subscription operations. The default is cn=orcladmin.

ldap_user_password=password

The user password used to bind to the directory.

profile_mode=OUTBOUND | INBOUND | BOTH

Optional for the create operation only. The direction of the provisioning events. The default is OUTBOUND (data is provisioned from Oracle Internet Directory to the application).

application_dn=DN

Required. The distinguished name of the application to which the provisioning subscription belongs. The combination of the application DN and organization DN uniquely identifies a provisioning profile. For example, here is the application DN for Portal:

"orclApplicationCommonName=PORTAL,cn=Portal,cn=Products,cn=OracleContext"

application_type=type

Required. The type of application being provisioned.

application_name=name

Optional. The name of the application being provisioned. If not provided, defaults to the distinguished name assigned to application_dn.

application_display_name=name

Optional. The display name of the application being provisioned. If not provided, defaults to the value assigned to application_name.

organization_dn=DN

Optional. If not provided, defaults to the default identity management realm. The distinguished name of the organization to which the provisioning subscription belongs, for example "dc=company,dc=com". The combination of the application DN and organization DN uniquely identifies a provisioning profile.

application_isdasvisible=TRUE | FALSE

Optional. Determines whether the application is visible as a provisioning-integrated application in the Oracle Internet Directory Provisioning Console. The default value is TRUE.

manage_application_default=TRUE | FALSE

Optional. Determines whether the Oracle Internet Directory Provisioning Console manages the application's default values. The default value is TRUE.

enable_bootstrap=TRUE | FALSE

Optional. Indicates whether the application should receive provisioning events for users that existed in Oracle Internet Directory before creating the application's provisioning integration profile. The default value is FALSE.

user_data_location=DN

Optional. Identifies the DN of the container in which to store application-specific user information.

default_provisioning_policy=PROVISIONING_REQUIRED | PROVISIONING_NOT_REQUIRED

Optional. Specifies the application's default provisioning policy. The default value is PROVISIONING_REQUIRED.

interface_name=SCHEMA.PACKAGE

Required for create or modify operations. The database schema name for the PLSQL package. The format of the value is schema.package_name, for example here is the schema and PLSQL package information for Portal:

interface_name=PORTAL.WWSEC_OID_SYNC

interface_version=1.1 | 2.0 | 3.0

The version of the interface protocol. Allowed values are 1.1, 2.0, or 3.0. The default value is 2.0.

interface_type=PLSQL | JAVA

Optional. The type of interface to which events will be propagated. The default is PLSQL.

interface_connect_info=connection_string

Required for create or modify operations. To connect to an Oracle database and propagate events, use one of the following formats for the connection string:

  • DBURL=ldap://ldaphost:ldapport/service:username:password (recommended)

  • host:port:sid:username:password

  • DBSVC=service:username:password

schedule=number_seconds

Optional for create and modify operations only. The number of seconds between executions of this profile. The default is 3600, which means the profile is scheduled to be executed every hour.

lastchangenumber=number

Optional for create and modify operations on OUTBOUND events only. The last change number in Oracle Internet Directory after which all qualifying events should be provisioned to the application. Defaults to the latest current change number.

max_prov_failure_limit=number

Optional. Determines the number of times the Oracle Provisioning System attempts to provision a user. The default is 1.

max_events_per_schedule=number

Optional for create and modify operations only. The maximum number of events that the Oracle directory integration and provisioning server sends to an application during one execution of a provisioning profile. The default is 100.

max_events_per_invocation=number

Optional for create and modify operations only. The maximum number of events that can be packaged and sent to a target in one invocation of the interface.

event_mapping_rules="OBJECT_TYPE:FILTER:DOMAIN"

Required for create and modify operations on INBOUND events only. This rule maps the object type received from the application (using an optional filter condition) to a domain in Oracle Internet Directory A provisioning profile can have multiple mapping rules defined.

The following example shows two mapping rules. The first rule shows that an employee object (EMP) whose locality attribute equals America (l=AMERICA) should be mapped to the domain l=AMER,cn=users,dc=company,dc=com. The second rule shows that an employee object (EMP) should be mapped to the domain cn=users,dc=company,dc=com (no filter conditions).

event_mapping_rules="EMP:l=AMERICA:l=AMER,cn=users,dc=company,dc=com"
event_mapping_rules="EMP::cn=users,dc=company,dc=com"

event_permitted_operations="OBJECT:DOMAIN:OPERATION(attributes,...)

Required for create and modify operations on INBOUND events only. This property is used to define the types of events that the application is allowed to send to the Oracle Directory Integration and Provisioning service. A provisioning profile can have multiple permitted operations defined.

For example, if you wanted to permit the application to send events whenever a user object was added or deleted, or when certain attributes were modified, you would have three permitted operations such as this:

event_permitted_operations="USER:dc=mycompany,dc=com:ADD(*)"
event_permitted_operations="USER:dc=mycompany,dc=com:MODIFY(cn,sn,mail,password)"
event_permitted_operations="USER:dc=mycompany,dc=com:DELETE(*)"

event_subscription="USER | GROUP:DOMAIN:OPERATION(attributes,...)"

Required for create and modify operations on OUTBOUND events only. This property is used to define the types of events that the Oracle Directory Integration and Provisioning service should send to the application. A provisioning profile can have multiple event subscriptions defined.

For example, if you wanted the directory integration server to send events to the application whenever a user or group object was added or deleted, you would have four event subscriptions such as this:

event_subscription="GROUP:dc=mycompany,dc=com:ADD(*)"
event_subscription="GROUP:dc=mycompany,dc=com:DELETE(*)"
event_subscription="USER:dc=mycompany,dc=com:ADD(*)"
event_subscription="USER:dc=mycompany,dc=com:DELETE(*)" 

max_events_per_schedule=number

Optional for create and modify operations only. The maximum number of events to be provisioned in one schedule. The default is 100.

max_retries=number

Optional for create and modify operations only. The number of times a failed event should be retried. The default is 5.

profile_group=number

Required for create and modify operations only. The group number of the profile. Default is "DEFAULT". This is required to address scalability issues when different Oracle Directory Integration and Provisioning server instances will be used to execute different selected groups.

profile_status=ENABLED | DISABLED

Required for the create operation only. Determines whether the profile is enabled or disabled. The default is ENABLED.

profile_debug=debug_level

Required. The debug level for the profile.

6.3.3 Tasks and Examples for oidprovtool

Using the Provisioning Registration Tool (oidprovtool) you can perform the following tasks:

6.3.3.1 Creating a Provisioning Profile

The following example creates a new provisioning profile that makes Portal aware of updates to the user and group information that is maintained in Oracle Internet Directory.

Example:

oidprovtool operation=create ldap_host=myhost.mycompany.com ldap_port=389 \
ldap_user_dn="cn=orcladmin" ldap_user_password=welcome1 application_dn="orclApplicationCommonName=PORTAL,cn=Portal,cn=Products,cn=OracleContext" \
organization_dn="dc=us,dc=mycompany,dc=com" interface_name=PORTAL.WWSEC_OID_SYNC \
interface_type=PLSQL interface_connect_info=myhost:1521:iasdb:PORTAL:password \
schedule=360 event_subscription="USER:dc=us,dc=mycompany,dc=com:DELETE" \
event_subscription="GROUP:dc=us,dc=mycompany,dc=com:DELETE" \
event_subscription="USER:dc=us,dc=mycompany,dc=com:MODIFY(orclDefaultProfileGroup,userpassword)" \
event_subscription="GROUP:dc=us,dc=mycompany,dc=com:MODIFY(uniqueMember)" \
profile_mode=OUTBOUND 

6.3.3.2 Modifying a Provisioning Profile

The following example modifies an existing provisioning profile for the Portal application. It changes the event subscription for the attributes that are provisioned when a user entry is modified.

Example:

oidprovtool operation=modify ldap_host=myhost.mycompany.com ldap_port=389 \
ldap_user_dn="cn=orcladmin" ldap_user_password=welcome1 application_dn="orclApplicationCommonName=PORTAL,cn=Portal,cn=Products,cn=OracleContext" \
organization_dn="dc=us,dc=mycompany,dc=com" \
subscription="USER:dc=us,dc=mycompany,dc=com:MODIFY(orclDefaultProfileGroup,userpassword,mail,cn,sn)"

6.3.3.3 Deleting a Provisioning Profile

The following example disables a provisioning profile for the Portal application.

Example:

oidprovtool operation=delete ldap_host=myhost.mycompany.com ldap_port=389 \
ldap_user_dn="cn=orcladmin" ldap_user_password=welcome1 application_dn="orclApplicationCommonName=PORTAL,cn=Portal,cn=Products,cn=OracleContext" \
organization_dn="dc=us,dc=mycompany,dc=com"

6.3.3.4 Disabling a Provisioning Profile

The following example disables a provisioning profile for the Portal application.

Example:

oidprovtool operation=disable ldap_host=myhost.mycompany.com ldap_port=389 \
ldap_user_dn="cn=orcladmin" ldap_user_password=welcome1 application_dn="orclApplicationCommonName=PORTAL,cn=Portal,cn=Products,cn=OracleContext" \
organization_dn="dc=us,dc=mycompany,dc=com"

6.3.4 Related Command-Line Tools for oidprovtool