Configuring C-Enablers

 

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

• Modifying the C-Enabler Configuration File

• Configuring the C-Enabler Administration Console

• Configuring C-Enabler Security

 

---

Modifying the C-Enabler Configuration 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 a c-enabler configuration file.

To create a new c-enabler XML configuration file:

1. Using your preferred text editor, create a new XML file that specified EnablerConfig.dtd as the DTD for that document.

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\dtd 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 and xerces.jar files 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, configure the web application in the Web Logic Server Administration Console. For more information, see "Deploying Applications" in the BEA WebLogic Server Administration Guide.

 

---

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 in 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: 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. Use the Weblogic Server Administration Console to modify the SSL protocol and mutual authentication properties as shown in the following listing. When you are finished, the completed code from the Console should look like the following example.

   Listing 2-3 SSL Protocol and Mutual Authentication Properties

   < SSL CertAuthenticator="com.bea.b2b.security.WLCCertAuthenticator"
           CertificateCacheSize="5"
           ClientCertificateEnforced="true"
           Enabled="true"
           HandlerEnabled="true"
           ListenPort="SSL Port"
           Name="myserver"
           ServerCertificateFileName="Trading Partner Certificate file"
           ServerKeyFileName="Trading Partner private key file" 
                   ServerCertificateChainFileName="rest of the digital certificates for Trading Partner"
           TrustedCAFileName="Certificate for root CA"
   />

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

" Trading partner private key file" specifies the name of the file containing the trading partner's private key.

"SSL port" specifies the dedicated port on which the c-enabler listens for Secure Socket Layer connections. The config.xml file for the c-enabler sets the SSL port to 7502.

"ServerCertificateChainFileName" is the file holding any remaining digital certificates held by the 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 config.xml configuration file for the c-enabler sets the root certificate authority 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 and private-key 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 BEA WebLogic Collaborate C-Hub Administration Guide.

For complete information on defining users, see "Managing Security" in the BEA WebLogic Server 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

For complete information on defining users, see "Managing Security" in the BEA Weblogic Server Administration Guide.

Defining Access Control Lists for the C-Enabler

Whether a user or a group can access a resource in WebLogic Collaborate is determined by the access control lists (ACLs) 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

For more information about defining ACLs, see "Defining ACLs" in "Managing Security" in the BEA Weblogic Server Administration Guide.