11 Creating and Managing Oracle Virtual Directory Listeners

11.2.1 Managing Communication Between Oracle Virtual Directory and Fusion Middleware Control

The communication between Oracle Virtual Directory and Oracle Enterprise Manager Fusion Middleware Control will be disrupted if you edit any of the following settings for the default Listeners (Admin Gateway and LDAP SSL Endpoint):

• Listener Host

• Listener Port

• Enable / Disable SSL

If you edit any of these settings for the default Listeners, you must update the Oracle Enterprise Manager Fusion Middleware Control target discovery information so Oracle Virtual Directory and Oracle Enterprise Manager Fusion Middleware Control can communicate.

To update the Oracle Enterprise Manager Fusion Middleware Control target discovery information, perform the following steps:

1. Log in to Oracle Enterprise Manager Fusion Middleware Control.

2. Right-click the Farm entry in the navigation tree and select Agent-Monitored Targets. The Agent-Monitored Targets screen appears.

3. Click the Configure button for the appropriate Oracle Virtual Directory target in the Targets table. The Configure Target page appears.

4. Update the following settings according to your current Oracle Virtual Directory environment and click OK at the top of the Configure Target page:

   • Machine name

   • Virtual Directory Admin Port

   • Virtual Directory LDAP Port

11.4.1 Creating LDAP Listeners

Perform the following steps to create an LDAP Listener using Oracle Enterprise Manager Fusion Middleware Control. Typically, when running secure and non-secure LDAP, there are at least two Listeners configured; one for regular LDAP (default port is 6501) and one for secure LDAP using SSL (default port is 7501).

1. Log in to Oracle Enterprise Manager Fusion Middleware Control and navigate to the Oracle Virtual Directory target where you want to create the LDAP Listener.

2. Select Administration and then Listeners from the Oracle Virtual Directory menu. The Listeners screen appears.

3. Click the Create button. The Add Listener screen appears.

4. Select LDAP from the Listener Type list and set values for the LDAP Listener configuration parameters as described in Table 11-1:

   Table 11-1 LDAP Listener Configuration Parameters

   Type	Parameter	Description
   Basic	Listener Name	Name of the Listener. Use only ASCII characters in the value for the Listener Name parameter, as non-ASCII characters are not supported.
   	Listener Host	Specify the IP address the Listener should use to listen for connections from clients. By default, Oracle Virtual Directory listens on all IP addresses if no value or 0.0.0.0 is specified for this parameter. Note: Do not use a a loopback IP address, including 127.0.0.1, :0:0:1, localhost, and so on, for the Listener Host setting. If you set this parameter to an IP address or host, the Listener will use that IP address or host to listen for connections from clients, regardless of whether the IP address or host is virtual or real.
   	Listener Port	The port number the Listener will provide service on. Only one Listener per server can be active on a port at any given time. If Oracle Virtual Directory is installed on the same server as an existing server, for example, an Active Directory domain controller, enter a port that will not conflict with the existing service.
   	Threads	The number of active worker threads the Listener will use to concurrently process incoming requests. The Listener will automatically increase the number of threads if you enter an insufficient amount. This initial setting serves only to indicate to Oracle Virtual Directory the expected amount of simultaneous clients so that it can pre-allocate resources. The default setting is 10, which should be sufficient for testing purposes. For production environments, Oracle recommends to increase this setting to 50.
   	Listener Enabled	Enables (selected) and disables (not selected) the Listener for service.
   LDAP Options	Anonymous Bind	Controls how Oracle Virtual Directory handles LDAP anonymous authentication. Allow will allow anonymous authentication; Deny will prevent anonymous operations; and DenyDNOnly will prevent empty password authentication. Note: According to the LDAP protocol specification, if an LDAP client connects to an LDAP server with a non-empty DN and an empty password, the LDAP server is expected to provide a successful anonymous bind. For applications that are using LDAP for authentication, this could allow end-users to log in to their applications without entering a password. Most LDAP-enabled applications prevent against this use case. However, as added security, you can configure Oracle Virtual Directory to prevent this from happening as an extra-safeguard.
   	Work Queue Capacity	Specifies the maximum number of pending LDAP requests that can accumulate when all worker threads associated with LDAP Listener are busy processing requests. Once the specified capacity is reached, the LDAP Listener rejects new requests with DSA is busy error. The default value is 1024.
   	Allow StartTLS	Determines whether or not LDAP clients can use StartTLS. If enabled, the LDAP Listener allows clients to use the StartTLS extended operation to initiate secure communication over an insecure channel.
   Socket Options	Backlog	Determines the maximum number of pending connection requests that can accumulate before the server starts rejecting new connection attempts. Default setting is 128.
   	Read Timeout	Enables and disables tolerance for idle client connections with the specified timeout period in milliseconds. If set to a non-zero time, client connections to the Oracle Virtual Directory server can remain idle only for the set amount of time. If the connection is idle for a period longer than the specified time, the client connection is terminated. A value of zero is considered an infinite timeout. The default value is 0.
   	Reuse Address	Determines whether or not the LDAP Listener should reuse socket descriptors. If enabled, socket descriptors for clients in TIME_WAIT state can be reused.
   	TCP Keep Alive	Determines whether or not the LDAP connection should use TCP keep-alive. If enabled, TCP keep-alive messages are periodically sent to the client to verify that the associated connection is still valid.
   	TCP No Delay	Determines whether or not the LDAP connection should use TCP no-delay. If enabled, response messages to the client are sent immediately, rather than potentially waiting to determine whether additional response messages can be sent in the same packet.

   
   

5. Click the OK button on the Add Listener screen to save the LDAP Listener.

6. Stop Oracle Virtual Directory if it is running by referring to Stopping the Oracle Virtual Directory Server Using Fusion Middleware Control. After it stops, start Oracle Virtual Directory by referring to Starting the Oracle Virtual Directory Server Using Fusion Middleware Control.

   Note:

   You must explicitly stop and start Oracle Virtual Directory—not Restart—to load the Listener configuration to the Oracle Virtual Directory server.

11.4.2 Creating HTTP Listeners

Perform the following steps to create an HTTP Listener using Oracle Enterprise Manager Fusion Middleware Control:

1. Log in to Oracle Enterprise Manager Fusion Middleware Control and navigate to the Oracle Virtual Directory target where you want to create the HTTP Listener.

2. Select Administration and then Listeners from the Oracle Virtual Directory menu. The Listeners screen appears.

3. Click the Create button. The Add Listener screen appears.

4. Select HTTP from the Listener Type list and set values for the HTTP Listener configuration parameters as described in Table 11-2:

   Table 11-2 HTTP Listener Configuration Parameters

   Type	Parameter	Description
   Basic	Listener Name	Name of the Listener. Use only ASCII characters in the value for the Listener Name parameter, as non-ASCII characters are not supported.
   	Listener Host	Specify the IP address the Listener should use to listen for connections from clients. By default, Oracle Virtual Directory listens on all IP addresses if no value or 0.0.0.0 is specified for this parameter. Note: Do not use a a loopback IP address, including 127.0.0.1, :0:0:1, localhost, and so on, for the Listener Host setting. If you set this parameter to an IP address or host, the Listener will use that IP address or host to listen for connections from clients, regardless of whether the IP address or host is virtual or real.
   	Listener Port	The port number the Listener will provide service on. Only one Listener per server can be active on a port at any given time.
   	Threads	The number of active worker threads the Listener will use to concurrently process incoming requests. The Listener will automatically increase the number of threads if you enter an insufficient amount. This initial setting serves only to indicate to Oracle Virtual Directory the expected amount of simultaneous clients so that it can pre-allocate resources. The default setting is 10, which should be sufficient for testing purposes. For production environments, Oracle recommends to increase this setting to 50.
   	Listener Enabled	Enables (selected) and disables (not selected) the Listener for service.
   DSML V2 Service	Realm Name	Name of the realm used by Oracle Virtual Directory to protect the DSMLv2 service when the DSMLv2 service is security enabled. This realm name would appear in a HTTP browser challenge to the user.
   Web Gateway Service Section	Allow Anonymous Access	Enables and disables anonymous access to the Web Gateway.
   	Search Root	The root distinguished name (namespace) of the directory tree where the Web Gateway will start its sub-tree search for user identity names (UIDs) provided after a user authentication challenge.
   	Search Attributes	The attribute the Web Gateway attempts to match when searching for a UID.
   	User Object Classes	The objectclasses the Web Gateway uses when searching for users to authenticate.
   	Result Cache Life (seconds)	Maximum time that Oracle Virtual Directory will wait before requerying a user credential stored in the directory source.
   	HTDocs Path	The directory path, relative to the Oracle Virtual Directory root installation, where the XSLT and HTML files are located.
   	Certificate Attributes	Indicates which attributes contain binary PKI certificate information. The default value is usercertificate.
   	Photo/Image Attributes	Indicates which attributes contain graphical images. The default value is jpegphoto.
   	Image Display Height	The height the Web Gateway scales photos to. The default value is 100.
   	Image Display Width	The width the Web Gateway scales photos to. The default value is 100.

   
   

5. Click the OK button on the Add Listener screen to save the HTTP Listener.

6. Stop Oracle Virtual Directory if it is running by referring to Stopping the Oracle Virtual Directory Server Using Fusion Middleware Control. After it stops, start Oracle Virtual Directory by referring to Starting the Oracle Virtual Directory Server Using Fusion Middleware Control.

   Note:

   You must explicitly stop and start Oracle Virtual Directory—not Restart—to load the Listener configuration to the Oracle Virtual Directory server.

11.4.3 Managing Listeners

This topic explains how to manage Oracle Virtual Directory Listeners using Oracle Enterprise Manager Fusion Middleware Control and contains the following sections:

• Editing Listener Settings

• Deleting Listeners

11.5.1 Updating Listener Settings

You can use WLST to update the settings for an existing Listener as follows:

1. Launch the WLST command line tool shell.

2. Connect to the WebLogic Admin Server. For example:

   connect('username', 'password','t3://host_name:Admin_Server_Port')
   

3. Move to the Oracle Virtual Directory Root Proxy MBean node and initialize the MBean. For example:

   custom()
   cd('oracle.as.management.mbeans.register')
   cd('oracle.as.management.mbeans.register:type=component,name=ovd1,instance=asin
   st1')
   invoke('load',jarray.array([],java.lang.Object),jarray.array([],java.lang.Strin
   g)) 
   

4. Move to the MBean node for the Listener you want to update, for example, the Listener named LDAP SSL Endpoint:

   cd('../..')
   cd('oracle.as.ovd')
   cd('oracle.as.ovd:type=component.Listenersconfig.sslconfig,name=LDAP SSL 
   Endpoint,instance=asinst_1,component=ovd1')
   

5. Using the WLST set() command, update the appropriate setting. The following example updates the Threads setting:

   set('Threads', 20)
   

   Notes:

   • Do not use a a loopback IP address, including 127.0.0.1, :0:0:1, localhost, and so on, for the Host setting.

   • If you edit the Host, Port, or SSL setting for the Admin Listener, you must update the Oracle Virtual Directory component registration by referring to Updating the Component Registration of an Oracle Instance Using OPMNCTL. If you do not update the Oracle Virtual Directory component registration after editing any of these settings for the Admin Listener, you will not be able to communicate with Oracle Virtual Directory using WLST.

   See Also:

   The following sections to learn more about the Listener settings you can configure using WLST:

   • Configuring Admin Listener Settings Using WLST

   • Configuring LDAP Listener Settings Using WLST

   • Configuring HTTP Listener Settings Using WLST

6. Save the changes and then refresh the MBean. For example:

   cd('../..')
   cd('oracle.as.management.mbeans.register')
   cd('oracle.as.management.mbeans.register:type=component,name=ovd1,instance=asin
   st1')
   invoke('save',jarray.array([],java.lang.Object),jarray.array([],java.lang.Strin
   g))
   invoke('load',jarray.array([],java.lang.Object),jarray.array([],java.lang.Strin
   g))
   

7. Stop Oracle Virtual Directory if it is running. After it stops, start Oracle Virtual Directory.

   Note:

   You must explicitly stop and start Oracle Virtual Directory—not Restart—to load the Listener configuration to the Oracle Virtual Directory server.

11.5.2 Deleting Listeners

You can use WLST to delete an existing Listener as follows:

1. Launch the WLST command line tool shell.

2. Connect to the WebLogic Admin Server. For example:

   connect('username', 'password','t3://host_name:Admin_Server_Port')
   

3. Move to the Oracle Virtual Directory Root Proxy MBean node and initialize the MBean. For example:

   custom()
   cd('oracle.as.management.mbeans.register')
   cd('oracle.as.management.mbeans.register:type=component,name=ovd1,instance=asin
   st1')
   invoke('load',jarray.array([],java.lang.Object),jarray.array([],java.lang.Strin
   g)) 
   

4. Move to the Oracle Virtual Directory Listeners configuration MBean. For example:

   cd('../..')
   cd('oracle.as.ovd/oracle.as.ovd:type=component.Listenersconfig,name=Listenersco
   nfig,instance=asinst1,component=ovd1') 
   

5. Delete the appropriate Listener, for example, the Listener named test1, as follows:

   invoke('deleteListener',jarray.array([java.lang.String('test1')],java.lang.Obje
   ct),jarray.array(['java.lang.String'],java.lang.String))
   

6. Save the changes and then refresh the MBean. For example:

   cd('../..')
   cd('oracle.as.management.mbeans.register')
   cd('oracle.as.management.mbeans.register:type=component,name=ovd1,instance=asin
   st1')
   invoke('save',jarray.array([],java.lang.Object),jarray.array([],java.lang.Strin
   g))
   invoke('load',jarray.array([],java.lang.Object),jarray.array([],java.lang.Strin
   g))
   

7. Stop Oracle Virtual Directory if it is running. After it stops, start Oracle Virtual Directory.

   Note:

   You must explicitly stop and start Oracle Virtual Directory—not Restart—to load the Listener configuration to the Oracle Virtual Directory server.

11.6.1 Configuring SSL for Listeners Using Fusion Middleware Control

Perform the following steps to secure Oracle Virtual Directory Listeners with SSL using Oracle Enterprise Manager Fusion Middleware Control:

1. Log in to Oracle Enterprise Manager Fusion Middleware Control and navigate to the Oracle Virtual Directory target of the Listener you want to secure with SSL.

2. Create a keystore if one does not already exist by selecting Security and then Keystores from the Oracle Virtual Directory menu. The Java Keystore screen appears. Refer to the information about creating a keystore using Oracle Enterprise Manager in the Oracle Fusion Middleware Administrator's Guide for additional information.

3. Configure the Listener by performing the following steps:

   1. Select Administration and then Listeners from the Oracle Virtual Directory menu. The Listeners screen appears.

   2. Select the Listener you want to secure with SSL by clicking on it and then click the Edit button. The Edit Listener: Listener Name screen appears.

   3. Click the Change SSL Settings link.

   4. Click the Enable SSL option to enable SSL on the Listener. If you are configuring the Listener for SSL No-Auth mode, skip to step i now.

   5. Select the keystore you want to use from the Server Keystore Name field.

      Note:

      If you select a different keystore or change the certificate in the keystore for the Admin Gateway Listener or the LDAP SSL Endpoint Listener, you must import the certificate into the Oracle Enterprise Manager Fusion Middleware Control Agent's wallet. If you do not import the certificate, Oracle Enterprise Manager Fusion Middleware Control cannot connect to Oracle Virtual Directory to retrieve performance metrics.

      To import the certificate into the Oracle Enterprise Manager Fusion Middleware Control Agent's wallet:

      1. Export the Oracle Virtual Directory server certificate by executing the following command:

         ORACLE_HOME/jdk/jre/bin/keytool -exportcert \
         -keystore OVD_KEYSTORE_FILE -storepass PASSWORD \
         -alias OVD_SERVER_CERT_ALIAS -rfc \
         -file OVD_SERVER_CERT_FILE
         

      2. Add the Oracle Virtual Directory server certificate to the Oracle Enterprise Manager Fusion Middleware Control Agent's Wallet by executing the following command:

         ORACLE_COMMON_HOME/bin/orapki wallet add -wallet \
         $ORACLE_INSTANCE/EMAGENT/EMAGENT/sysman/config/monwallet \
         -trusted_cert -cert OVD_SERVER_CERT_FILE -pwd WALLET_PASSWORD
         

   6. Enter the password for the keystore in the Server Keystore Password field.

      Note:

      The password for the keystore that is created during the Oracle Virtual Directory installation is the same as the password set for the Oracle Virtual Directory administrator during installation.

   7. Select the truststore you want to use from the Server Truststore Name field.

   8. Enter the password for the truststore in the Server Truststore Name field.

   9. Click and expand the Advanced SSL Setting option.

   10. Select one of the following authentication modes for the Listener from the Client Authentication field.

       To configure the Listener for SSL No-Authentication Mode, select No Authentication.

       To configure the Listener for SSL Server Authentication Mode, select Server Authentication.

       To configure the Listener for SSL Mutual Authentication mode between the Oracle Virtual Directory server and the client, select Mutual Authentication.

       Note:

       The Optional Client Authentication mode is not supported for Oracle Virtual Directory Listeners.

   11. Select the appropriate option from the Cipher Suite field. You can select All, or a combination of individual options.

       Note:

       If you are configuring the Listener for SSL No-Auth mode, you must select at least one DH_anon cipher. For all other SSL modes, you must select at least one RSA cipher.

   12. Select the appropriate option from the SSL Protocol Version field.

       Note:

       The v2Hello option is not supported by itself. That is, you cannot select the v2Hello option alone—you must select it in combination with at least one additional SSL Protocol Versions from the list.

   13. Click the OK button.

4. Stop Oracle Virtual Directory if it is running by referring to Stopping the Oracle Virtual Directory Server Using Fusion Middleware Control. After it stops, start Oracle Virtual Directory by referring to Starting the Oracle Virtual Directory Server Using Fusion Middleware Control.

   Note:

   You must explicitly stop and start Oracle Virtual Directory—not Restart—to load the Listener configuration to the Oracle Virtual Directory server.

11.6.2 Configuring SSL for Listeners Using WLST

To configure SSL for Oracle Virtual Directory using the WLST command line tool:

1. Launch the WLST command line tool shell.

2. Go to the custom tree using the following command:

   custom()
   

3. Navigate to the root Oracle Virtual Directory mBean using the following commands:

   cd('oracle.as.management.mbeans.register')
   cd('oracle.as.management.mbeans.register:type=component,name=COMPONENT_
   NAME,instance=INSTANCE_NAME')
   

4. Initialize the Oracle Virtual Directory configuration from the remote Oracle Virtual Directory server into the WebLogic server using the following command:

   invoke('load',jarray.array([],java.lang.Object),jarray.array([],
   java.lang.String))
   

5. Identify the Listeners for this Oracle Virtual Directory component by executing the following command:

   listListeners('instName', 'compName')
   

   For example:

   listListeners('instance1','ovd1')
   

   The command lists all the Listeners for the component named ovd1. In the list of Listeners returned, identify the Listener you want to secure using SSL. For example, imagine you want to secure the Listener named LDAP SSL Endpoint.

6. Display the existing SSL configuration for the Listener you want secure (LDAP SSL Endpoint in this example) using the following command:

   getSSL('instance1','ovd1','ovd','LDAP SSL Endpoint')
   

7. Display the existing keystores using the following command:

   listKeyStores('instance1','ovd1','ovd')
   

8. If you need to, create a new keystore and a self-signed certificate using the following commands.

   To create the new keystore, execute the following command:

   createKeyStore('instance1','ovd1','ovd','NEW_KEYSTORE_NAME','PASSWORD_FOR_NEW_KEYSTORE')
   

   To create a self-signed certificate in the new keystore, execute the following command:

   generateKey ('instance1','ovd1','ovd','NEW_KEYSTORE_NAME','PASSWORD_FOR_NEW_KEYSTORE', 'DN', 'keySize', 'alias')
   

9. Identify the name of the SSL MBean for the Oracle Virtual Directory Listener by executing the following command:

   getSSLMBeanName('instance1','ovd1','ovd','LDAP SSL Endpoint')
   

10. Set the passwords for the keystore and truststore in the MBean by executing the following commands:

    cd ('SSL_MBEAN_NAME')
    set('KeyStorePassword',java.lang.String('PASSWORD').toCharArray())
    set('TrustStorePassword',java.lang.String('PASSWORD').toCharArray())
    

11. Configure the SSL settings for the Listener using the following command and file.prop. An sample file.prop file is given for reference:

    configureSSL ('instance1', 'ovd1', 'ovd', 'LDAP SSL Endpoint', 'PATH_TO_file.prop')
    

    Note:

    If you configure a different keystore or change the certificate in the keystore for the Admin Gateway Listener or the LDAP SSL Endpoint Listener, you must import the certificate into the Oracle Enterprise Manager Fusion Middleware Control Agent's wallet. If you do not import the certificate, Oracle Enterprise Manager Fusion Middleware Control cannot connect to Oracle Virtual Directory to retrieve performance metrics.

    To import the certificate into the Oracle Enterprise Manager Fusion Middleware Control Agent's wallet:

    1. Export the Oracle Virtual Directory server certificate by executing the following command:

       ORACLE_HOME/jdk/jre/bin/keytool -exportcert \
       -keystore OVD_KEYSTORE_FILE -storepass PASSWORD \
       -alias OVD_SERVER_CERT_ALIAS -rfc \
       -file OVD_SERVER_CERT_FILE
       

    2. Add the Oracle Virtual Directory server certificate to the Oracle Enterprise Manager Fusion Middleware Control Agent's Wallet by executing the following command:

       ORACLE_COMMON_HOME/bin/orapki wallet add -wallet \
       $ORACLE_INSTANCE/EMAGENT/EMAGENT/sysman/config/monwallet \
       -trusted_cert -cert OVD_SERVER_CERT_FILE -pwd WALLET_PASSWORD
       

    Example 11-1 Sample file.prop File

    SSLEnabled=true
    AuthenticationType=auth_type
    SSLVersions=version
    Ciphers=cipher
    KeyStore=name_of_your_keystore
    TrustStore=name_of_your_keystore
    

    Important Notes Regarding the file.prop File: 

    • Replace the variable values in the Example 11-1 with the values for your environment.

    • If you are configuring the Listener for SSL No-Auth mode, you must select at least one DH_anon cipher. For all other SSL modes, you must select at least one RSA cipher.

    • You must specify the value of the KeyStore parameter when configuring SSL for server-auth and mutual-auth modes.

    • If you specify only AES ciphers, the SSLVersions parameter must contain TLSv1.

    • The text in the file.prop file is case sensitive.

    • Do not use spaces after cipher entries in the file.prop file.

    • Refer to the "Properties Files for SSL" section in the Oracle Fusion Middleware Administrator's Guide for more information about the contents of the file.prop file.

    See Also:

    The following sections for information about the AuthenticationType, SSLVersions, and Ciphers you can configure in File.prop:

    • Configuring Admin Listener Settings Using WLST

    • Configuring LDAP Listener Settings Using WLST

    • Configuring HTTP Listener Settings Using WLST

12. Stop Oracle Virtual Directory if it is running. After it stops, start Oracle Virtual Directory.

    Note:

    You must explicitly stop and start Oracle Virtual Directory—not Restart—to load the Listener configuration to the Oracle Virtual Directory server.

11.6.3 Validating the SSL Connection

This topic explains how to validate SSL connections for each SSL mode and contains the following sections:

• SSL No-Authentication Mode

• SSL Server Auth Mode

• SSL Mutual Authentication Mode

ORACLE_HOME/bin/ldapbind -D cn=orcladmin -q -U 1 -h HOST -p SSL_PORT