Configuring Security

 

This following sections describe how to configure security in BEA WebLogic Collaborate:

• Introduction to the WebLogic Collaborate Security Model

• Security Terminology

• Configuring the SSL Protocol and Mutual Authentication

• Defining Users and Groups

• Defining Access Control Lists

• Specifying Information in the Repository

• Working with the WLCCertAuthenticator Class

• Configuring WebLogic Collaborate to Use an HTTP Proxy Server

For information about configuring administration security, see Configuring and Running the C-Hub Administration Console.

 

---

Introduction to the WebLogic Collaborate Security Model

The WebLogic Collaborate security model uses the security features of the underlying BEA WebLogic Server^TM platform.

Authentication is the process of verifying a principal's identity before completing a connection. Authentication protects who gets access to the WebLogic Collaborate environment. WebLogic Collaborate uses the following methods to perform authentication:

• Username and password—Human users (administrators) use a username and password to prove their identity.

• Digital certificates—Principals in the WebLogic Collaborate environment other than human users use digital certificates to prove their identity to other principals.

• Secure sockets layer (SSL)—The SSL protocol provides data integrity and confidentiality to the connections between principals.

In the WebLogic Collaborate environment, authorization protects who has access to the available resources. Permission to access WebLogic Collaborate resources is assigned through access control lists and roles. The following figure illustrates the WebLogic Collaborate security model.

Figure 4-1 WebLogic Collaborate Security Model

 

For information about the WebLogic Server security features used by WebLogic Collaborate, see "Configuring the SSL Protocol" and "Defining ACLs" in "Managing Security" in the BEA WebLogic Server Administration Guide.

 

---

Security Terminology

The following sections describes the security terminology used by the WebLogic Collaborate security model:

• Transport Servlet

• Resources

• Principals, Users, and Groups

• Authorization

• Digital Certificates

• Certificate Authority

• SSL Protocol

• Authentication

Transport Servlet

A transport servlet is the entry point into a WebLogic Collaborate system for communication between:

• The c-hub and c-enablers that use XOCP

• The c-hub and non-XOCP clients

A transport servlet is dynamically registered in the WebLogic Server environment for each c-space and c-enabler.

Resources

Resources are objects in the WebLogic Collaborate environment. Some of the WebLogic Collaborate resources are:

• Transport servlets on the c-hub and c-enabler

• C-Hub Administration Console

• C-Enabler Administration Console

• JDBC connection pool

• Conversations

Principals, Users, and Groups

Principals are objects that need access to the WebLogic Collaborate environment and resources. WebLogic Collaborate principals include:

• Trading partners

• Human users—c-hub administrators and c-enabler administrators

• C-hub servers

Principals are granted access to the WebLogic Collaborate environment and resources through authentication and authorization mechanisms. Principals in WebLogic Collaborate map to WebLogic Server users.

If the c-hub or c-enabler can prove the identity of the WebLogic Server user, the c-hub or c-enabler associates the user with a thread that executes code on behalf of the user. Before the thread begins executing code, the c-hub or c-enabler checks pertinent access control lists (ACLs) to make sure the WebLogic Server user has the proper permission to continue.

WebLogic Collaborate can have the following types of WebLogic Server users:

• Trading partner users on the c-hub

• A c-hub user on the c-enabler

• A c-hub administrator user

• A c-enabler administrator user

The following figure illustrates the relationship between principals in WebLogic Collaborate and WebLogic Server users.

Figure 4-2 WebLogic Collaborate Principals

 



 

Groups are sets of WebLogic Server users. Groups provide an efficient way to manage large numbers of users because an administrator can specify permissions for an entire group at one time.

Authorization

Authorization is the process of allowing a WebLogic Collaborate principal access to particular WebLogic Collaborate resources. The authorization model in WebLogic Collaborate is based on an ACL and permission mechanism and role-based authorization control.

The following sections describe how authorization is used in the WebLogic Collaborate environment:

• Access Control Lists

• Transport Servlet, JDBC Connection Pool, and Administration Consoles

• Conversations

Access Control Lists

ACLs are data structures with multiple entries that guard access to WebLogic Collaborate resources. An ACL grants permission on a resource, or class of resources, to a list of users and groups. An ACL includes a list of AclEntries, each with the set of permissions for a particular user or group.

Permissions represent privileges required for accessing a resource and are related to the resource they protect. The exact permissions available depend on the type of resource the ACL protects. For example, there are permissions to send and receive files, delete files, read and write files, and load servlets.

You define ACLs for the following WebLogic Collaborate resources:

• The transport servlet

• The C-Enabler Administration Console

• The C-Hub Administration Console

• The JDBC connection pool

Transport Servlet, JDBC Connection Pool, and Administration Consoles

Authorization allows a user to access WebLogic Collaborate resources based on ACLs for the resources. The WebLogic Collaborate resources that require authorization are:

• Transport servlets

• C-Hub Administration Console

• C-Enabler Administration Console

• JDBC connection pool

WebLogic Collaborate can have the following access control policies:

• Trading partner users need access to the transport servlet on the c-hub and the JDBC connection pool.

• The c-hub user on the c-enabler needs access to the transport servlet on the c-enabler for the purpose of sending messages to the c-enabler.

• The c-hub administrator users need access to the C-Hub Administration Console. This access is achieved by configuring custom ACLs for the C-Hub Administration Console.

• The c-enabler administrator users need access to the C-Enabler Administration Console. This access is achieved by configuring custom ACLs for the C-Enabler Administration Console.

Conversations

WebLogic Collaborate conversations use a role-based authorization whereby a trading partner is given access to a conversation based on a role that is defined in subscriptions for that trading partner.

A particular trading partner in a c-space can send and receive certain types of documents as defined by the trading partner's role in a specific conversation. Authorization to send a document in a conversation is based on the subscriptions of the trading partner. Subscription information identifies:

• Trading partner

• Name of the conversation

• Roles for all trading partners in the conversation

• Document types

The conversation definition identifies:

• Conversation name

• Conversation version

• Allowed roles

• Allowed document types

The c-hub compares the information in the subscription to the conversation definition. Based on this comparison, the c-hub allows a trading partner to participate in conversations by sending and receiving messages.

For example, suppose trading partner x has a subscription to a conversation named aConv with the role of buyer. The aConv conversation has two roles buyer and seller. The aConv conversation specifies that the buyer role has one incoming document (reply.dtd) and one outgoing document (request.dtd).

When trading partner x joins the c-space, it creates a conversation handler for the aConv conversation with a role of buyer. The c-hub prevents trading partner x from participating with a role of seller. In addition, the c-hub permits trading partner x to send only documents of type request.dtd.

To configure the authorization of a trading partner in a c-space, define the following information:

• Trading partner subscriptions, including the name and version of the conversation and the role of the trading partner in the conversation.

• Conversation definitions including the conversation name, the conversation version, conversation roles, and input and output document types for these roles.

You can use the C-Hub Administration Console to define this information as described in Setting Up Conversations, and in Step 4. Assign Subscriptions (Roles and Conversations) to a Trading Partner. in Working with C-Spaces. You can also use the Bulk Loader to import this information into the repository as described in Importing Data into the Repository in Working with the Bulk Loader.

Digital Certificates

Digital certificates are electronic documents used to uniquely identify principals and objects over networks such as the Internet. A digital certificate securely binds the identity of a user or object, as verified by a trusted third party known as a certificate authority, to a particular public key. The combination of the public key and the private key provides a unique identity to the owner of the digital certificate.

Digital certificates allow verification of the claim that a specific public key does in fact belong to a specific user or entity. A recipient of a digital certificate can use the public key contained in the digital certificate to verify that a digital signature was created with the corresponding private key. If such verification is successful, this chain of reasoning provides assurance that the corresponding private key is held by the subject named in the digital certificate, and that the digital signature was created by that particular subject.

A digital certificate typically includes a variety of information, such as:

• The name of the subject (holder, owner) and other identification information required to uniquely identify the subject, such as a URL or an email address.

• The subject's public key.

• The name of the certificate authority that issued the digital certificate.

• A serial number.

• The validity period (or lifetime) of the digital certificate (defined by a start date and an end date).

The most widely accepted format for digital certificates is defined by the ITU-T X.509 international standard. Thus, digital certificates can be read or written by any application complying with the X.509 standard. The public key infrastructure (PKI) in WebLogic Server recognizes digital certificates that comply with X.509 version 3, or X.509v3.

Certificate Authority

Digital certificates are issued by a certificate authority. Any trusted third-party organization or company that is willing to vouch for the identities of those to whom it issues digital certificates and public keys can be a certificate authority. When a certificate authority creates a digital certificate, the certificate authority signs it with its private key, to ensure the detection of tampering. The certificate authority then returns the signed digital certificate to the requesting subject.

The subject can verify the signature of the issuing certificate authority by using the public key of the certificate authority. The certificate authority makes its public key available by providing a digital certificate issued from a higher-level certificate authority attesting to the validity of the public key of the lower-level certificate authority. This hierarchy of certificate authorities is terminated by a self-signed digital certificate known as the root certificate.

The recipient of an encrypted message can develop trust in the private key of a certificate authority recursively, if the recipient has a digital certificate containing the public key of the certificate authority signed by a superior certificate authority whom the recipient already trusts. In this sense, a digital certificate is a stepping stone in digital trust. Ultimately, it is necessary to trust only the public keys of a small number of top-level certificate authorities. Through a chain of digital certificates, trust in a large number of users' digital signatures can be established.

Thus, digital signatures establish the identities of communicating entities, but a digital signature can be trusted only to the extent that the public key for verifying the digital signature can be trusted.

SSL Protocol

The SSL protocol provides secure connections by enabling two applications connecting over a network connection to authenticate the other's identity and by encrypting the data exchanged between the applications. An SSL connection begins with a handshake during which the applications exchange digital certificates, agree on the encryption algorithms to use, and generate encryption keys used for the remainder of the session.

The SSL protocol provides the following security features:

• Server authentication—The server uses its digital certificate, issued by a trusted certificate authority, to authenticate itself to clients.

• Client authentication—Optionally, clients might be required to authenticate themselves to the server by providing their own digital certificates. This type of authentication is also referred to as mutual authentication. The authentication model in WebLogic Collaborate uses mutual authentication.

• Data privacy—All client requests and server responses are encrypted to maintain the confidentiality of the data exchanged over the network.

• Data integrity—Data that flows between a client and server is protected from a third party's tampering.

The SSL protocol is used to implement link-level encryption of messages sent between the c-hub and the c-enabler.

Administrators use a Web browser to access the C-Hub and C-Enabler Administration Consoles. You can use the Hypertext Transfer Protocol with SSL (HTTPS) to secure this type of network communication.

Authentication

Authentication is the process by which WebLogic Collaborate establishes the identity of a principal. Digital certificates with mutual authentication over SSL or HTTPS are used between the c-enabler (on behalf of the trading partner) and the c-hub. Both the c-hub and the c-enabler examine and validate the digital certificates against defined security information. Human users use a username/password combination to authenticate themselves to the WebLogic Collaborate environment.

 

---

Configuring the SSL Protocol and Mutual Authentication

To configure the c-hub to use the SSL protocol and mutual authentication, perform the following steps:

1. Obtain a digital certificate for the c-hub. WebLogic Collaborate ships four digital certificates and private keys (one for the c-hub, one for the c-enabler, and two for 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.

   For more information on Secure Socket Layers (SSL), see "Managing Security" in the BEA WebLogic Server Administration Guide.

2. In the WebLogic Administration Console, specify the following security settings:

   • SSL Port

   • Client root CA

   • Hub Certificate file

   • Hub Private Key file

   • Certificate for root CA

     The following listing is an example of the modified config.xml file, showing the changed SSL protocol and related authentication settings.

     Listing 4-1 Example from config.xml of the SSL Protocol and Mutual Authentication for the C-hub

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

     In the preceding listing:

   • SSL port specifies the dedicated port on which the c-hub listens for SSL connections. The config.xml file for the c-hub 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. Trading partners are required to present digital certificates issued by this certificate authority. The config.xml file for the c-hub has the client root CA set to CA_cert.pem.

   • SSL port specifies the dedicated port on which the c-enabler listens for SSL connections. The config.xml file for the c-enabler has the SSL port set to 7502.

   • Hub Certificate file specifies the name of the digital certificate for the c-hub. The config.xml file for the c-hub has the hub certificate file set to hub_cert.pem.

   • Hub Private Key specifies the name of the private key for the c-hub. The config.xml file for the c-hub has the hub private key file set to hub_key.pem.

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

 

---

Defining Users and Groups

To control access to your web applications, you first need to define identities for users on the c-hub. Define the following types of users:

• Users that correspond to trading partners. These users must also be specified in the repository for each trading partner.

• A user for the c-hub administrator.

For complete information about defining users and groups, see "Defining Users" and "Defining Groups" in "Managing Security" in the BEA WebLogic Server Administration Guide.

 

---

Defining Access Control Lists

The Access Control List (ACL) for a resource determines whether a user or group can access a resource in WebLogic Collaborate. To define ACLs, you first create an ACL for a resource, next specify the permission for the resource, and then grant the permission to a specified set of users and groups. Each WebLogic Collaborate resource has one or more permissions for the resource that can be granted.

On the c-hub you need to define the following ACLs:

• On the transport servlet for trading partner users; the transport servlet has only an execute permission.

• On the JDBC connection pool for trading partner users; the JDBC connection pool has reserve, reset, and shrink permissions.

• On the C-Hub Administration Console for the c-hub administrator user; the C-Hub Administration Console has hubconfig and hubmonitor permissions.

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

The following listing includes properties that define the c-hub ACLs. Note that the code example assumes the name of the transport servlet on the c-hub is cspace1.

Listing 4-2 C-Hub ACLs

#ACL for Transport Servlet
acl.execute.weblogic.servlet.Hub/SecurityCSpace=eng
#ACL for JDBC Connection Pool
acl.reserve.weblogic.jdbc.connectionPool.wlcPool=everyone
acl.reset.weblogic.jdbc.connectionPool.wlcPool=everyone
acl.shrink.weblogic.jdbc.connectionPool.wlcPool=everyone

#ACL for Administration Console
acl.hubconfig.WLCAdmin=admin
acl.hubmonitor.WLCAdmin=tp1

You can substitute groups for users in the ACLs. For more information on access control lists, see Defining ACLs in "Managing Security" in the BEA WebLogic Server Administration Guide.

Specifying Information in the Repository

The c-hub repository contains security information about the c-hub and the trading partners that access the c-hub. Repository information can be either configured through the C-Hub Administration Console or specified in a repository data file and then imported into the repository using the Bulk Loader.

Define the following security information for the c-hub:

• Certificate field name

• Server certificate field name

• Certificate location

• Private key location

Define the following security information for each trading partner that accesses the c-hub:

• Certificate field value

• WebLogic Server user name

• List of server certificate field values

For information about the C-Hub Administration Console, see Creating a Trading Partner and Defining Server-Side Security Values for a Trading Partner in Working with Trading Partners. For information about the Bulk Loader, see Importing Data into the Repository in Working with the Bulk Loader.

The following listing contains an example of the security information you need to define for the c-hub and trading partners in the repository. For more information, see the readme.htm file in the WLC_HOME/examples/security directory.

Listing 4-3 Security Information for the Repository.

<c-hub
	...
	certificate-location="<WLC_HOME>\examples\security
	        \certificates\hub_cert.pem"
	private-key-location="<WLC_HOME>\examples\security
	        \certificates\hub_key.pem"
	certificate-field-name="email"
	server-certificate-field-name="email"
	...
/>

<trading-partner
	name="SecurityPartner1"
	email="[e-mail]"
	user-name="securityPartner1"
	certificate-field-value="e63914a52929a16dce3f6a5cb4bf67a2"
	<server-certificate
	        certificate-field-value="[e-mail]"/>
</trading-partner>

<trading-partner
	name="SecurityPartner2"
	email="[e-mail]"
	user-name="securityPartner2"
	certificate-field-value="fb8b5a3a39d71c49817fc55384798707"
	        <server-certificate
	certificate-field-value="[e-mail]"/>
</trading-partner>

 

---

Working with the WLCCertAuthenticator Class

The following sections describe how to work with the WLCCertAuthenticator class:

• Specifying the WLCCertAuthenticator Class

• Customizing the WLCCertAuthenticator Class

Specifying the WLCCertAuthenticator Class

WebLogic Collaborate contains an implementation of the weblogic.security.acl.CertAuthenticator class. On the c-hub, CertAuthenticator maps digital certificates from trading partners to their corresponding WebLogic Server users. On the c-enabler, CertAuthenticator maps the digital certificates from the c-hub to a corresponding WebLogic Server user.

Use the WebLogic Server Administration Console to configure the WebLogic Collaborate implementation of the certificate authority (com.bea.b2b.security.WLCCertAuthenticator) of the weblogic.security.acl.CertAuthenticator class. The following listing shows the property that defines the WebLogic Collaborate implementation of the weblogic.security.acl.CertAuthenticator class.

Listing 4-4 WebLogic WLCCertAuthenticator Class

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

Customizing the WLCCertAuthenticator Class

The WLCCertAuthenticator is an implementation of the WebLogic Server CertAuthenticator class. The default implementation of the WLCCertAuthenticator class validates a trading partner and maps the digital certificate of the trading partner to the corresponding trading partner defined on the c-hub. You may want to extend this functionality to use mutual authentication for users other than trading partners. For example, you may want to modify the class to map a Web browser or Java client to a user on the c-hub.

The WLCCertAuthenticator class is called after an SSL connection has been established. The class can extract data from a digital certificate to determine the user which corresponds to the digital certificate.

For a code example of customizing the WLCCertAuthenticator class, see the Javadoc for the WLCCertAuthenticator class.

 

---

Configuring WebLogic Collaborate to Use an HTTP Proxy Server

If you are using WebLogic Collaborate in the security-sensitive environment, you may want to use WebLogic Collaborate behind a proxy server. A proxy server allows the c-hub and c-enabler to communicate across intranets or the Internet without compromising security. A proxy server is used to:

• Hide the local network addresses of the WebLogic Servers that host the c-hub or c-enabler from external hackers

• Restrict access to the external network

• Monitor external network access to the WebLogic Servers that host the c-hub or c-enabler

When proxy servers are configured on the local network WebLogic Collaborate uses, network traffic (SSL and HTTP) is tunneled through the proxy server to the external network. The following figure illustrates how a proxy server might be used in the WebLogic Collaborate environment.

Figure 4-3 Proxy Server

 

To configure a proxy server on the c-hub side of a network, define a host name and port number for the proxy server in the c-hub repository.

To configure a proxy server on the c-enabler side of a network, define a host and port for the proxy server in the c-enabler configuration file. For more information, see the BEA WebLogic Collaborate C-Enabler Administration Guide.

You need to add permissions to read and write the ssl.proxyHost and ssl.proxyPort system properties for the WebLogic Server. These system properties are stored in the weblogic.policy file which is located in the directory where you installed WebLogic Server. Add the following lines to the grant section of the weblogic.policy file.

permission java.util.PropertyPermission "ssl.proxyHost", "read, write";
permission java.util.PropertyPermission "ssl.proxyPort", "read, write";