This chapter explains how to create and configure Oracle Virtual Directory adapters and includes the following sections:
The following table lists the available Oracle Virtual Directory adapter templates and which plug-ins are deployed by these templates.
Note:
This table is intended as a quick reference only.
Be sure to read Section 2.9, "Understanding Adapter Templates" for detailed information about these adapter templates and plug-ins.
| Adapter Template Type | Adapter Template | Plug-In Deployed by Adapter Template |
|---|---|---|
|
Default Adapter |
Default Template |
|
|
LDAP Adapters |
Active_Directory |
|
|
CA_eTrust |
||
|
Changelog_LDAP-TYPE |
Changelog plug-in |
|
|
EUS_ActiveDirectory |
|
|
|
EUS_OID |
EUSOID plug-in |
|
|
EUS_Sun |
|
|
|
EUS_eDirectory |
|
|
|
General_LDAP_Directory |
||
|
IBM_Directory |
||
|
Novell_eDirectory |
||
|
OAM/AD Adapter with Mapper |
|
|
|
OAM/AD Adapter with SSL, Mapper |
Adapter is hidden to clients by default. It is accessible only through plug-ins like the Active Directory Password plug-in. |
|
|
OAM/AD Adapter with Script |
|
|
|
OAM/ADAM Adapter with Mapper |
|
|
|
OAM/ADAM Adapter with SSL, Mapper |
Adapter is hidden to clients by default. It is accessible only through plug-ins like the Active Directory Password plug-in. |
|
|
OAM/ADAM Adapter with Script |
|
|
|
OAM/SunOne Adapter with Mapper |
|
|
|
OAM/SunOne Adapter with Script |
Dump Transactions plug-in |
|
|
ONames_LDAP-TYPE |
ONames plug-in |
|
|
Oracle_Internet_Directory |
||
|
Siemens_DirX |
||
|
SunOne_Directory |
||
|
User_LDAP-TYPE |
UserManagement plug-in |
|
|
Local Store Adapter |
Local_Storage_Adapter |
|
|
Database Adapter |
OAM/DB Adapter with Script |
|
This section explains how to create and configure LDAP Adapters and includes the following sections:
Perform the following steps to create LDAP Adapters using Oracle Directory Services Manager:
Log in to Oracle Directory Services Manager.
Select Adapter from the task selection bar. The Adapter navigation tree appears.
Click the Create Adapter button. The New Adapter Wizard appears.
Perform the following steps to define the Type of adapter:
Select LDAP from the Adapter Type list.
Enter a unique name for the LDAP Adapter in the Adapter Name field. The adapter name value is used in other configuration fields that must reference the adapter.
Select an adapter template from the Adapter Template list by referring to Section 2.9, "Understanding Adapter Templates." Use the Default template if you are unsure which template to use.
Note:
After selecting an adapter template, Oracle Directory Services Manager populates default values for some adapter settings. You should alter these default settings according to your environment.
Click Next. The Connection screen appears.
Select a DNS mode of operation from the Use DNS for Auto Discovery options to configure Oracle Virtual Directory to use DNS to automatically discover the appropriate LDAP hosts for the remote base defined (instead of configuring specific LDAP hosts in the Connection Details table). This is also referred to as serverless bind mode. The LDAP Adapter supports the following DNS modes of operation:
Note:
The DNS options are listed in the Oracle Directory Services Manager interface in English only, however the description for each DNS option is supported in localized language translations.
No: Use the Connection Details table configuration—no serverless bind.
Standard: Use standard DNS lookup for a non-Microsoft server. All servers are marked as read/write, so enabling the Follow Referrals setting is advised to allow for LDAP write support.
Microsoft: The DNS server is a Microsoft dynamic DNS and also supports load-balancing configuration. If proxying to a Microsoft dynamic DNS server, this is the recommended setting because of Oracle Virtual Directory's ability to auto-detect read/write servers compared to read-only servers.
Note:
Remote base should have a domain component style name when using this setting, for example, dc=myorg,dc=com. This name enables Oracle Virtual Directory to locate the LDAP hosts within the DNS service by looking up myorg.com.
If you selected the No option for the Use DNS for Auto Discovery setting, add the proxy LDAP host information in the Connection Details table by clicking the Add Host button and then entering the following information. Each proxy LDAP host must provide equivalent content, that is, must be replicas.
Note:
Be careful when specifying only a single host for proxying. Without a failover host, the LDAP Adapter cannot automatically fail over to another host. A single host is suitable when Oracle Virtual Directory is connected to a logical LDAP service through a load balancing system.
Enter the IP Address or DNS name of the LDAP host to proxy to in the Hosts field.
Note:
Oracle Virtual Directory 11g Release 1 (11.1.1) supports IPv6. If your network supports IPv6 you can use a literal IPv6 address in the Hosts field to identify the proxied LDAP host.
Enter the port number the proxied LDAP host provides LDAP services on in the Port field.
Enter a number between 0 and 100 in the Weight Value field to configure the load percentage to send to the host. If the combined percentages for all of the hosts configured for the adapter do not total 100, Oracle Virtual Directory automatically adjusts the load percentages by dividing the percentage you entered for a host by the total percentage of all hosts configured for the adapter. For example, if you have three hosts configured for the adapter at 20 percent, 30 percent, and 40 percent, Oracle Virtual Directory adjusts the 20 to 22 (20/90), the 30 to 33 (30/90), and the 40 to 44 (40/90).
Select the Read-only option to configure the LDAP Adapter to only perform search operations on the LDAP host. The LDAP Adapter automatically directs all modify traffic to read/write hosts in the list.
Select the Use SSL/TLS option to secure the communication between the LDAP Adapter and the proxy LDAP hosts using SSL/TLS.
See:
Section 12.1.1.4, "Managing Certificate Authorities for LDAP Adapters Secured by SSL" for information on Certificate Authorities.
If you select (enable) the Use SSL/TLS option, choose the SSL authentication mode to use for securing the adapter by selecting an option from the SSL Authentication Mode list. The SSL Authentication Mode setting is functional only when the Use SSL/TLS option is enabled.
Enter the default distinguished name for the LDAP Adapter to bind with when accessing the proxied directory in the Server proxy Bind DN field. Depending on the setting in the Pass Through Credentials field, this DN is used for all operations, or only for exceptional cases such as pass-through mode. The form of the distinguished name must be in the form of the remote directory. The LDAP Adapter binds as Anonymous if the Server proxy Bind DN field is empty.
Enter the authentication password in clear text in the Proxy Password field to use with Server proxy Bind DN value. When loaded on the server, the value is automatically encrypted.
Click Next. Oracle Virtual Directory attempts to validate the connection(s) to the host(s) you defined in the Connection Details table. The Test Connection screen appears displaying the results of the connection validation process.
Upon successful validations, a success message and the details for the connection appear. Click Next. The Name Space screen appears. Continue creating the New LDAP Adapter by advancing to step 11.
Upon failed validations, a Could not connect message appears in the Connection column in the status table for the host connections that could not be validated. Click in the row for the host connection that could not be validated to see more information about why the connection failed. Resolve the failed connections by clicking the Back button, reviewing the settings for the host where the connection failed, and then editing the host settings as needed.
The connection to the proxy LDAP host must be validated for the adapter to proxy the LDAP host. Click Next on the Test Connection screen of the New LDAP Adapter Wizard after resolving the failed connection. The Name Space screen appears. Continue creating the New LDAP Adapter by advancing to step 11.
Enter the location in the remote server directory tree structure to which the local Oracle Virtual Directory root suffix corresponds in the Remote Base field. This is the location in the remote directory under which Oracle Virtual Directory executes all searches and operations for the adapter. The LDAP Adapter applies an automatic mapping of all entries from the remote base to the adapter root base.
Enter the namespace you want Oracle Virtual Directory clients to see for the proxied directory's namespace in the Mapped Namespace field. For example, if the DN in the proxied directory is dc=oracle, dc=com and you want Oracle Virtual Directory clients to see the namespace as dc=Oracle Corp, dc=com, you would enter dc=Oracle Corp, dc=com in the Mapped Namespace field.
Set the pass-through credentials for the LDAP Adapter by selecting an option from the Pass Through Credentials list:
Note:
The pass-through options are listed in the Oracle Directory Services Manager interface in English only, however the description for each pass-through option is supported in localized language translations.
Select Never to use the Proxy DN credentials for all operations.
Select BindOnly to pass user credentials to the proxied LDAP server for bind only and use the default server credentials for all other operations.
Select Always to pass user credentials presented to Oracle Virtual Directory to the proxied LDAP server for all operations.
Note:
In some situations when pass-through mode is set to Always, the LDAP Adapter may still use the Proxy DN. This occurs when the user credential cannot be mapped, for example, from another adapter namespace, or if it is the root account.
If defining multiple adapters to different domain controllers within a Microsoft Active Directory forest, you can program the LDAP Adapter to proxy credentials from other adapters (that is, two or more adapters pointing to the same Active Directory forest) by using the Routing Bind-Include setting.
Select the Use Kerberos option to configure the LDAP Adapter to perform LDAP bind operations using the Kerberos protocol. Oracle recommends using Java 1.6 or higher if you enable the Use Kerberos setting to resolve many known issues with the Microsoft Active Directory version of Kerberos.
If you enable the Use Kerberos option:
The Pass Through option must be set to BindOnly because the Kerberos authentication can only be used to validate credentials and not passed to the back-end server for any other operation.
The RDN value must be the same as the Kerberos principal name, for example, sAMAccountName in Active Directory. This may mean that the bind DN for a Kerberos bind is not the actual user DN. For example, if the user DN is cn=Jane Doe,cn=users,dc=mycompany,dc=com but the sAMAccountName is jdoe, the bind DN with the Use Kerberos option enabled is cn=jdoe,cn=users,dc=mycompany,dc=com.
You must create a krb5.conf file and place it in the Oracle Virtual Directory's configuration folder. The krb5.conf has the following properties:
Table 12-2 Properties in the krb5.conf File
| Property | Description |
|---|---|
|
default_realm |
The default domain used if not supplied by the mapping. For example, if a user binds as |
|
domain_realm |
Defines a mapping between a domain and a realm definition. For example: |
|
realms |
Defines one or more realms, for example: |
|
kdc |
The DNS name of the server running the Kerberos service for a particular realm definition. |
Kerberos binds use the Kerberos libraries provided in the standard Java package. The Kerberos libraries use the krb5.conf file, which is not currently synchronized with Oracle Virtual Directory LDAP Adapter settings. The default libraries control Kerberos fail-over. Refer to Sun Microsystem's Java documentation for more information on fail-over and advanced krb5.conf file configurations.
Note:
If a Microsoft Active Directory server is in the process of shutting down (either stopping or rebooting) and Oracle Virtual Directory tries to connect to it, Active Directory may not validate the credential and may return a Client not Found in Kerberos Database error message instead of returning a Key Distribution Center (Domain Controller) connection error.
The end-user should attempt to login again and assuming that either the Active Directory server is available or Key Distribution Center fail-over is enabled, successful authentication should be returned.
If you enable the Use Kerberos option, you can use the Kerberos Retry option to control whether Oracle Virtual Directory should retry logging in after failed authentication attempts. If you enable the Kerberos Retry option and authentication fails, Oracle Virtual Directory reloads the kerb5.conf file and retries the log in.
Note:
If you identified multiple Active Directory servers in a single Kerberos realm in the krb5.conf file, do not enable the Kerberos Retry option, as enabling the retry may disrupt fail-over functionality.
Click Next on the Name Space screen. The Summary screen appears listing the settings for the new LDAP Adapter.
Review the settings for the new LDAP Adapter and click Finish to create the LDAP Adapter. The new LDAP Adapter appears in the Adapter tree.
After you create the LDAP Adapter you can configure it using the procedures in Section 12.1.1, "Configuring LDAP Adapters."
This section describes how to configure LDAP Adapter settings, including:
After you create the LDAP Adapter you can configure the general settings for the adapter by clicking the adapter name in the Adapter tree, clicking the General tab, setting values for the following fields, and clicking Apply:
This field defines the root DN that the adapter provides information for. The DN defined, and the child entries below it, comprise the adapter's namespace. The value you enter in this field should be the base DN value for the returned entries. For example, if you enter dc=mydomain,dc=com in the field, all entries end with dc=mydomain,dc=com.
You can configure an adapter as active (enabled) or inactive (disabled). An adapter configured as inactive does not start during a server restart or an attempted adapter start. Use the inactive setting to keep old configurations available or in stand-by without having to delete them from the configuration. The default setting is active (enabled).
Perform the following procedures to configure the proxy LDAP host information in the LDAP Servers table in the General tab. Each proxy LDAP host must provide equivalent content, that is, must be replicas.
Be careful when specifying only a single host for proxying. Without a failover host, the LDAP Adapter cannot automatically fail over to another host. A single host is suitable when Oracle Virtual Directory is connected to a logical LDAP service by using a load balancing system.
Note:
The information in the LDAP Servers table is used only if you set the Use DNS for Auto Discovery parameter to No.
To add a proxy LDAP host to the adapter:
Click the Add Host button.
Enter the IP Address or DNS name of the LDAP host to proxy to in the Hosts field.
Note:
Oracle Virtual Directory 11g Release 1 (11.1.1) supports IPv6. If your network supports IPv6 you can use a literal IPv6 address in the Hosts field to identify the proxied LDAP host.
Enter the port number the proxied LDAP host provides LDAP services on in the Port field.
Enter a number between 0 and 100 in the Percentage field to configure the load percentage to send to the host. If the combined percentages for all of the hosts configured for the adapter do not total 100, Oracle Virtual Directory automatically adjusts the load percentages by dividing the percentage you entered for a host by the total percentage of all hosts configured for the adapter. For example, if you have three hosts configured for the adapter at 20 percent, 30 percent, and 40 percent, Oracle Virtual Directory adjusts the 20 to 22 (20/90), the 30 to 33 (30/90), and the 40 to 44 (40/90).
Select the Read-only option to configure the LDAP Adapter to only perform search operations on the LDAP host. The LDAP Adapter automatically directs all modify traffic to read/write hosts in the list.
To delete a proxy LDAP host from the adapter:
Click anywhere in the row of the host you want to delete in the Remote Host table.
Click the Delete button. A confirmation dialog box appears.
Click Confirm to delete the proxy LDAP host from the adapter.
To validate a proxy LDAP host connection:
Click anywhere in the row of the Remote Host table for the host you want to validate the connection for.
Click the Validate button. The connection to the proxy LDAP host must be validated for the adapter to proxy the LDAP host.
Enabling this option secures the communication between the LDAP Adapter and the proxy LDAP hosts using SSL/TLS.
See:
Section 12.1.1.4, "Managing Certificate Authorities for LDAP Adapters Secured by SSL" for information on Certificate Authorities.
If you select (enable) the Use SSL/TLS option, choose the SSL authentication mode to use for securing the adapter by selecting an option from the SSL Authentication Mode list. The SSL Authentication Mode setting is functional only when the Use SSL/TLS option is enabled.
If set to Sequential, the first host specified in LDAP Servers table is used unless a failure occurs. If a failure occurs, the next host is tried. Sequential failover is often used for fail-over between geographies. In sequential failover, the LDAP Adapter attempts to use the designated host until it fails. At this point, it would fail-over to an equivalent host available in another data center or continent.
If set to Distributed, each new connection made is load balanced through the list defined by the LDAP Servers table. Distributed failover is most often used when proxying a set of LDAP hosts that are typically in the same data center or are equally available in terms of network performance.
Note:
If a remote host's network fails, a delay of several minutes may occur in Oracle Virtual Directory because of platform specific TCP socket timeout settings. However, Oracle Virtual Directory failover is operating properly and no data is lost during the delay.
Enable this option to force the Oracle Virtual Directory server to continue trying to connect to the last host listed in the LDAP Servers table for new incoming requests on the adapter even after it has been determined that the connection to the host failed. When enabled, the adapter's Heartbeat Interval setting is ignored regardless if a connection to the host has failed and the host will not be removed from the LDAP Servers table. Some environments with distributed directories may prefer to disable the Extended Trying option with the Routing Critical setting to quickly return partial results at that time. The default setting is enabled.
The LDAP Adapter periodically verifies the availability of each the hosts defined in the LDAP Servers table. Any currently disabled host can be resurrected or a currently active host that fails the TCP/IP connection test is labeled as false during this verification cycle. The Heartbeat Interval parameter specifies the number of seconds between verification passes. Setting a value too low can cause unnecessary connections to the remote directory. Setting a value too high can mean extended time for recovery detection when you have a failure. For production environments, Oracle suggests starting with a value of 60 seconds, then making adjustments as needed.
Note:
Setting the Heartbeat Interval parameter to "0" will disable the Heartbeat thread; however, Oracle recommends that you always have the heartbeat thread enabled.
The amount of time in milliseconds the server waits for an LDAP request to be acknowledged by a remote host. If the operation fails, the LDAP Adapter automatically tries the next server in the Remote Host table. The minimum configurable value is 15000 (ms). For production environments, Oracle suggests starting with a value of 15000, which is 15 seconds, then making adjustments as needed.
A tuning parameter that enables you to control how many simultaneous connections can be made to a single server. For production environments, Oracle suggests starting with a value of 10 connections, then making adjustments as needed.
The maximum amount a time in milliseconds that an LDAP operation waits to use an existing connection before causing the LDAP Adapter to generate a new connection. For production environments, Oracle suggests starting with a value of 1000, which is 1 second, then making adjustments as needed.
Maximum number of times an operation waits for an LDAP connection before overriding the Max Pool Connections parameter to generate a new connection. Maximum time is a function of multiplying Max Pool Wait time by the number of tries. If pool wait is 1 second, and 10 is the maximum number of tries, then if after 10 seconds an LDAP connection is not available in the normal pool, the pool will be expanded to handle the extended load. To prevent pool expansion beyond Max Pool Connections, set the number of tries to a high number. For production environments, Oracle suggests starting with a value of 10, then making adjustments as needed.
Refer to step 14 for information about the Use Kerberos option.
If you enable the Use Kerberos option, you can use the Kerberos Retry option to control whether Oracle Virtual Directory should retry logging in after failed authentication attempts. If you enable the Kerberos Retry option and authentication fails, Oracle Virtual Directory reloads the kerb5.conf file and retries the log in.
Note:
If you identified multiple Active Directory servers in a single Kerberos realm in the krb5.conf file, do not enable the Kerberos Retry option, as enabling the retry may disrupt fail-over functionality.
Instead of configuring specific proxy LDAP hosts in the LDAP Servers table, you can use this option to instruct Oracle Virtual Directory to use DNS to locate the appropriate LDAP servers for the remote base defined, also known as serverless bind mode. The LDAP Adapter supports the following modes of operation:
No: Use the LDAP Servers table configuration—no serverless bind
Standard: Use standard DNS lookup for a non-Microsoft server. All servers are marked as read/write, so enabling the Follow Referrals setting is advised to allow for LDAP write support.
Microsoft: The DNS server is a Microsoft dynamic DNS and also supports load-balancing configuration. If proxying to a Microsoft dynamic DNS server, this is preferred setting because of Oracle Virtual Directory's ability to auto-detect read/write servers compared to read-only servers.
Note:
Remote base should have a domain component style name when using this setting, for example, dc=myorg,dc=com. This name enables Oracle Virtual Directory to locate the LDAP hosts within the DNS service by looking up myorg.com.
The following fields appear in the Settings section of the General tab:
The location in the remote server directory tree structure to which the local Oracle Virtual Directory root suffix corresponds. This is the location in the remote directory under which Oracle Virtual Directory executes all searches and operations for the current adapter. The LDAP Adapter applies an automatic mapping of all entries from the remote base to the adapter root base.
List of attributes to be treated as DNs for which namespace translation is required, such as member, uniquemember, manager. For example, when reading a group entry from a proxied directory, Oracle Virtual Directory automatically converts the DN for the group entry itself and the uniquemember or member attributes if these attributes are in the DN Attributes list.
Note:
Translate only those attributes you know must be used by the client application. Entering all possible DN attributes may not be necessary and can consume some a small amount of additional CPU time in the proxy.
To add attributes to the DN Attributes list:
Click Add. The Select DN Attribute dialog box appears.
Select the attribute you want to add.
Click OK.
When a / character is encountered in a directory, Oracle Virtual Directory can optionally escape the slashes with back-slashes \ character. Some directory server products accept un-escaped slashes, while others reject them. Selecting this setting enables escaping of slashes.
Enabling this setting causes the LDAP Adapter to follow (chase) referrals received from a source directory on the client's behalf. If disabled, the referral is blocked and not returned to the client.
The following list summarizes the LDAP Adapter's behavior with different settings in relation to the send managed DSA control in LDAP operations setting:
If the LDAP Adapter's Follow Referrals is set to Enabled (true), and Send Managed DSA Control in LDAP Operations is also set to True, Oracle Virtual Directory does not chase the referral entries, but it returns them back to the client.
If the LDAP Adapter's Follow Referrals is set to Enabled (true), but Send Managed DSA Control in LDAP Operations is set to False, Oracle Virtual Directory chases the referral entries.
If the LDAP Adapter's Follow Referrals is set to Disabled (false), but Send Managed DSA Control in LDAP Operations is set to True, Oracle Virtual Directory does not chase the referral entries, but it returns them back to the client.
If the LDAP Adapter's Follow Referrals is set to Disabled (false), and Send Managed DSA Control in LDAP Operations is also set to False, Oracle Virtual Directory does not chase the referral entries and does not return them back to client.
If enabled, this setting allows the proxy to use the paged results control with a proxied directory. Enabling this setting is most often used when a directory limits the number of results in a query. This setting is used on behalf of and transparently to Oracle Virtual Directory's clients.
The following fields appear in the Credential Processing section of the General tab:
The default DN that the LDAP Adapter binds with when accessing the proxied directory. Depending on the Pass-through Mode setting, this DN is used for all operations, or only for exceptional cases such as pass-through mode. The form of the distinguished name should be in the form of the remote directory. Empty values are treated as Anonymous.
The authentication password to be used with the Proxy DN value. To set the password, enter a value in clear text. When loaded on the server, the value is automatically hashed with a reversible mask to provide additional security, for example, {OMASK}jN63CfzDP8XrnmauvsWs1g==.
To pass user credentials presented to Oracle Virtual Directory to the proxied LDAP server for all operations, set to Always. To pass user credentials to the proxied LDAP server for bind only and use the default server credentials for all other operations, set to Bind Only. To use the Proxy DN credentials for all operations, set to Never.
Note:
In some situations when pass-through mode is set to Always, the LDAP Adapter may still use the Proxy DN. This occurs when the user credential cannot be mapped, for example, from another adapter namespace, or is the root account.
If defining multiple adapters to different domain controllers within a Microsoft Active Directory forest, you can program the LDAP Adapter to proxy credentials from other adapters (that is, two or more adapters pointing to the same Active Directory forest) by using the Routing Bind-Include setting.
The following fields appear in the Ping Protocol Settings section of the General tab:
The Ping Protocol Settings provide options for how to determine when a source LDAP directory server that is not responding becomes available. If multiple source directory servers are configured, Oracle Virtual Directory identifies the non-responsive servers and performs subsequent operations against the next available server.
Select either TCP or LDAP as the protocol Oracle Virtual Directory should use to ping source directory servers. Select LDAP if the source directory server is using SSL.
Note:
While the TCP protocol option is faster than the LDAP option, it may produce an inaccurate response from the source directory server if its network socket is available, but its LDAP server process is unavailable.
If you select LDAP as the Ping Protocol, identify the DN to use for the LDAP bind.
If you select LDAP as the Ping Protocol, identify the password for the DN specified in the Ping Bind DN setting.
After you create the adapter you can configure routing for the adapter by clicking the adapter name in the Adapter tree, clicking the Routing tab, and referring to Section 3.2, "Understanding Routing Settings."
After you create the adapter you can apply Plug-ins and Mappings to the adapter by clicking the adapter name in the Adapter tree, clicking the Plug-Ins tab, and referring to Section 13.1, "Managing Adapter Plug-ins" and Section 14.3, "Applying Mappings to Adapters."
In some situations, SSL connections from Oracle Virtual Directory to the SSL port of an LDAP Adapter can fail and the following message may appear:
Oracle Virtual Directory could not load certificate chain
Two examples of situations when this may happen are when:
you create a new LDAP Adapter secured by SSL and use an untrusted Certificate Authority
a certificate for an existing LDAP Adapter secured by SSL expires and the new certificate is signed by an untrusted Certificate Authority
To resolve this issue, import the LDAP server certificate and the Root Certificate Authority certificate used to sign the LDAP server certificate, into the Oracle Virtual Directory server so it knows the certificates are trusted.
Use the following keytool command and an appropriate alias all on one command line:
ORACLE_HOME/jdk/jre/bin/keytool -import -trustcacerts -alias "NEW_CA" -file PATH_TO_CA_CERTIFICATE -keystore ORACLE_INSTANCE/config/OVD/ovd1/keystores/adapters.jks
Using LDAP Adapters with Microsoft Active Directory and Microsoft Certificate Services
By default, Microsoft Certificate Services automatically update expired Active Directory SSL certificates. However, client applications are not normally notified of this change. If this happens, the Oracle Virtual Directory LDAP Adapter connected to an updated Active Directory server stops functioning. If this occurs, use Oracle Directory Services Manager to configure the LDAP Adapter to import trusted certificates and the adapter should begin to function again.
Perform the following steps to configure a mutual authentication SSL connection between Oracle Virtual Directory and Oracle Internet Directory:
Create and configure an LDAP adapter for Oracle Internet Directory by referring to Section 12.1, "Creating LDAP Adapters" and Section 12.1.1, "Configuring LDAP Adapters." When you configure the adapter, set it to use a non-SSL port number.
If ORACLE_INSTANCE/config/OVD/ovd1/adapters.jks does not exist, create it with a self-signed certificate to store the trusted certificates by using the following command:
ORACLE_HOME/jdk/jre/bin/keytool -genkey \ -keystore ORACLE_INSTANCE/config/OVD/ovd1/keystores/adapters.jks \ -storepass password -alias alias -keyalg rsa -dname DN
Note:
The DN identified by the -dname option in the preceding command is the DN that Oracle Virtual Directory uses to act as a client to Oracle Internet Directory.
A user entry corresponding to this DN must exist (or must be created) on Oracle Internet Directory in order for SSL mutual authentication to work.
Export the Oracle Internet Directory server certificate in Base64 format using the following command:
orapki wallet export -wallet LOCATION_OF_OID_WALLET \ -dn DN_FOR_OID_SERVER_CERTIFICATE -cert ./b64certificate.txt
Note:
If you use a certificate alias in the orapki command and the alias is not in all lowercase letters, an error occurs.
Import the Oracle Internet Directory server certificate created in step 3 to the Oracle Virtual Directory keystore as a trusted entry using the following command:
ORACLE_HOME/jdk/jre/bin/keytool -importcert \ -keystore ORACLE_INSTANCE/config/OVD/ovd1/keystores/adapters.jks \ -storepass password -alias alias -file b64certificate.txt -noprompt
Export the Oracle Virtual Directory server certificate in Base 64 format, using the following command:
ORACLE_HOME/jdk/jre/bin/keytool -exportcert \ -keystore ORACLE_INSTANCE/config/OVD/ovd1/keystores/adapters.jks \ -storepass password -rfc -alias alias -file cert.txt
Import the Oracle Virtual Directory server certificate to the Oracle Internet Directory wallet as a trusted certificate. Execute the following command from the Oracle Internet Directory wallet directory:
orapki wallet add -wallet ./ewallet.p12 -cert cert.txt \ -trusted_cert -pwd password
Note:
If you use a certificate alias in the orapki command and the alias is not in all lowercase letters, an error occurs.
Using Oracle Directory Services Manager, update the LDAP Adapter for Oracle Internet Directory as follows:
Select (enable) the Use SSL/TLS option.
Change the port number to the SSL port number configured for Mutual Authentication in Oracle Internet Directory.
Select Server only Authentication/Mutual Authentication as the SSL Authentication Mode.
You can leave the Proxy DN and Proxy Password options blank.
Click the Apply button to save the changes to the adapter.
Restart the Oracle Virtual Directory server, verify the connection details, and test the adapter.
If the test is successful, the adapter status displays a Certificates Trusted message. For example,
opmnctl stopproc ias-component=ovd1 opmnctl startproc ias-component=ovd1
This section explains how to create and configure Database Adapters and includes the following sections:
Perform the following steps to create Database Adapters using Oracle Directory Services Manager:
Note:
Before you create a Database Adapter for a non-Oracle database for the first time, you must first load the database's drivers into Oracle Virtual Directory. Refer to Section 9.6.2, "Loading Libraries into the Oracle Virtual Directory Server" for information on loading drivers into the Oracle Virtual Directory server.
If you are creating an adapter for MS SQL 2005 or 2008, be sure you use the latest sqljbdc4.jar (SQL JDBC driver). Using an older driver can cause database display problems and prevent you from successfully creating the adapter.
Log in to Oracle Directory Services Manager.
Select Adapter from the task selection bar. The Adapter navigation tree appears.
Click the Create Adapter button. The New Adapter Wizard appears.
Perform the following steps to define the Type of adapter:
Select Database from the Adapter Type list.
Enter a unique name for the Database Adapter in the Adapter Name field. The adapter name value is used in other configuration fields that must reference the adapter.
Select Default from the Adapter template list unless you are integrating Oracle Virtual Directory with Oracle Access Manager. Refer to Section 2.9, "Understanding Adapter Templates" for more information.
Note:
After selecting an adapter template, Oracle Directory Services Manager populates default values for some adapter settings. You should alter these default settings according to your environment.
Click Next. The Connection screen appears.
Enter a valid base DN (in DN format) in the Adapter Suffix/Namespace field. This field defines the root DN that the adapter provides information for. The DN defined, and the child entries below it, comprise the adapter's namespace. The value you enter in this field should be the base DN value for returned entries. For example, if you enter dc=mydomain,dc=com in the field, all entries end with dc=mydomain,dc=com.
Select one option from the following URL Type list. Some steps to create a Database Adapter differ depending on which option you choose. After selecting an option, continue this procedure by following the alphabetic numbered steps for each option.
Use Predefined Database: Select this option to connect to a predefined database. The predefined databases appear in the Database Type list after selecting Use Predefined Database from the URL Type list. If you are unsure if Oracle Virtual Directory has predefined your type of database, select Use Predefined Database from the URL Type list and verify whether your database is listed in the Database Type list. If your database is listed in the Database Type list, continue with the following steps. If your database is not listed, select Use Custom URL from the URL Type list and perform the steps for using a custom URL.
Select the type of your of database from the Database Type list. After selecting the database type, the JDBC Driver Class and Database URL fields are populated with the appropriate information for the database.
Enter the IP Address or DNS host name of the database in the Host field.
Enter the port number the database listens on in the Port field.
Enter the name of the database, for example, the Oracle SID, in the Database Name field.
Enter the user name that the Database Adapter should use to connect the database in the Database User field.
Enter the password for the user name you entered in the Database User field in the Password field. Oracle Virtual Directory replaces the value you enter in this field with a reversible masked value upon startup.
Click Next. The Map Database Tables screen appears. Continue this procedure by going to step 7 now.
Use Custom URL: Select this option to connect Oracle Virtual Directory to a custom database.
In the JDBC Driver Class field, enter the JDBC driver class name for the database.
In the Database URL field, enter the URL that Oracle Virtual Directory should use to access the database.
In the Database User field, enter the user name that the Database Adapter should use to connect the database.
In the Password field, enter the password for the user name you entered in the Database User field. Oracle Virtual Directory replaces the value you enter in this field with a reversible masked value upon startup.
Click Next. The Map Database Tables screen appears. Continue this procedure by going to step 7 now.
Identify the database tables the Database Adapter should use in the Map Database Tables field by entering the name of the table file, or by clicking Browse, navigating to the table file, selecting it, and clicking OK. Click Next on the Map Database Tables screen to proceed. The Map Object Classes screen appears.
Note:
If you do not define an object class in step 8, the information you entered in the Map Database Tables field cannot be saved.
In the Map Object Classes field, define the object classes and their RDNs that map to the database tables. Click the Create Object Class button. The New Object Class Mapping dialog box appears allowing you to define the objectclass and their corresponding RDNs. Enter the following information:
Select the appropriate object class for the Object Class list.
Enter the RDN for the object class in the RDN field.
Click OK. The object class and the RDN appear in the Object Class table.
Note:
You can create nested object classes by entering an existing object where the RDN of the nested class must be an attribute of the child object class. For example, you could create parent organization units for records in a table about people where location information is available that you can use to drive the organization unit (ou) information.
Map LDAP attributes for the object class and RDNs to the database table and fields. You must map LDAP attributes for the object class RDN value. You do not have to map every LDAP attribute required by the LDAP schema for the selected object class.
Click the appropriate object class in the Object Class table and then click the Add Mapping Attribute button on the Attributes Mapping table. Enter the following information.
Select the LDAP attribute value for the object class from the LDAP Attribute list.
Select the appropriate database table and field from the Database Table:Field list.
Optionally, select a description for the attribute type from the Data Type list.
Note:
You must select BLOB from the Data Type list if you are mapping an attribute to a BLOB column in the database.
Click Next on the Map Object Class Mapping screen after defining all the object classes and attribute mappings. The Summary screen appears listing the settings for the Database Adapter.
Review the Database Adapter settings and click Finish to create the Database Adapter. The new Database Adapter appears in the Adapter tree.
When the adapter starts, Oracle Virtual Directory connects to the database and retrieves all defined LDAP attributes and their corresponding table and column information to reconcile the attributes with the defined LDAP schema. If a mapped LDAP attribute is already defined, it attempts to create a mapping from the database source format to the target LDAP schema format. If the LDAP attribute is not defined, the Database Adapter temporarily adds an attribute to the server schema that most closely maps to the database format (this definition is not added to the permanent Oracle Virtual Directory schema configuration).
After you create the Database Adapter, you can configure it using the procedures in Section 12.2.3, "Configuring Database Adapters."
To create a Database Adapter for use with Oracle RAC Database, perform the procedure in Section 12.2, "Creating Database Adapters," but when you configure the connection to the Oracle RAC database on the Connection screen:
Select Use Custom URL from the URL Type list.
In the Database URL field, enter the URL to connect to the Oracle RAC database, such as:
jdbc:oracle:oci:@(DESCRIPTION=(ADDRESS_LIST=(LOAD_ BALANCE=ON)(ADDRESS=(PROTOCOL=TCP)(HOST=host-name-1)(PORT=1521))(ADDRESS= (PROTOCOL=TCP)(HOST=host-name-2)(PORT=1521)))(CONNECT_ DATA=(SERVER=DEDICATED)(SERVICE_NAME=database-service-name)))
Note:
The Oracle Virtual Directory Database Adapter does not support Fast Connection Failover (FCF) for Oracle RAC. However, after a RAC instance failure, Oracle Virtual Directory reconnects to a surviving RAC instance.
Perform the following steps to create a Database Adapter for use with Oracle TimesTen In-Memory Database:
If native Oracle TimesTen libraries are not accessible to Oracle Virtual Directory, you must install the Oracle TimesTen In-Memory Database client.
In Oracle Virtual Directory's opmn.xml file, add the location of the Oracle TimesTen libraries and add the location of the Oracle TimesTen JDBC driver to the class-path. The opmn.xml file is located in the following directory:
ORACLE_INSTANCE/config/OPMN/opmn/
To set the location of the Oracle TimesTen libraries:
Add the LD_LIBRARY_PATH environment variable for UNIX and Linux platforms, or add the PATH environment variable on Windows.
For example, on UNIX and Linux platforms, you add the LD_LIBRARY_PATH environment variable as follows, where TIMESTEN_HOME represents the directory where you installed the Oracle TimesTen software:
Note:
On Windows platforms, the PATH environment variable you set in the opmn.xml file must include the Oracle TimesTen bin directory, such as, TIMESTEN_HOME/bin.
Example 12-1 Setting the Location of the Oracle TimesTen Libraries on UNIX/Linux
<ias-component id="ovd1">
<process-type id="OVD" module-id="OVD">
<environment>
<variable id="TNS_ADMIN" value="$ORACLE_INSTANCE/config"/>
<variable id="LD_LIBRARY_PATH" value="/TIMESTEN_HOME/lib" append="true"/>
</environment>
To add the location of the Oracle TimesTen JDBC driver to the class-path:
Set the java-classpath to include the path to the TimesTen JDBC Driver as follows, where TIMESTEN_HOME represents the directory where you installed the Oracle TimesTen software:
Example 12-2 Adding the Location of the Oracle TimesTen JDBC Driver to the class-path
<module-data>
<category id="start-options">
<data id="java-bin" value="$ORACLE_HOME/jdk/bin/java"/>
<data id="java-options" value="-server -Xms512m -Xmx512m
-Dvde.soTimeoutBackend=0 -Doracle.security.jps.config=$ORACLE_INSTANCE/config/JPS/jps-config-jse.xml"/>
<data id="java-classpath" value="$ORACLE_HOME/ovd/jlib/vde.jar$:$ORACLE_HOME/jdbc/lib/ojdbc6.jar:/TIMESTEN_HOME/lib/ttjdbc6.jar"/>
</category>
</module-data>
Reload the configuration to OPMN, and stop, then start Oracle Virtual Directory. For example:
To reload the configuration to OPMN, execute:
ORACLE_INSTANCE/bin/opmnctl reload
To stop Oracle Virtual Directory, execute:
ORACLE_INSTANCE/bin/opmnctl stopproc ias-component=NAME_OF_OVD_COMPONENT
To start Oracle Virtual Directory, execute:
ORACLE_INSTANCE/bin/opmnctl startproc ias-component=NAME_OF_OVD_COMPONENT
Create a Database Source Name (DSN) for Oracle TimesTen. Refer to the Oracle TimesTen Operations Guide on the Oracle Technology Network Web site for more information.
Create the Database Adapter for Oracle TimesTen using Oracle Directory Services Manager. When you create the Database Adapter for Oracle TimesTen:
If the adapter is for an Oracle TimesTen client-only installation:
Select the Use Custom URL option from the URL Type list on the Connection screen of the New Database Adapter Wizard.
Enter the following in the JDBC Driver Class field:
com.timesten.jdbc.TimesTenDriver
In the Database URL field, enter the following and replace DSN with the Database Source Name you created in step 4:
jdbc:timesten:client:dsn=DSN
Continue creating the adapter by referring to Section 12.2, "Creating Database Adapters."
If the adapter is for an Oracle TimesTen client and server installation:
Select the Use Predefined Database option from the URL Type list on the Connection screen of the New Database Adapter Wizard.
Choose Oracle - Times-Ten from the Database Type list.
Select the Use Custom URL option from the URL Type list.
In the Database URL field, enter the following and replace DSN with the Database Source Name you created in step 4:
jdbc:timesten:direct:dsn=DSN
Continue creating the adapter by referring to Section 12.2, "Creating Database Adapters."
Note:
You can use the Enable Case Insensitive Search option, as described in Section 12.2.3.1, "Configuring Database Adapter General Settings," to improve Database Adapter performance during searches on case-insensitive LDAP attributes, such as uid, for Oracle TimesTen databases.
In addition to enabling the Enable Case Insensitive Search option, the linguistic indexes for the database columns used in the search must be created in the database. Refer to the Oracle Database Globalization Support Guide for information about Oracle TimesTen database linguistic indexes.
This section describes how to configure Database Adapter settings, including:
After you create the Database Adapter, you can configure the general settings for the adapter by clicking the adapter name in the Adapter tree, clicking the General tab, setting values for the following fields, and clicking Apply:
This field defines the root DN that the adapter provides information for. The DN defined, and the child entries below it, comprise the adapter's namespace. The value you enter in this field should be the base DN value for returned entries. For example, if you enter dc=mydomain,dc=com in the field, all entries end with dc=mydomain,dc=com.
An adapter can be configured as active (enabled) or inactive (disabled). An adapter configured as inactive does not start during a server restart or an attempted adapter start. Use the inactive setting to keep old configurations available or in stand-by without having to delete them from the configuration. The default setting is active.
The following fields appear in the Connection Settings section of the General tab:
Select an option from the following URL Type list. Some fields for Database Adapter connection settings differ depending on which option you choose. After selecting an option, continue configuring the Connection Settings by setting the fields listed for each option.
Use Custom URL: Select this option to connect Oracle Virtual Directory a custom database.
Enter the JDBC driver class name for the database in the JDBC Driver Class field.
Enter the URL that Oracle Virtual Directory should use to access the database in the Database URL field.
Enter the user name that the Database Adapter should use to connect the database in the Database User field.
Enter the password for the user name you entered in the Database User field in the Password field. Oracle Virtual Directory replaces the value you enter in this field with a reversible masked value upon startup.
Use Predefined Database: Select this option to connect to a predefined database. The predefined databases appear in the Database Type list after selecting Use Predefined Database from the URL Type list. If you are unsure if Oracle Virtual Directory has predefined your type of database, select Use Predefined Database from the URL Type list and verify if your database is listed in the Database Type list. If your database is listed in the Database Type list, continue with the following steps. If your database is not listed, select Use Custom URL from the URL Type list and perform the steps for using a custom URL.
Select the type of your database from the Database Type list. After selecting the database type, the JDBC Driver Class and Database URL fields are populated with the appropriate information for the database.
Enter the IP Address or DNS host name of the database in the Host field.
Enter the port number the database listens on in the Port field.
Enter the name of the database, for example, the Oracle SID, in the Database Name field.
Enter the user name that the Database Adapter should use to connect the database in the Database User field.
Enter the password for the user name you entered in the Database User field in the Password field. Oracle Virtual Directory replaces the value you enter in this field with a reversible masked value upon startup.
The following fields appear in the Settings section of the General tab:
Since objectclasses in the database are logical objects and do not map directly to a table column in the mapping, modifications to the objectclass attribute can cause errors. If the Ignore Modify Objectclasses option is enabled, the Database Adapter removes any references to the objectclass attribute so that errors are not be sent to the client application, that is, they are ignored. If the Ignore Modify Objectclasses option is not selected, error messages are sent to the client application
This setting causes the Database Adapter to list objectclass parent classes along with the main objectclass in the objectclass attribute. Disable this setting when you want to emulate Microsoft Active Directory server schema. For most scenarios, it is useful to enable this setting so that objectclass=xxx queries can be executed against parent objectclass values.
Enabling (selecting) the Enable Case Insensitive Search option makes the search case insensitive for case insensitive LDAP attributes, such as uid. Oracle Virtual Directory uses UPPER in the SQL query when Enable Case Insensitive Search is enabled. If the database cannot maintain functional indexes, such as for Oracle TimesTen or MySQL databases, then you should disable the Enable Case Insensitive Search option. When the Enable Case Insensitive Search is disabled, Oracle Virtual Directory performs case sensitive searches and does not use UPPER in the SQL query. The default value for Enable Case Insensitive Search is Enable.
This setting defines the maximum connections the Database Adapter may make with the database.
This setting determines how much time (in seconds) the Database Adapter should wait before timing-out when trying to establish a connection with the database.
The following fields appear in the DB/LDAP Mapping section of the General tab:
This field displays the database tables the Database Adapter is set to use. To add a database table, click the Add button, navigate to the table file, select it and click OK.
The following fields appear in the Object Classes section of the General tab:
This field displays object classes and their RDNs that map to the database tables. To add an Object Class Mapping, click the Create button, select the appropriate object class from the Object Class list, enter an RDN value for the object class in the RDN field, and click OK.
After you create the adapter you can configure routing for the adapter by clicking the adapter name in the Adapter tree, clicking the Routing tab, and referring to Section 3.2, "Understanding Routing Settings."
After you create the adapter you can apply Plug-ins and Mappings to the adapter by clicking the adapter name in the Adapter tree, clicking the Plug-Ins tab, and referring to Section 13.1, "Managing Adapter Plug-ins" and Section 14.3, "Applying Mappings to Adapters."
This section explains how to create and configure Local Store Adapters and includes the following sections:
Perform the following steps to create Local Store Adapters using Oracle Directory Services Manager:
Log in to Oracle Directory Services Manager.
Select Adapter from the task selection bar. The Adapter navigation tree appears.
Click the Create Adapter button. The New Adapter Wizard appears.
Perform the following steps to define the Type of adapter:
Select Local Store from the Adapter Type list.
Enter a unique name for the Local Store Adapter in the Adapter Name field. The adapter name value is used in other configuration fields that must reference the adapter.
Select an adapter template from the Adapter Template list by referring to Section 2.9, "Understanding Adapter Templates.". Use the Default template if you are unsure which template to use.
Note:
After selecting an adapter template, Oracle Directory Services Manager populates default values for some adapter settings. You should alter these default settings according to your environment.
Click Next. The Settings screen appears.
Enter a valid base DN (in DN format) in the Adapter Suffix/Namespace field. This field defines the root DN that the adapter provides information for. The DN defined, and the child entries below it, comprise the adapter's namespace. The value you enter in this field should be the base DN value for returned entries. For example, if you enter dc=mydomain,dc=com in the field, all entries end with dc=mydomain,dc=com.
Select the Create Adapter Suffix option to create a base entry in the Local Store Adapter using the value specified in the Adapter Suffix/Namespace field.
Note:
If you enable the Create Adapter Suffix option, an Objectclass screen appears after you click Next on the Settings screen. When the Objectclass screen appears, select an Objectclass for the base entry in the Local Store Adapter.
Enter the path, relative to the Oracle Virtual Directory installation, and a unique file name prefix for the Local Store Adapter data files in the Database File field. For example, a valid name may be data/localDB. If you are using multiple Local Store Adapters, this value must be unique for each adapter or data-corruption occurs.
Enter the size for the Local Store Adapter cache in the Cache Size field. The Cache Size option determines the number of entries the Local Store Adapter will cache, which always contains the last entries accessed or written. The size of the entries determines how much memory you need.
Note:
Storing very large entries, for example, groups or binary objects, this may cause Oracle Virtual Directory to consume more memory than normal. You may have to increase the overall memory available to the Oracle Virtual Directory.
Select the password hash type by choosing an option from the Password Hash Mode list. The most secure algorithm is SSHA, however, others are available for compatibility purposes. Selecting PLAIN leaves the password valued un-hashed in the internal Local Store Adapter data store.
Enter the path, relative to the Oracle Virtual Directory installation, and a unique file name in the Backup File field in which automatic backups should be stored. For example, a valid backup file may be backup/localDB. The backup file name should be unique to the Local Store Adapter to prevent being over-written by another Local Store Adapter.
Enter the hour (0 to 23) in the Backup Time - Hour field to set the hour of the time at which the Local Store Adapter automatic backup should occur.
Enter the minute (0 to 59) in the Backup Time - Minute field to set the minute of the time at which the Local Store Adapter automatic backup should occur.
Enter the maximum number of backup files in the Max Backup Files field to keep in the backup file rotation for the Local Store Adapter.
Click Next. The Summary screen appears listing the settings for the Local Store Adapter.
Review the Local Store Adapter settings and click Finish to create the Local Store Adapter. The new Local Store Adapter appears in the Adapter tree.
After you create the Local Store Adapter you can configure it using the procedures in Section 12.3.1, "Configuring Local Store Adapters."
This section describes how to configure Local Store Adapter settings, including:
After you create the Local Store Adapter you can configure the general settings for the adapter by clicking the adapter name in the Adapter tree, clicking the General tab, setting values for the following fields, and clicking Apply:
This field defines the root DN that the adapter provides information for. The DN defined, and the child entries below it, comprise the adapter's namespace. The value you enter in this field should be the base DN value for returned entries. For example, if you enter dc=mydomain,dc=com in the field, all entries end with dc=mydomain,dc=com.
An adapter can be configured as active (enabled) or inactive (disabled). An adapter configured as inactive does not start during a server restart or an attempted adapter start. Use the inactive setting to keep old configurations available or in stand-by without having to delete them from the configuration. The default setting is active.
If you enable the Read-Only option the adapter does not accept modify transactions and is available for searching only. The default setting is disabled, that is, the adapter is in read/write mode.
The following fields appear in the Indexes section of the General tab:
The Presence field contains a list of attribute types whose presence in entries must be quickly identified, which is required for (attrname=*) style search filters to operate. To add an attribute to the list, click Add, select the attribute from the dialog box that appears, and click OK on the dialog box.
The Exact index field contains a list of attributes for supporting searches for exact match index, for example, sn=smith. When using the ordering index, this index is redundant. To add an attribute to the list, click Add, select the attribute from the dialog box that appears, and click OK on the dialog box.
The Ordering field contains a list of attributes for enabling ordering searches, such as, sn<=Smith, exact searches, and initial substring searches, such as, sn=Smi*. LDAP filters allow only <= and >= ordering relationships. < and > are not supported in LDAPv3. To add an attribute to the list, click Add, select the attribute from the dialog box that appears, and click OK on the dialog box.
The Substring option is only necessary if final substring searches are necessary, for example, sn=*ith, in addition to the ordering index. Initial substring searches are often handled using the ordering index. To add an attribute to the list, click Add, select the attribute from the dialog box that appears, and click OK on the dialog box.
Enables or disables low-performance searching of attributes that are not specifically indexed. If search un-indexed is disabled, searching an un-indexed attribute returns no results (that is, evaluates as false).
The following fields appear in the Security section of the General tab:
Enables or disables sensitive attributes, which are attributes in the Local Store Adapter with encrypted values. If you enable the Enable Sensitive Attribute option, you must identify the attributes whose values will be encrypted using the Sensitive Attributes field.
If Enable Sensitive Attributes is selected, the values of the attributes listed in the Sensitive Attributes field will be encrypted.
The following fields appear in the Database section of the General tab:
The path relative to ORACLE_INSTANCE/ovd/SYSTEM_COMPONENT_NAME and a unique file name prefix for the Local Store Adapter data files. SYSTEM_COMPONENT_NAME is usually ovd1. If you are using multiple Local Store Adapters, this value must be unique for each adapter or data-corruption occurs.
Select the password hash type by choosing an option from the Password Hash Mode list. The most secure algorithm is SSHA, however, others are available for compatibility purposes. Selecting PLAIN leaves the password valued un-hashed in the internal Local Store Adapter data store.
When adding an entry, the LDAP RFCs require that the relative distinguished name, RDN, or left most DN term, be present in the attribute list of the entry being added. Some directory product vendors ignore this and allow for the RDN value to be missing from the attribute list, which may lead to some compatibility problems with applications that depend on this behavior. Enabling Auto RDN, allows Oracle Virtual Directory to automatically create the missing attribute. The default setting is disabled.
After a successful database backup, Oracle Virtual Directory can optionally compress the database files. If the Local Store Adapter data is being modified frequently, this helps keep database size manageable. The default setting is disabled.
Note:
On Windows platforms, it is highly recommended that the Auto Compact feature be disabled. There are some Windows scenarios where the ability to rename files is not guaranteed, which can result in corruption or loss of data.
When a new entry is added or changed, it is first written to a transaction log to allow for faster application response, while ensuring that transactions are written to disk.
This option determines at what size (in bytes) the transaction log is truncated. Entries that have not been placed into the data store and indexed are never removed from the transaction log, even when the number of unprocessed transactions brings the log to a size that exceeds the size listed in this option.
Having a small transaction log that is continuously truncated can add considerable overhead if adding large quantities of entries. It may be better to make the transaction log as large as possible for an initial bulk load, but reduce its size afterward, before going into production.
This option determines the number of entries to be cached by the Local Store Adapter in memory. It always contains the last entries accessed or written. The amount of memory needed is determined by the size of the entries.
Storing very large entries, for example, groups or binary objects, may cause Oracle Virtual Directory to consume more memory than normal. You may have to increase the overall memory available to the Oracle Virtual Directory.
The following fields appear in the Backup section of the General tab:
The path relative to ORACLE_INSTANCE/ovd/SYSTEM_COMPONENT_NAME that points to a unique file name in which automatic backups should be stored. SYSTEM_COMPONENT_NAME is usually ovd1. The backup file name should be unique to the Local Store Adapter to prevent being over-written by another Local Store Adapter.
The hour (0 to 23) of the time at which the Local Store Adapter automatic backup should occur.
The minute (0 to 59) of the time at which the Local Store Adapter automatic backup should occur.
The maximum number of backup files to keep in the backup file rotation for the Local Store Adapter.
After you create the adapter you can configure routing for the adapter by clicking the adapter name in the Adapter tree, clicking the Routing tab, and referring to Section 3.2, "Understanding Routing Settings."
After you create the adapter you can apply Plug-ins and Mappings to the adapter by clicking the adapter name in the Adapter tree, clicking the Plug-Ins tab, and referring to Section 13.1, "Managing Adapter Plug-ins" and Section 14.3, "Applying Mappings to Adapters."
This section explains how to create and configure Join View Adapters and includes the following sections:
Note:
This section assumes that the adapters to be joined using a Join View Adapter already exist.
Prerequisites for Creating a Join View Adapter
Before you can create and deploy any type of Join View Adapter, you must create an adapter to be the Join View Adapter's primary adapter. Refer to "Join View Adapter's Primary Adapter" for more information.
Before you can create a Shadow Join View Adapter, in addition to creating a primary adapter, you must create either a LDAP Adapter connected to Oracle Internet Directory, or a Local Store Adapter to store shadow entries. If you use an LDAP Adapter and Oracle Internet Directory, the base DN of the LDAP Adapter must be in Oracle Internet Directory. If you use a Local Store Adapter, the base DN of the Local Store Adapter must be in Oracle Virtual Directory.
After completing the prerequisites, perform the following steps to create Join View Adapters using Oracle Directory Services Manager:
Log in to Oracle Directory Services Manager.
Select Adapter from the task selection bar. The Adapter navigation tree appears.
Click the Create Adapter button. The New Adapter Wizard appears.
Perform the following steps to define the Type of adapter:
Select Join from the Adapter Type list.
Enter a unique name for the Join Adapter in the Adapter Name field. The adapter name value is used in other configuration fields that must reference the adapter.
Select the Default template from the Adapter Template list.
Note:
After selecting an adapter template, Oracle Directory Services Manager populates default values for some adapter settings. You should alter these default settings according to your environment.
Click Next. The Settings screen appears.
Enter the root DN that the Join View Adapter provides information for in the Adapter Suffix/Namespace field. The DN defined and the child entries below it are the namespace of the adapter. The value entered in this field is the value that appears to clients of the virtual directory. The value should be specified as a comma separated distinguished name.
Caution:
Ensure that the root DN of the Join View Adapter is different from that of its primary adapter or any of the joined adapters, otherwise you can cause unexpected duplicate results.
Choose the primary adapter for the Join View Adapter by selecting it from the Primary Adapter list. The primary adapter is the primary driver of data in the Join View and is used by the Join View Adapter to construct its directory hierarchy. Entries in the Join View Adapter only exist if they exist in the primary adapter. The primary adapter can be any adapter. Refer to "Join View Adapter's Primary Adapter" for more information.
Note:
After defining and debugging a Join View, you can set the primary adapter's Visibility routing setting to Invisible to hide un-joined entries from LDAP clients.
Enter the name of the adapter you want to perform a bind verification with into the Bind Adapter field, or click Browse and select the adapter. While an LDAP client can bind with a DN based on the primary adapter, it may be that the password will be verified against a joined entry in another adapter. The Bind Adapter must be either the primary adapter or one of the joined adapters.
Click Next. The Summary screen appears displaying a summary of the Join View Adapter settings.
Review the Join View Adapter settings and click Finish to create the Join View Adapter. The new Join View Adapter appears in the Adapter tree.
After you create the Join View Adapter you can configure it using the procedures in Section 12.3.1, "Configuring Local Store Adapters."
This section describes how to configure Join View Adapter settings, including:
After you create the Join View Adapter you can configure the general settings and Join Rules for the adapter by clicking the adapter name in the Adapter tree, clicking the General tab, setting values for the following fields, and clicking Apply:
This field defines the root DN that the adapter provides information for. The DN defined, and the child entries below it, comprise the adapter's namespace. The value you enter in this field should be the base DN value for returned entries. For example, if you enter dc=mydomain,dc=com in the field, all entries end with dc=mydomain,dc=com.
Caution:
Ensure that the root DN of the Join View Adapter is different from that of its primary adapter or any of the joined adapters, otherwise you can cause unexpected duplicate results.
An adapter can be configured as active (enabled) or inactive (disabled). An adapter configured as inactive does not start during a server restart or an attempted adapter start. Use the inactive setting to keep old configurations available or in stand-by without having to delete them from the configuration. The default setting is active.
The following fields appear in the Settings section of the General tab:
List of attributes to be treated as DNs for which namespace translation is required, such as member, uniquemember, manager. For example, when reading a group entry from a proxied directory, Oracle Virtual Directory automatically converts the DN for the group entry itself and the uniquemember or member attributes if these attributes are in the DN Attributes list.
Note:
Translate only those attributes you know must be used by the client application. Entering all possible DN attributes may not be necessary and can consume some a small amount of additional CPU time in the proxy.
To add attributes to the Map DN Attributes list:
Click Add. The Select DN Attribute dialog box appears.
Select the attribute you want to add.
Click OK.
The primary adapter is the primary driver of data in the Join View and is used by the Join View Adapter to construct its directory hierarchy. Entries in the Join View Adapter only exist if they exist in the primary adapter. The primary adapter can be any adapter. Refer to "Join View Adapter's Primary Adapter" for more information.
A list of one or more adapter names to be used for bind processing. By default, the primary adapter is used, however you can override this and list one or more other adapters. The Join View Adapter attempts to complete joins against the target adapter and process the bind. If the bind succeeds, processing stops and success is returned to the client. If the bind fails, the Join View Adapter continues trying each adapter in the Bind Adapter list. Only when all bind adapters have failed is a bind failure returned. This is useful when user identities exist in multiple directories and you want to give clients the opportunity to try password validation against multiple directories.
Perform the following steps to create join relationships for Join View Adapters:
Click the Create button. The Join Rule dialog box appears.
Select the adapter from the Adapter list to join with the Join View adapter.
Select the type of join relationship for the Join View Adapter by choosing a join relationship from the Type list. Refer to Section 2.5.2, "Join Relationships" for more information on join relationships.
Enter a join condition in the Condition field as follows:
For Simple Joiners and OneToMany Joiners, enter a condition in the form remoteattribute=primaryadapterattribute where remoteattribute is an attribute in the target joined adapter and primaryadapterattrinute is an attribute from the primary adapter.
For Shadow Joiners, enter a unique key attribute name from the primary adapter, for example, uid, that you can use to locate records in a rename. For Shadow Joiners, the condition is not an equality condition as it is with other joiners.
For ConditionalSimpleJoiners, extend a Simple Joiner type of condition using the ; character and an additional condition, such as "employeenumber>0" for which the join only occurs on.
For example, a Simple Joiner condition could be: employeenumber=employeenumber
Extend this condition for the ConditionalSimpleJoiner using the ; character and an additional condition, for example:
employeenumber=employeenumber;(&(employeenumber=101)(sn=Smith))
Click OK on the Join Rule dialog box to save the join relationship information. The join relationship information appears in the Join Rules table.
Click Apply at the top of the page on the General tab to deploy the join.
Note:
To join two different adapters with different keys to the primary adapter, create multiple Join Rules, each with single key. If you need multiple keys to create a single Join Rule, depending upon the specific criteria, you might be able to use the ConditionalSimpleJoiner or you may have to write a custom Join Rule.
Modifying join relationships for Join View Adapters:
Click the name of the join relationship in the Join Rules table to modify. A split screen appears with the join relationship settings in the lower half of the screen.
Edit the join relationship as desired.
Click Apply in the lower half of the screen to save your changes.
Click Apply at the top of the page on the General tab to deploy the join.
Perform the following steps to delete join relationships for Join View Adapters:
Click the name of the join relationship in the Join Rules table to delete.
Click the Delete button on the Join Rules table. A confirmation dialog box appears asking you to confirm deleting the join relationship.
Click Delete on the confirmation dialog box to delete the join relationship. The join relationship is removed from the Join Rules table.
After you create the adapter you can configure routing for the adapter by clicking the adapter name in the Adapter tree, clicking the Routing tab, and referring to Section 3.2, "Understanding Routing Settings." Additionally, review the following information specific to configuring Join View Adapter routing:
Because the Join View Adapter's primary adapter is the primary driver of data in the Join View and is used by the Join View Adapter to construct its directory hierarchy you also must configure the primary adapter's routing.
Modify the primary adapter's Retrievable Attributes and Storable Attributes routing settings to control which attributes may be written to the primary adapter. If you do not want Oracle Virtual Directory to be able to write any modifications to the primary adapter, set Storable Attributes to _never.
Local Store Adapter Routing as Join View Adapter's Local Store Directory
If you are using a Local Store Adapter as the local store directory for the Join View Adapter you may want to adjust the Local Store Adapter's routing settings also.
Modify the Storable Attributes routing setting for the Local Store Adapter so that only the attributes that are to be written locally are listed. Include the unique key attribute used in the join rule and include the vdeprimaryref attribute. Optionally, set the Visibility routing setting to Internal for the if you do not want it to be seen by LDAP clients.
After you create the adapter you can apply Plug-ins and Mappings to the adapter by clicking the adapter name in the Adapter tree, clicking the Plug-Ins tab, and referring to Section 13.1, "Managing Adapter Plug-ins" and Section 14.3, "Applying Mappings to Adapters."
The following steps are an overview of the process for configuring a Join View Shadow Adapter for use with Oracle Internet Directory:
Extend the Oracle Internet Directory schema to add support for shadow objects/attributes using the following steps:
Create an LDIF file with the following information:
dn: cn=subschemasubentry changetype: modify add: attributetypes attributetypes: ( 1.3.6.1.4.1.17119.1.0.1 NAME 'vdeprimaryref' EQUALITY caseIgnoreMatch SYNTAX '1.3.6.1.4.1.1466.115.121.1.15' USAGE userApplications ) dn: cn=subschemasubentry changetype: modify add: objectclasses objectclasses: ( 1.3.6.1.4.1.17119.1.1.1 NAME 'vdeShadowObject' SUP 'top' STRUCTURAL MUST vdeprimaryref )
Use the Oracle Internet Directory ldapmodify tool to import the LDIF file, for example:
ldapmodify -h ORACLE_INTERNET_DIRECTORY_HOST -p ORACLE_INTERNET_DIRECTORY_PORT -D bindDN -q -v -f PATH_TO_LDIF_FILE
Create a cn=shadowentries orclcontainer object to store the shadow entries in a branch that is separate from normal users to avoid confusing the shadow entries with any other normal user entries.
Create an LDAP Adapter that connects to the Oracle Internet Directory branch you created in Step 2 and set the visibility to internal because only the Shadow Join must access it.
Add vdeprimaryref,uid followed by comma separated list of attributes you want to store in the shadow entry to the Storeable Attributes field. Replace uid with the name of the attribute you can use to identify the entry if the DN changes in the primary adapter. An example may look like:
vdeprimaryref,uid,cn,obpasswordhistory
Set the primary adapter's visibility to internal as the Shadow Join will be the visible "entry" to LDAP clients.
Create a new Join View Adapter and set the bind adapter to be the primary adapter.
Create a new Shadow Join rule as follows:
Set the joined adapter to be the shadow LDAP Adapter you created in Step 1.
Set uid as the condition value, replacing uid with proper value if you are using another attribute as the primary key attribute for the entry.
After completing these steps, when you update the entry exposed through the Join View:
Oracle Virtual Directory determines which attributes must be written to the primary adapter and to the Shadow LDAP.
When Oracle Virtual Directory writes to the Shadow LDAP it first checks to make sure the shadowed entry exists in the LDAP server (by checking for the vderef attribute and then the condition attribute value). If Oracle Virtual Directory does not find an entry, it creates the entry then updates the attributes.
An LDAP client sees a complete entry with all of the attributes when it connects to Oracle Virtual Directory after the update is complete.