Configuring C-Enablers

 

The following sections are intended for system administrators. These sections contain information about configuring the c-enabler XML file, the C-Enabler Administration Console, and c-enabler security:

• Configuring the C-Enabler XML File

• Configuring the C-Enabler Administration Console

• Configuring C-Enabler Security

 

---

Configuring the C-Enabler XML File

To participate in c-hub conversations, a trading partner creates c-enabler sessions between a c-enabler node and the c-hub. Each c-enabler session allows the trading partner to collaborate with other trading partners in a single c-space. Configuration information about c-enabler sessions is read at run time from the c-enabler XML file, EnablerConfig.dtd.

To configure the c-enabler XML file:

1. Open EnablerConfig.dtd in a text editor.

2. Specify values for the DTD elements (see Specifying Values for the DTD Elements for additional information).

3. Validate the XML file structure (see Validating the XML File Structure for additional information).

Specifying Values for the DTD Elements

The following listing shows EnablerConfig.dtd, the DTD for the c-enabler XML file. This file is located in the wlc_home\enabler\config subdirectory of your WebLogic Collaborate installation directory for both Windows and UNIX.

Listing 2-1 EnablerConfig.dtd

---

<!--	Copyright (c) 2000 BEA Systems, Inc. -->
<!--	All rights reserved                  -->
<!--	THIS IS UNPUBLISHED PROPRIETARY      --> 
<!--	SOURCE CODE OF BEA Systems, Inc.     -->
<!--	The copyright notice above does not  -->
<!--	evidence any actual or intended      -->
<!--	publication of such source code.        -->

<!-- $Id: //depot/dev/src/com/bea/b2b/dtd/EnablerConfig.dtd#6 $-->

<!-- This DTD describes enabler configuration files -->

<!-- Digital certificate information of trading partner -->
<!ELEMENT certificate EMPTY >

<!-- Location of digital certificate key of trading partner on the enabler node -->
<!ATTLIST certificate location CDATA #REQUIRED >

<!ELEMENT enabler (session*) >
<!ATTLIST enabler name CDATA #REQUIRED >

<!-- URL of the enabler session where incoming business documents are received -->
<!ELEMENT enabler-url EMPTY >
<!ATTLIST enabler-url ref CDATA #REQUIRED >

<!-- URL of the Hub -->
<!ELEMENT hub-url EMPTY >
<!ATTLIST hub-url 
	 ref CDATA #REQUIRED 
	 certificate-field-name CDATA #IMPLIED
	 certificate-field-value CDATA #IMPLIED
	 server-certificate-field-name CDATA #IMPLIED
	 server-certificate-field-value CDATA #IMPLIED
	 hub-user CDATA #IMPLIED
	 proxy-host CDATA #IMPLIED
	 proxy-port CDATA #IMPLIED >

<!ELEMENT private-key EMPTY >

<!-- Location of private-key of trading partner on the enabler node -->
<!ATTLIST private-key location CDATA #REQUIRED >
<!ELEMENT trading-partner EMPTY >

<!-- Name of the trading partner as per subscription in C-Space -->
<!ATTLIST trading-partner name CDATA #REQUIRED >

<!-- Security information is required if https is used -->
<!ELEMENT security-info ( (certificate, private-key) | trading-partner) >
<!ELEMENT session (hub-url, enabler-url, security-info) >

<!-- Name of the c-space on hub where trading partner has subscribed to conversations  -->
<!ATTLIST session c-space-name CDATA #REQUIRED >

<!-- Name of individual enabler session with which it is identified locally on enabler node -->
<!ATTLIST session name CDATA #REQUIRED >

<!-- Thread pool size for the session -->
<!ATTLIST session thread-pool-size CDATA #IMPLIED >

---

The following table describes the elements used in EnablerConfig.dtd.

Table 2-1 Elements Used in EnablerConfig.dtd

Element	Description
enabler	Root element of the document. The name attribute uniquely identifies the c-enabler inside a WebLogic Server instance.
session	Defines a c-enabler session.This element can have hub-url, enabler-url, and security-info subelements (in that order). Element attributes include: c-space-name—Name of the c-space that the trading partner wants to join. name— Name of the session that hosts the conversation between the c-hub and c-enabler. thread-pool-size—Thread-pool size for the session.
hub-url	Defines characteristics of the c-hub. Element attributes include: ref—URL of the c-hub that participates in the conversation. certificate-field-name—Type of certificate used for client-side security. This element is related to SSL and is used to map trading-partner certificates to WebLogic Server users. certificate-field-value—Value for client-side security. server-certificate-field-name— Type of certificate used for server-side security. This element is related to SSL and is used to map trading-partner certificates to WebLogic Server users. server-certificate-field-value—Value for server-side security. hub-user—WebLogic Server user name under which the c-enabler will be running when processing messages received from the c-hub. proxy-host—Address of the proxy server used for the c-hub, if any. proxy-port—Port number for the proxy server used for the c-hub, if any.
enabler-url	Defines characteristics of the c-enabler. The ref attribute specifies the URL of the c-enabler that participates in the conversation. As WebLogic Collaborate assigns this URL to a servlet, it must be reserved for exclusive use of WebLogic Collaborate only. Such a URL must not be used by applications for any other purpose. Each c-space/business protocol combination has a unique URL. A trading partner uses this URL to access a particular c-space using a particular business protocol.
security-info	Defines security information for the conversation between the c-hub and c-enabler. This element can have certificate and private-key subelements (in that order) or trading-partner subelements.
trading-partner	Defines characteristics of a trading partner. The name attribute specifies the name of the trading partner on whose behalf the c-enabler session is established.
certificate	Defines digital certificate information for the trading partner. The location attribute specifies the location of the digital certificate key.
private-key	Defines characteristics of the private key for the trading partner. The location attribute specifies the location of the private key.

The following listing is a sample c-enabler XML file with all elements defined.

Listing 2-2 Sample C-Enabler XML File

---

<?xml version="1.0"?> 
<!DOCTYPE enabler SYSTEM "EnablerConfig.dtd"> 
<enabler name="SecurityPartner1Enabler">
    <session name="Session1" c-space-name="SecurityCSpace">
        <hub-url ref="https://localhost:7002/Hub/SecurityCSpace"
            certificate-field-name="email"
            certificate-field-value="[e-mail]" 
            server-certificate-field-name="email"
            server-certificate-field-value="[e-mail]" 
            hub-user="hub" /> 
        <enabler-url ref="https://localhost:7502/Enabler1"/>
        <security-info>
            <certificate location="<WLC_HOME>\examples\security
                \certificates\partner1_cert.pem"/>
            <private-key location="<WLC_HOME>\examples\security
                \certificates\partner1_key.pem"/>
        </security-info>
    </session>
</enabler>

---

Validating the XML File Structure

WebLogic Collaborate provides the Reader utility to validate c-enabler XML files.To use Reader, you must include the wlc.jar file in your CLASSPATH variable. You must also include the wlc_home\bin subdirectory of your WebLogic Collaborate installation in your PATH variable.

To run Reader, enter the following command at the Windows command prompt:

enablerreader [-?] | configFilename

The arguments to this command are defined as follows:

• configFilename is the name of the c-enabler XML file that you want to validate.

• -? displays help about Reader.

You can also validate a c-enabler XML file with a Java interpreter by entering the following command at the Windows command prompt:

java -classpath %classpath% com.bea.b2b.hub.EnablerConfigReader [-?] | configFilename

The arguments for this command are identical to the arguments for enablerreader.

 

---

Configuring the C-Enabler Administration Console

To configure the C-Enabler Administration Console, define the C-Enabler Administration Console Web application.

The C-Enabler Administration Console is a J2EE Web application. The file for this Web application is enableradmin.war, which is located in the wlc_home\lib subdirectory of your WebLogic Collaborate installation directory.

To define the C-Enabler Administration Console Web application, set the following value in the weblogic.properties file:

# Administration Console Web Application
weblogic.httpd.webApp.WLCEnablerAdmin=
wlc_home/lib/enableradmin.war

For example:

weblogic.httpd.webApp.WLCEnablerAdmin=
d:/bea/WLC/lib/enableradmin.war

 

---

Configuring C-Enabler Security

The security model in WebLogic Collaborate is based on the one used in Weblogic Server (that is, authentication and authorization are used to protect resources). For general information about the WebLogic Collaborate security model, see Configuring Security the BEA WebLogic Collaborate C-Hub Administration Guide.

C-enabler security consists of configuring SSL protocol and mutual authentication properties, defining c-enabler users, and defining c-enabler access control lists (ACLs).

Configuring SSL Protocol and Mutual Authentication

To configure SSL protocol and mutual authentication properties:

1. Obtain a digital certificate for the c-enabler. WebLogic Collaborate ships four digital certificates and four private keys (one certificate and one private key for a c-hub, a c-enabler, and two trading partners) in the wlc_home/examples/security/certificates directory. The directory also contains a digital certificate for the root certificate authority.

   Note: Each trading partner requires its own c-enabler. The digital certificates and private keys shipped with WebLogic Collaborate are for demonstration purposes only. Before using WebLogic Collaborate in a deployed, production environment, obtain digital certificates and private keys from a security vendor or an in-house certificate authority.

2. Modify the weblogic.properties file to set the SSL protocol and mutual authentication properties as shown in the following listing.

   Listing 2-3 SSL Protocol and Mutual Authentication Properties

   ---

   #Enable the use of the SSL protocol
   weblogic.security.ssl.enable=true
   weblogic.system.SSLListenPort=SSL port
   
   #Define information about digital certificates and private keys
   weblogic.security.clientRootCA=Client Root CA
   weblogic.security.certificate.server=Trading partner certificate
           file
   weblogic.security.key.server=Trading partner private key file
   weblogic.security.certificate.authority=Certificate for root CA
   
   #Enable mutual authentication
   weblogic.security.enforceClientCert=true
   
   #Specifies whether or not the c-enabler rejects SSL connections that #fail client authentication.
   weblogic.security.SSLHandler.enable=true

   ---

   The variables in weblogic.properties are defined as follows:

   • SSL port specifies the dedicated port on which the c-enabler listens for SSL connections. The weblogic.properties file for the c-enabler has the SSL port set to 7002.

   • Client Root CA specifies the name of the digital certificate for the certificate authority used to issue digital certificates for trading partners. The c-enabler is required to present digital certificates issued by this certificate authority. The weblogic.properties file for the c-enabler has the client root CA set to CA_cert.pem.

   • Trading partner certificate file specifies the name of the digital certificate for a trading partner.

   • Certificate for root CA specifies the name of the digital certificate for the certificate authority that issued the digital certificate for the c-enabler. The weblogic.properties file for the c-enabler has the certificate for root CA set to CA_cert.pem.

     Note: When using mutual authentication, you can use the digital certificate for the certificate authority for both the c-hub and the c-enabler.

Configuring SSL Security

To configure SSL security:

1. Set the following attributes for the hub-url XML element in the c-enabler XML configuration file:

   • certificate-field-name

   • certificate-field-value

   • server-certificate-field-name

   • server-certificate-field-value

   • hub-user

2. Set the certificate attribute for the security-info XML element in the c-enabler XML configuration file.

For a description of these attributes, see Table 2-1.

Configuring a Proxy Server

To configure a proxy server:

1. Set the proxy-host and proxy-port attributes for the hub-url XML element in the c-enabler XML configuration file. For a description of these attributes, see Table 2-1.

2. Configure a proxy server as described in the Configuring Security chapter in the C-Hub Administration Guide.

Defining Users on the C-Enabler

You define the following types of users for a c-enabler:

• C-hub user

• C-enabler administrator user

Include the following lines in the weblogic.properties file to define these users:

weblogic.password.hub=password for hub user
weblogic.password.admin=password for enabler administrator user 

Defining ACLs for the C-Enabler

Whether a user or a group can access a resource in WebLogic Collaborate is determined by the ACL for that resource. To define ACLs, create an ACL for a resource, specify the permission for that resource, and then grant permission to a specified set of users and groups.

Each WebLogic Collaborate resource has one or more permissions that you can grant. The ACLs (resources and permissions) are defined as follows:

• Transport servlet resource for a c-hub user only has execute permission

• C-Enabler Administration Console resource for a c-enabler administrator has enablermonitor permission

Include the following lines in the weblogic.properties file to define these ACLs:

#ACL for transport servlet
weblogic.allow.execute.weblogic.servlet.enabler=hub

#ACL for Administration Console
weblogic.allow.enablermonitor.WLCAdmin=admin