2.2 oidca

During installation, the Oracle Internet Directory Configuration Assistant (oidca) configures Oracle Internet Directory. Once an installation has been completed, you can use it to:

Create, upgrade, or delete an Oracle Context.
Convert an Oracle Context to an Oracle Identity Management realm.
Configure the ldap.ora file that is used to discover the directory server in the environment.

Use the Oracle Internet Directory Configuration Assistant with Enterprise User Security and Oracle Net Services under the following conditions:

Table 2-1 Conditions for Using Oracle Internet Directory Configuration Assistant for Specific Database Components

Component Conditions

Component	Conditions
Enterprise User Security	Enterprise User Security works only with Oracle Identity Management realms created in the 9.0.4 or later release of Oracle Internet Directory. If you have Oracle Contexts created in prior releases, then you must use the Oracle Internet Directory Configuration Assistant to convert them to Oracle Identity Management realms. Use Oracle Internet Directory Configuration Assistant when creating or updating the `ldap.ora` configuration file. That file is used to discover the directory server in the environment.
Oracle Net Services	Use Oracle Internet Directory Configuration Assistant when: Creating, upgrading and deleting Oracle Contexts Converting an Oracle Context from an earlier release to an Identity Management Realm Setting up the `ldap.ora` configuration file. That file is used to discover the directory server in the environment.

Enterprise User Security

Enterprise User Security works only with Oracle Identity Management realms created in the 9.0.4 or later release of Oracle Internet Directory. If you have Oracle Contexts created in prior releases, then you must use the Oracle Internet Directory Configuration Assistant to convert them to Oracle Identity Management realms.

Use Oracle Internet Directory Configuration Assistant when creating or updating the ldap.ora configuration file. That file is used to discover the directory server in the environment.

Oracle Net Services

Use Oracle Internet Directory Configuration Assistant when:

Creating, upgrading and deleting Oracle Contexts
Converting an Oracle Context from an earlier release to an Identity Management Realm
Setting up the ldap.ora configuration file. That file is used to discover the directory server in the environment.

2.2.1 Syntax for oidca

oidca oidhost=hostname {nonsslport=port_number | sslport=port_number}  dn=binddn pwd=bindpwd {{mode=CREATECTX | UPGRADECTX | DELETECTX | CTXTOIMR contextdn=oraclecontextdn} | {mode=LDAPORA adminctx=admincontextdn dirtype=OID | AD [-update]}} | {propfile=filename}

2.2.2 Arguments for oidca

oidhost=hostname

Required. The host name of the Oracle Internet Directory server. If not specified, then the default of localhost is used.

nonsslport=port_number | sslport=port_number

Required. The port number used to connect to the Oracle Internet Directory server.

To connect to the directory in non-SSL mode, supply the unsecure LDAP port with the nonsslport argument (the default is 389).

To connect to the directory in SSL mode, supply the secure LDAP port with the sslport argument (the default is 636).

dn=binddn

Required. The DN of the Oracle Internet Directory user needed to bind to the directory (for example, cn=orcladmin).

pwd=bindpw

Required. The user password needed to bind to the directory.

mode=CREATECTX | UPGRADECTX | DELETECTX | CTXTOIMR | LDAPORA

Required. Specifies the operation to perform. The choices are:

CREATECTX creates a new Oracle Context under the given DN.
UPGRADECTX upgrades the Oracle Context in the given DN. You cannot upgrade Oracle Context instances that belong to a realm.
DELETECTX deletes an Oracle Context from the given DN.
CTXTOIMR converts an Oracle Context to an Oracle Identity Management realm.
LDAPORA configures the ldap.ora file that is used to discover the Oracle Internet Directory server in the environment.

contextdn=oraclecontextdn

Required when the mode argument equals CREATECTX, UPGRADECTX, DELETECTX, or CTXTOIMR. Specifies the DN under which the Oracle Context will be created, upgraded, deleted, or converted to an Oracle Identity Management realm.

adminctx=admincontextdn

Required when the mode argument equals LDAPORA. The default administrative context DN. For example, dn=company, dc=com.

dirtype=OID | AD

Required when the mode argument equals LDAPORA. The type of directory.

-update

Optional flag used when the mode argument equals LDAPORA. Use -update to overwrite an existing ldap.ora file. If not given, a new ldap.ora file will be created. If the ldap.ora file exists and the -update argument is not specified, then the Assistant exits with the message "ldap.ora exists".

propfile=filename

Instead of specifying the mode argument and its associated contextdn, adminctx, and dirtype arguments on the command-line, you can specify them in a properties file instead. Specify the full path and file name of the file containing these arguments.

2.2.3 Tasks and Examples for oidca

Using the Oracle Internet Directory Configuration Assistant command-line tool, you can perform the following tasks:

Creating an Oracle Context
Upgrading an Oracle Context
Deleting an Oracle Context
Converting an Oracle Context to an Oracle Identity Management Realm
Configuring the ldap.ora File

2.2.3.1 Creating an Oracle Context

The following example shows how to create a new Oracle Context under the given context DN:

Example:

oidca oidhost=host.company.com nonsslport=389 dn=cn=orcladmin pwd=password mode=CREATECTX contextdn=dc=company,dc=com

The context DN must exist in the directory and have the format of dc=your_company,dc=com. A DN with the format of cn=oraclecontext,dc=your_company,dc=com must not exist in the directory.

When creating an Oracle Context, Oracle Internet Directory Configuration Assistant does the following:

It verifies that the contextdn has valid DN syntax.
Verifies if OracleContext exists. If OracleContext does not exist, then Oracle Internet Directory Configuration Assistant creates it under the given context DN.

2.2.3.2 Upgrading an Oracle Context

The following example shows how to upgrade an existing Oracle Context under the given context DN:

Example:

oidca oidhost=host.company.com nonsslport=389 dn=cn=orcladmin pwd=password mode=UPGRADECTX contextdn=cn=oraclecontext,dc=company,dc=com

The context DN must exist in the directory, and can have either the format of dc=your_company,dc=com or the format of cn=oraclecontext,dc=your_company,dc=com. The given context DN must contain an OracleContext. The OracleContext cannot belong to a realm.

When upgrading an Oracle Context, Oracle Internet Directory Configuration Assistant does the following:

It verifies that the context DN has a valid DN syntax and that OracleContext exists in Oracle Internet Directory. The Assistant cannot upgrade a root OracleContext explicitly. If there is no root OracleContext, then the Assistant sends an error message.
It verifies if the OracleContext already belongs to an Oracle Identity Management realm. You cannot upgrade OracleContext instances that belong to a realm.

If OracleContext belongs to a realm, then Oracle Internet Directory Configuration Assistant exits with the appropriate message.
It verifies if the OracleContext is up-to-date.

If the OracleContext is up-to-date, then the Assistant exits with the message "Oracle Context already exists and is up to date."

If the OracleContext is not up-to-date, then the Assistant upgrades the OracleContext under this DN.

2.2.3.3 Deleting an Oracle Context

The following example shows how to delete an existing Oracle Context under the given context DN:

Example:

oidca oidhost=host.company.com nonsslport=389 dn=cn=orcladmin pwd=password mode=DELETECTX contextdn=cn=oraclecontext,dc=company,dc=com

When deleting an Oracle Context, Oracle Internet Directory Configuration Assistant does the following:

It verifies that the context DN has a valid DN syntax and that OracleContext exists in Oracle Internet Directory.
It verifies if the OracleContext already belongs to an Oracle Identity Management realm. You cannot delete OracleContext instances that belong to a realm.

If OracleContext belongs to a realm, then Oracle Internet Directory Configuration Assistant exits with the appropriate message.
If the OracleContext does not belong to a realm, then Oracle Internet Directory Configuration Assistant deletes it.

2.2.3.4 Converting an Oracle Context to an Oracle Identity Management Realm

Oracle Database 10g entries must be stored in Oracle Internet Directory Release 9.0.4 or later. Moreover, Enterprise User Security, a feature of Oracle Database 10g, requires a Release 9.0.4 or later version of an Oracle Identity Management realm.

The following example shows how to convert an existing Oracle Context to an Oracle Identity Management realm:

Example:

oidca oidhost=host.company.com nonsslport=389 dn=cn=orcladmin pwd=password mode=CTXTOIMR contextdn=cn=oraclecontext,dc=company,dc=com

When converting an Oracle Context to an Oracle Identity Management realm, Oracle Internet Directory Configuration Assistant does the following:

It verifies that the context DN has a valid DN syntax and that OracleContext exists in Oracle Internet Directory.
It verifies if the OracleContext already belongs to an Oracle Identity Management realm. You cannot convert OracleContext instances that already belong to a realm.
If the OracleContext does not belong to a realm, then the Assistant converts the OracleContext to an Oracle Identity Management realm.

Note:

If the nickname attribute is not cn, then configure it as a user configuration attribute by using the Oracle Internet Directory Self-Service Console. See instructions in the Oracle Identity Management Guide to Delegated Administration
To use the Oracle Internet Directory Self-Service Console to manage user and groups in the converted realm, be sure to configure the appropriate administrative privileges. For details, see the Oracle Internet Directory Administrator's Guide.

2.2.3.5 Configuring the ldap.ora File

The following example shows how to configure anldap.ora file by overwriting the existing ldap.ora file:

Example:

oidca oidhost=host.company.com nonsslport=389 dn=cn=orcladmin pwd=password mode=LDAPORA admincontext=dc=company,dc=com dirtype=OID -update

When configuring the ldap.ora file, Oracle Internet Directory Configuration Assistant does the following:

Checks for the ldap.ora file location.
If ldap.ora exists and the -update flag is not specified, then the Assistant exits with the message "ldap.ora exists".
If ldap.ora exists and the -update flag is specified, then the Assistant updates the existing ldap.ora file.
If ldap.ora does not exist, then the assistant creates a new ldap.ora file in a location in the following order:

LDAP_ADMIN

$ORACLE_HOME/ldap/admin

2.2.4 Related Command-Line Tools for oidca

N/A