Managing Security

 

The following sections describe how to implement security in WebLogic Server:

• Steps for Configuring Security

• Changing the System Password

• Specifying a Security Realm

• Defining Users

• Defining Groups

• Defining ACLs

• Configuring the SSL Protocol

• Configuring Mutual Authentication

• Configuring RMI over IIOP with SSL

• Protecting Passwords

• Installing an Audit Provider

• Installing a Connection Filter

• Setting Up the Java Security Manager

• Modifying the weblogic.policy File for Third Party or User-Written Classes

• Using the Recording Security Manager Utility

• Configuring Security Context Propagation

• SSL Certificate Validation

 

---

Steps for Configuring Security

Implementing security in a WebLogic Server deployment largely consists of configuring attributes that define the security policy for that deployment. WebLogic Server provides an Administration Console to help you define the security policy for your deployment. Using the Administration Console, you specify security-specific values for the following elements of your deployment:

• Security realms

• Users and Groups

• Access Control Lists (ACLs) and permissions for WebLogic Server resources

• SSL protocol

• Mutual authentication

• Host Name verification

• Audit providers

• Custom filters

• Security context propagation

Because security features are closely related, it is difficult to determine where to start when configuring security. In fact, defining security for your WebLogic Server deployment may be an iterative process. Although more than one sequence of steps may work, BEA Systems recommends the following procedure:

1. Change the password of the system User to protect your WebLogic Server deployment. See Changing the System Password.

2. Specify a security realm. By default, WebLogic Server is installed with the File realm in place. However, you may prefer an alternate security realm or a custom security realm. See Specifying a Security Realm.

3. Define Users for the security realm. You can organize Users further by implementing Groups in the security realm. See Defining Users.

4. Define ACLs and permissions for the resources in your WebLogic Server deployment. See Defining ACLs.

5. Protect the network connection between clients and WebLogic Server by implementing the SSL protocol. When SSL is implemented, WebLogic Server uses its digital certificate, issued by a trusted certificate authority, to authenticate clients. This step is optional but BEA recommends it. See Configuring the SSL Protocol.

6. Further protect your WebLogic Server deployment by implementing mutual authentication. When mutual authentication is implemented, WebLogic Server must authenticate itself to the client and then the client in turn, must authenticate itself to WebLogic Server. Again, this step is an optional but BEA recommends it. See Configuring Mutual Authentication.

For a complete description of WebLogic Server security features, see Introduction to WebLogic Security and Security Fundamentals.

Note: All configuration steps in this topic are based on the use of the Administration Console.

For information about assigning security roles to WebLogic EJBs, see WebLogic Server 6.1 Deployment Properties.

For information about security in WebLogic web applications, see Assembling and Configuring Web Applications.

 

---

Changing the System Password

During installation you specify a password for the system User. The specified password is associated with the system User in WebLogic Server and is stored in the fileRealm.properties file in the \wlserver6.1\config\domain directory where domain is the name specified as the WebLogic Administration domain name during installation. The specified password corresponds to the Administration Server for the domain and all the Managed Servers associated with that Administration Server.

Note: The system User is the only user account under which WebLogic Server can be started.

The password of the system User is encrypted and is further protected when WebLogic Server applies a hash to it. To improve security, BEA recommends frequently changing the system password that was set during installation. Each WebLogic Server deployment must have a unique password.

To change the system password, do the following:

1. In the Administration Console under the Security node, click Users to open the Users.

2. Under Change a User's Password, enter system in the Name attribute field.

3. Enter password you specified when installing WebLogic Server in the Old Password attribute field.

4. Enter a new password in the New Password attribute field.

5. Enter the new password again in the Confirm the Password attribute field.

6. Click Change.

7. Click the Changes You Have Made Must Be Saved to the Realm Implementation link.

8. Submit the change.

9. Reboot WebLogic Server.

When you use an Administration Server and Managed Servers in a domain, the Managed Server must always use the password for the Administration Server in the domain. Always change the password for the Administration Server through the Administration Console. After changing the password, restart all servers in the domain. The process is as follows:

1. Shutdown all the Managed Servers in the domain.

2. Change the system password on the Administration Server following the steps in this section.

3. Shutdown the Administration Server.

4. Reboot the Administration Server using the new system password.

5. Login into the Administration Console using the new system password.

6. Restart all the Managed Servers in the domain.

Maintaining the secrecy of WebLogic passwords is critical to keeping your WebLogic Server deployment and data secure. For your protection, BEA recommends keeping the password of WebLogic Server secret.

 

---

Specifying a Security Realm

This section describes configuring a security realm for your WebLogic Server deployment. For an introduction of security realms and how they are used in WebLogic Server, see Security Realms in Programming WebLogic Security. The following sections describe specifying a security realm:

• Configuring the File Realm

• Configuring the Caching Realm

• Configuring the LDAP Security Realm

• Configuring the Windows NT Security Realm

• Configuring the UNIX Security Realm

• Configuring the RDBMS Security Realm

• Installing a Custom Security Realm

• Migrating Security Realms

Configuring the File Realm

By default WebLogic Server is installed with the File realm in place. Before using the File realm, you need to define several attributes that govern the use of the File realm. You set these attributes on the Filerealm tab in the Security window of the Administration Console.

The following table describes each attribute on the Filerealm tab.

Table 14-1 File Realm Attributes

Attribute	Description
Caching Realm	Name of the Caching realm being used. When using the File realm, this attribute should be set to None. If you are using an alternate or custom security realm, set this attribute to the name of the Caching realm to be used. A list of configured Caching realms appears on the pull-down menu.
Max Users	Maximum number of Users to be used the File realm. The File realm is intended to be used with 10,000 or fewer Users. The minimum value for this attribute is 1 and the maximum value is 10,000. The default is 1,000.
Max Groups	Maximum number of Groups to be used with the File realm. The minimum value for this attribute is 1 and the maximum value is 10,000. The default is 1,000.
Max ACLs	Maximum number of ACLs to be used with the File realm. The minimum value for this attribute is 1 and the maximum value is 10,000. The default is 1,000.

 

Use the Manage Caching Realm button to clear the user, group, and ACL caches.

Caution: If the fileRealm.properties file becomes corrupted or is destroyed, you must reconfigure the security information for WebLogic Server. WebLogic Server cannot boot without a fileRealm.properties file.

The fileRealm.properties file contains default ACLs used to boot WebLogic Server. Even if you write a custom security realm, you still need a fileRealm.properties file to boot WebLogic Server since the custom security realm is not initially called during the start-up sequence.

Therefore, BEA recommends that you take the following steps:

Make a backup copy of the fileRealm.properties file and put it in a secure place.

Set the permissions on the fileRealm.properties file such that the administrator of the WebLogic Server deployment has write and read privileges and no other users have any privileges.

Note: Also make a backup copy of the SerializedSystemIni.dat file for the File realm. For more information about the SerializedSystemIni.dat file, see Protecting Passwords.

If, instead of the File realm, you want to use one of the alternate security realms provided by WebLogic Server or a custom security realm, set the attributes for the desired realm and reboot WebLogic Server.

Caution: If you use one of the alternate security realms, you must configure and enable the Caching realm; otherwise the alternate security realm will not work.

For more information about security realms in WebLogic Server, see Security Realms.

Configuring the Caching Realm

The Caching realm works with the File realm, alternate security realms, or custom security realms to fulfill client requests with the proper authentication and authorization. The Caching realm stores the results of both successful and unsuccessful realm lookups. It manages separate caches for Users, Groups, permissions, ACLs, and authentication requests. The Caching realm improves the performance of WebLogic Server by caching lookups, thereby reducing the number of calls into other security realms. For more information about security realms in WebLogic Server, see Security Realms.

The Caching realm is installed automatically when you install WebLogic Server: the cache is set up to delegate to the other security realms however caching is not enabled. You have to enable caching through the Administration Console.

Caution: If you use one of the alternate security realms, you must configure and enable the Caching realm; otherwise the alternate security realm will not work.

When you enable caching, the Caching realm saves the results of a realm lookup in its cache. Lookup results remain in the cache until either the specified number of seconds defined for the time-to-live (TTL) attributes has passed (the lookup result has expired) or the cache has filled. When the cache is full, new lookup results replace the oldest cached results. The TTL attributes determine how long a cached object is valid. The higher you set these attributes, the less often the Caching realm calls the secondary security realm. Reducing the frequency of such calls improves the performance. The trade-off is that changes to the underlying security realm are not recognized until the cached object expires.

Note: When you obtain an object from a security realm, the object reflects a snapshot of the object. To update the object, call the object's get() method again. For example, the membership of a Group is set when the Group is retrieved from the security realm with a call to the getGroup() method. To update the members of the Group, you must call the getGroup() method again.

By default, the Caching realm operates on the assumption that the alternate security realm is case-sensitive. In a case-sensitive security realm, the owners of usernames bill and Bill, for example are treated as two distinct Users. The Windows NT Security realm and the LDAP Security realm are examples of security realms that are not case-sensitive. If you are using a security realm that is not case-sensitive, you must disable the CacheCaseSensitive attribute. When this attribute is set, the Caching realm converts usernames to lowercase so that WebLogic Server gives correct results for the security realm when it performs case-sensitive comparisons. When defining or referencing Users or Groups in a case-sensitive security realm, type usernames in lowercase.

To configure the Caching realm:

1. Go to the Security—>Caching Realms node in the left pane of the Administration Console.

2. In the right pane of the Administration Console, click the Configure a New Caching Realm link.

3. Define the attributes on the General tab in the Caching Realm Configuration window.

   The following table describes the attributes you set on the General tab.

   Table 14-2 Caching Realm Attributes on the General Tab

   Attribute	Description
   Name	Displays the active security realm as defined in the Administration Console. This attribute can not be changed.
   Basic Realm	Name of the class for the alternate security realm or custom security realm to be used with the Caching realm. The names of the configured realms appear on the pull-down menu.
   Case Sensitive Cache	Defines whether the specified security realm is case-sensitive. By default, this attribute is enabled: the realm is case-sensitive. To use a realm that is not case-sensitive (such as the Windows NT and LDAP security realms), you must disable this attribute.

   
    

4. Click Create.

5. Configure and enable the ACL cache by defining values for the attributes shown on the ACL tab in the Caching Realm Configuration window.

   The following table describes the attributes you set on the ACL tab.

   Table 14-3 ACL Cache Attributes

   Attribute	Description
   Enable Cache	Option for enabling the ACL cache.
   ACL Cache Size	Maximum number of ACL lookups to cache. This attribute should be a prime number for best lookup performance. The default is 211.
   ACL Cache Positive TTL	Number of seconds to retain the results of a successful lookup. The default is 60 seconds.
   ACL Cache Negative TTL	Number of seconds to retain the results of an unsuccessful lookup. The default is 10 seconds.

   
    

6. To save your changes, click the Apply button.

7. To enable and configure the Authentication cache, define values for the attributes shown on the Authentication tab in the Caching Realm Configuration window.

   The following table describes the attributes you set on the Authentication tab.

   Table 14-4 Authentication Cache Attributes

   Attribute	Description
   Enable Authentication Cache	Option for enabling the Authentication cache.
   Authentication Cache Size	Maximum number of Authenticate requests to cache. This attribute should be a prime number for best lookup performance. The default is 211.
   Authentication Cache TTLPositive	Number of seconds to retain the results of a successful lookup. The default is 60 seconds.
   Authentication Cache TTLNegative	Number of seconds to retain the results of an unsuccessful lookup. The default is 10 seconds.

   
    

8. To save your changes, click the Apply button.

9. To enable and configure the Group cache, define values for the attributes shown on the Groups tab in the Caching Realm Configuration window.

   The following table describes the attributes you set on the Group tab.

   Table 14-5 Group Cache Attributes

   Attribute	Description
   Enable Group Cache	Option for enabling the Group cache.
   Group Cache Size	Maximum number of Group lookups to cache. This attribute should be a prime number for best lookup performance. The default is 211.
   Group Cache TTLPositive	Number of seconds to retain the results of a successful lookup. The default is 60 seconds.
   Group Cache TTLNegative	Number of seconds to retain the results of an unsuccessful lookup. The default is 10 seconds.
   Group Membership Cache TTL	Number of seconds to store the members of a group before updating it. The default is 300 seconds.

   
    

10. To save your changes, click the Apply button.

11. To enable and configure the User cache, define values for the attributes shown on the User tab in the Caching Realm Configuration window.

    The following table describes the attributes you set on the User tab.

    Table 14-6 User Cache Attributes

    Attribute	Description
    Enable User Cache	Option for enabling the User cache.
    User Cache Size	Maximum number of User lookups to cache. This attribute should be a prime number for best lookup performance. The default is 211.
    User Cache TTLPositive	Number of seconds to retain the results of a successful lookup. The default is 60 seconds.
    User Cache TTLNegative	Number of seconds to retain the results of an unsuccessful lookup. The default is 10 seconds.

    
     

12. To save your changes, click the Apply button.

13. To enable and configure the Permission cache, define values for the attribute shown on the Permission tab in the Caching Realm Configuration window. T

    The following table describes each attribute on the Permission tab.

    Table 14-7 Permission Cache Attributes

    Attribute	Description
    Enable Permission Cache	Option for enabling the Permission cache.
    Permission Cache Size	Maximum number of Permission lookups to cache. This attribute should be a prime number for best lookup performance. The default is 211.
    Permission Cache TTLPositive	Number of seconds to retain the results of a successful lookup. The default is 60 seconds.
    Permission Cache TTLNegative	Number of seconds to retain the results of an unsuccessful lookup. The default is 10 seconds.

    
     

14. To save your changes, click the Apply button.

15. When you finish defining attributes for the Caching realm, reboot WebLogic Server.

Configuring the LDAP Security Realm

The LDAP security realm provides authentication through a Lightweight Directory Access Protocol (LDAP) server. This server allows you to manage all the users for your organization in one place: the LDAP directory. The LDAP security realm supports Open LDAP, Netscape iPlanet, Microsoft Site Server, and Novell NDS.

In this release of WebLogic Server, you can choose between two versions of the LDAP security realm:

• LDAP realm V1—The LDAP security realm packaged in previous releases of WebLogic Server. With the exception of Microsoft Site Server, the LDAP security realm V1 works with all the supported LDAP servers and is provided for BEA customers that are currently using the LDAP security realm in an older release of WebLogic Server. However, the LDAP realm V1 is deprecated in this release and BEA recommends users upgrade to the LDAP realm V2.

• LPAP realm V2—An updated LDAP security realm with improved performance and configurability. This is the same LDAP security realm provided in WebLogic Server 6.0 Service Pack 1.0. LDAP realm V2 does not support getUsers() or getGroups() due to the fact that allocating memory to fulfill those requests can cause a denial of service vulernability. If you want to use those functions, BEA recommends using LDAP realm V1 When running Windows 2000, BEA recommends using LDAP realm V2 to authenticate against the Windows 2000 User and Group store.

Note: When using LDAP realm V1 you can view Users and members of a Group stored in the LDAP directory server through the Administration Console. However, when using LDAP realm V2, you can only view the Groups stored in the LDAP directory server through the Administration Console.

You need to use the administration tools available with the LDAP server to manage Users and Groups (for example, adding or deleting Users or Groups or adding members to Groups). If you make a change in the LDAP directory store, reset the User cache and the Group cache to immediately view your changes in the Administration Console.

The following suggestions are ways to improve the performance of the LDAP Security realm:

• Use the filters in the ldaprealm.props file to obtain smaller and more specific results sets from the LDAP server (supported for LDAP realm V2 only).

• Have the LDAP server index all of the attributes that you use as search keys in your LDAP realm search filters. Not indexing the attributes could cause linear search performance.

• Use the Caching realm carefully. Changes in the LDAP server's information will not be propagated to the LDAP Security realm until the cache is cleared.

Configuring the LDAP security realm involves defining attributes that enable the LDAP Security realm in WebLogic Server to communicate with the LDAP server and attributes that describe how Users and Groups are stored in the LDAP directory. The LDAP tree and schema is different for every LDAP server. Therefore, the LDAP realm V2 provides a set of templates that define default attributes for the supported LDAP servers.

Restrictions When Using the LDAP Security Realm

The LDAP security realm has the following restrictions:

• When the LDAP server in Microsoft Site Server is installed and the root of the LDAP directory is created, a number of organizational units are created by default. Under Groups there is a default organization unit called NTGroups with a default Group named Administrators, which is empty. By default, WebLogic Server also provides a Group called Administrators that contains a member System which is the User under which WebLogic Server is started. If you use the defaults in Microsoft Site Server and start creating your own Groups under the default organizational unit, WebLogic Server will not start. In order to start WebLogic Server with the LDAP security realm, you need to create your own unique organizational unit in the LDAP directory and create Groups for your WebLogic Server deployment under that organizational unit.

• If you have two Groups within the LDAP directory with the same name, WebLogic Server cannot properly authenticate the Users in the second Group that it locates. The LDAP security realm uses the Group's distinguished name (DN) to locate Groups in the LDAP directory. If you create more than one group with the same name, WebLogic Server only authenticates the Users in the first Group it locates. You must use unique Group names when using the LDAP security realm.

• The LDAP realm V2 does not provide the following functionality provided in LDAP realm V1:

  • Listing all Users

  • Listing the members of a Group

  • The authProtocol and userAuthentication mechanisms have been removed. You need to use the JNDI bind mechanism to pass security credentials to the LDAP server.

• The LDAP realm V2 has issues with the Open LDAP Server when running the getGroups() method for large numbers of groups (more than 300). This problem is due to caching bugs in Open LDAP.

Locating Users and Groups in the LDAP Directory

The LDAP security realm needs to know where the Users and Groups are stored in the LDAP directory used with the security realm. This is done by specifying the distinguished names (DNs) of the LDAP directories that contain the Users and Groups.

In LDAP, a DN starts with a leaf node and goes to the root node. For example:

			root
			  |
			  |
			  |
			o=acme.com
			  |
			  |
			  |
			ou=Groups

The DN for this branch would be specified as ou=Groups, o=acme.com.

In LDAP realm V1, you specify DNs via the GroupDN and UserDN attributes when configuring the security realm. However, you must reverse the DNs. For example, the sample DN would be specified as groupDN="o=acme.com, ou=Groups".

In LDAP realm V2, you specify DNs by adding user.dn and group.dn properties to the Configuration attribute of the CustomRealm MBean. Unlike LDAP realm V1, you do not have to reverse the DN. For example, the user.dn and group.dn properties for a LDAP realm V2 are specified as follows:

ConfigurationData="..., group.dn=ou=Groups, o=acme.com, ..."

A common error when switching between the LDAP realm V1 and LDAP realm V2 is copying over the reverse DNs thus causing the LDAP security realm to stop working. Check your DN specifications when migrating from LDAP realm V1 to LDAP realm V2.

Configuring an LDAP Realm V1

To use the LDAP Security realm V1 instead of the File realm:

1. Go to the Security—>Realms node in the left pane of the Administration Console.

2. In the right pane of the Administration Console, click the Configure a New LDAP Realm V1 link.

   The name of the class that implements the LDAP Security realm is displayed.

3. Click Create.

4. To enable communication between the LDAP server and WebLogic Server define values for the attributes shown on the LDAP Realm V1 tab in the LDAP Realm Create window.

   The following table describes the attributes you set on the LDAP Realm V1 tab.

   Table 14-8 LDAP Security Realm Attributes on the LDAP Tab

   Attribute	Description
   LDAPURL	Location of the LDAP server. Change the URL to the name of the computer on which the LDAP server is running and the number of the port at which it is listening. For example: ldap://ldapserver:385. If you want WebLogic Server to connect to the LDAP server using the SSL protocol, use the LDAP server's SSL port in the URL.
   Principal	Distinguished name (DN) of the LDAP User used by WebLogic Server to connect to the LDAP server. This user must be able to list LDAP Users and Groups.
   Credential	Password that authenticates the LDAP User defined in the Principal attribute.
   Enable SSL	Option for enabling the SSL protocol to protect communications between the LDAP server and WebLogic Server. Keep in mind the following guidelines: Disable this attribute if the LDAP server is not configured to use the SSL protocol. If you set the UserAuthentication attribute on the LDAP Users tab to external, this attribute must be enabled.
   AuthProtocol	The type of authentication used to authenticate the LDAP server. Set this attribute to one of the following values: None for no authentication Simple for password authentication CRAM-MD5 for certificate authentication Netscape iPlanet supports CRAM-MD5. Microsoft Site Server, Netscape iPlanet, and OpenLDAP and Novell NDS support Simple.

   
    

5. To save your changes, click the Apply button.

6. To specify how Users are stored in the LDAP directory define the attributes shown on the Users tab in the LDAP Realm Create window.

   The following table describes the attributes you set on the Users tab.

   Table 14-9 LDAP Security Realm Attributes on the Users Tab

   Attribute	Description
   User Authentication	Determines the method for authenticating Users. Set this attribute to one of the following values: Bind specifies that the LDAP security realm retrieves user data, including the password for the LDAP server, and checks the password in WebLogic Server. External specifies that the LDAP security realm authenticates a User by attempting to bind to the LDAP server with the username and password supplied by the WebLogic Server client. If you choose the External setting, you must also use the SSL protocol. Local specifies that the LDAP security realm authenticates a User by looking up the UserPassword property in the LDAP directory and checking it against the passwords in WebLogic Server. If you are using Netscape iPlanet, set this attribute to Bind.
   User Password Attribute	If the User Authentication attribute is set to Local, this attribute is used to find out what LDAP property contains the passwords for the LDAP users.
   User DN	A list of attributes and their values that, when combined with the attributes in the User Name Attribute attribute, uniquely identifies an LDAP User.
   User Name Attribute	The login name of the LDAP User. The value of this attribute can be the common name of an LDAP User but usually it is an abbreviated string, such as the common name.

   
    

7. To save your changes, click the Apply button.

8. To specify how Groups are stored in the LDAP directory, assign values to the attributes shown on the Groups tab in the LDAP Realm Create window.

   The following table describes the attributes you set on the Groups tab.

   Table 14-10 LDAP Security Realm Attribute on the Groups Tab

   Attribute	Description
   Group DN	List of attributes and values that, combined with the Group Name Attribute attribute, uniquely identifies a Group in the LDAP directory. For example, "o=acme.com, ou=Groups".
   Group Name Attribute	Name of a Group in the LDAP directory. It is usually a common name.
   Group Is Context	Boolean checkbox that specifies how Group membership is recorded in the LDAP directory. Check this checkbox if each Group entry contains one User. By default, the box is selected. Uncheck this checkbox if one Group entry contains an attribute for each Group member.
   Group Username Attribute	Name of the LDAP attribute that contains a Group member in a Group entry.

   
    

9. To save your changes, click the Apply button.

10. When you have finished defining all the attributes, reboot WebLogic Server.

11. Configure the Caching realm. For more information, see Configuring the Caching Realm.

    Note: When you use an LDAP Security realm, you must configure and enable the Caching realm; otherwise, the LDAP Security realm will not work.

    When configuring the Caching realm, select LDAP Realm from the pull-down menu for the Basic attribute on the General tab. The Basic attribute defines the association between the Caching realm and the alternate security realm (in this case, the LDAP Realm V1).

12. Go to the Security node.

13. Choose the Filerealm tab.

14. In the Caching Realm attribute, choose the name of the Caching Realm to be used with the LDAP Security realm. A list of configured Caching Realms appears on the pull-down menu.

    Note: When you use an LDAP Security realm, you must configure and enable the Caching realm; otherwise, the LDAP Security realm will not work.

15. Reboot WebLogic Server.

The Caching realm caches Users and Groups internally to avoid frequent lookups in the LDAP directory. Each object in the Users and Groups caches has a TTL attribute that you set when you configure the Caching realm. If you make changes in the LDAP directory, those changes are not reflected in the LDAP Security realm until the cached object expires or is flushed from the cache. The default TTL is 10 seconds for unsuccessful lookups and 60 seconds for successful lookups. Unless you change the TTL attributes for the User and Group caches, changes in the LDAP directory should be reflected in the LDAP Security realm in 60 seconds.

If some server-side code has performed a lookup in the LDAP Security realm, such as a getUser() call on the LDAP Security realm, the object returned by the realm cannot be released until the code releases it. Therefore, a User authenticated by WebLogic Server remains valid as long as the connection persists, even if you delete the user from the LDAP directory.

Configuring an LDAP Realm V2

Configuring the LDAP Realm V2 involves defining attributes that enable the security realm to communicate with the LDAP server and describe where users and groups are stored in the LDAP directory. The LDAP tree and schema is different for every LDAP server. WebLogic Server provides templates for the supported LDAP servers. These templates specify default configuration information used to represent Users and Groups in each of the supported LDAP servers. For more information, see Supported LDAP Server Templates.

To configure a LDAP security realm V2, you choose the template that corresponds to the LDAP server you want to use and modify it to specify information about your specific configuration.

To use a LDAP Security realm V2:

1. Go to the Security—>Realms node in the left pane of the Administration Console.

2. Choose the LDAP server you want to use with WebLogic Server. The following options are available:

   • defaultLDAPRealmforOpenLDAPDirectoryServices

   • defaultLDAPRealmforNovellDirectoryServices

   • defaultLDAPRealmforMicrosoftSiteServer

   • defaultLDAPRealmforNetscapeDirectoryServer

     The configuration window for the chosen LDAP server appears.

3. Modify the following information in the Configuration Data box:

   • server.host—The host name of the LDAP server.

   • server.port—The port number on which the LDAP server listens.

   • useSSL—Specifies whether or not to use SSL to protect communications between the LDAP server and WebLogic Server. Set the value to true to enable the use of SSL.

   • server.principal—The LDAP user used by WebLogic Server to connect to the LDAP server.

   • server.credential—The password of the LDAP user used by WebLogic Server to connect to the LDAP server.

   • user.dn—The base DN of the tree in the LDAP directory that contains users.

   • user.filter—The LDAP search filter for finding a user given the name of the user.

   • group.dn—The base DN of the tree in the LDAP directory that contains groups.

   • group.filter—The LDAP search filter for finding a group given the name of the group.

   • membership.filter—The LDAP search filter for finding the members of a group given the name of the group.

     For more information, see Supported LDAP Server Templates.

Note: When using the LDAP v2 realm for Microsoft Site server, you must also specify membership.search=true and the following must be added to the user.filter value so that Microsoft Site server does not authenticate disabled users:

user.filter=(&(sAMAccountName=%u)(objectclassname=user)
(!userAccountControl:1.2.840.113556.1.4.803:=2))

1. To save your changes, click the Apply button.

2. Go to the Security node.

3. Choose the Filerealm tab.

4. Configure the Caching realm. For more information, see Configuring the Caching Realm.

   Note: When you use an LDAP Security realm, you must configure and enable the Caching realm; otherwise, the LDAP Security realm will not work.

   When configuring the Caching realm, select the defaultLDAPRealmforLDAPserver (for example, defaultLDAPRealmforOpenLDAPDirectoryServices) from the pull-down menu for the Basic attribute on the General tab. The Basic attribute defines the association between the Caching realm and the alternate security realm (in this case, the LDAP Realm).

5. Reboot WebLogic Server.

Supported LDAP Server Templates

Listing  14-1 through Listing  14-5 are templates used to configure LDAP servers supported by the LDAP V2 Realm.

Warning: Each line in the following code examples must appear on a single line. The code in the code examples has been formatted to fit the margins of this document and some lines have been broken to facilitate that formatting.

Listing 14-1 Default Netscape Directory Server Template

<CustomRealmName="defaultLDAPRealmForNetscapeDirectoryServer"
RealmClassName="weblogic.security.ldaprealmv2.LDAPRealm"
ConfigurationData=
"server.host=ldapserver.example.com;
server.port=700;
useSSL=true;
server.principal=uid=admin,
ou=Administrators,ou=TopologyManagement,o=NetscapeRoot;
server.credential=*secret*;
user.dn=ou=people,o=beasys.com;
user.filter=(&amp;(uid=%u)(objectclass=person));
group.dn=ou=groups,o=beasys.com;
group.filter=(&amp;(cn=%g)(objectclass=groupofuniquenames));
membership.filter=(&amp;(uniquemember=%M)
      (objectclass=groupofuniquenames));

"Notes="Before enabling the LDAP V2 security realm, edit the 
configuration parameters for your environment."/>

Listing 14-2 Default Microsoft Site Server Template

<CustomRealmName="defaultLDAPRealmForMicrosoftSiteServer"
RealmClassName="weblogic.security.ldaprealmv2.LDAPRealm"
ConfigurationData=
"server.host=ldapserver.example.com;
server.port=700;
useSSL=true;
server.principal=cn=Administrator,ou=Members,
      o=ExampleMembershipDir;
server.credential=*secret*
user.dn=ou=Members, o=ExampleMembershipDir;
user.filter=(&amp;(cn=%u)(objectclass=member)
      (!userAccountControl:1.2.840.113556.1.4.803:=2)));
group.dn=ou=Groups, o=ExampleMembershipDir;
group.filter=(&amp;(cn=%g)(objectclass=mgroup));
membership.scope.depth=1;microsoft.membership.scope=sub;
membership.filter=(|(&amp;(memberobject=%M)
(objectclass=memberof))(&amp;(groupobject=%M)
(objectclass=groupmemberof)));
membership.search=true;

"Notes="Before enabling the LDAP V2 security realm, edit the 
configuration parameters for your environment."/>

Listing 14-3 Default Novell Directory Services Template

<CustomRealmName="defaultLDAPRealmForNovellDirectoryServices"
RealmClassName="weblogic.security.ldaprealmv2.LDAPRealm"
ConfigurationData=
"server.host=ldapserver.example.com;
server.port=700;
useSSL=true;
server.principal=cn=Admin, DC=BEASYS
server.credential= *secret*;
user.dn=ou=people,o=example.com;
user.filter=(&amp;(cn=%u)(objectclass=person));
group.dn=ou=groups,o=example.com;
group.filter=(&amp;(cn=%g)(objectclass=groupofuniquenames));
membership.filter=(&amp;(member=%M)
      (objectclass=groupofuniquenames));"

"Notes="Before enabling the LDAP V2 security realm, edit the 
configuration parameters for your environment."/>

Listing 14-4 Default Open LDAP Directory Services Template

<CustomRealmName="defaultLDAPRealmForOpenLDAPDirectoryServices"
RealmClassName="weblogic.security.ldaprealmv2.LDAPRealm"
ConfigurationData=
"server.host=ldapserver.example.com;
server.port=700;
useSSL=true;
server.principal=cn=Manager, dc=example, dc=com;
server.credential= *secret*;
user.dn=ou=people, dc=example,dc=com;
user.filter=(&amp;(uid=%u)(objectclass=person));
group.dn=ou=groups,dc=example,c=com;
group.filter=(&amp;(cn=%g)(objectclass=groupofuniquenames));
membership.filter=(&amp;(uniquemember=%M)     
(objectclass=groupofuniquenames));"

"Notes="Before enabling the LDAP V2 security realm, edit the 
configuration parameters for your environment."/>

Using Microsoft Active Directory with WebLogic Server

By default, WebLogic Server does not support Microsoft Active Directory LDAP server. To use Microsoft Active Directory with WebLogic Server, perform the following steps:

1. Go to the Security—>Realms node in the left pane of the Administration Console.

2. Choose the defaultLDAPRealmforMicrosoftSiteServer option.

   The configuration window for the chosen LDAP server appears.

3. Modify the following information in the Configuration Data box with information specific to the Microsoft Active Directory LDAP server:

   • server.host—The host name of the LDAP server.

   • server.port—The port number on which the LDAP server listens.

   • useSSL—Specifies whether or not to use SSL to protect communications between the LDAP server and WebLogic Server. Set the value to true to enable the use of SSL.

   • server.principal—The LDAP user used by WebLogic Server to connect to the LDAP server.

   • server.credential—The password of the LDAP user used by WebLogic Server to connect to the LDAP server.

   • user.dn—The base DN of the tree in the LDAP directory that contains users.

   • user.filter—The LDAP search filter for finding a user given the name of the user.

   • group.dn—The base DN of the tree in the LDAP directory that contains groups.

   • group.filter—The LDAP search filter for finding a group given the name of the group.

   • membership.filter—The LDAP search filter for finding the members of a group given the name of the group.

     WebLogic Server authenticates by binding to the LDAP server and passing the DN and password of the user. Even if you have disabled a user account by setting the LDAP userAccountControl attribute to ACCOUNTDISABLE, the authentication will succeed unless you have modified the user.filter value to ignore accounts that have been disable. Modify the user.filter value to only return accounts that do not have the UF_ACCOUNTDISABLE bit set. For example:

     user.filter=(&(sAMAccountName=%u)(objectclassname=user)
(!userAccountControl:1.2.840.113556.1.4.803:=2))

     When specifying the group.filter value, CN must be specified as CN=%G otherwise the filter fails to find the members of a group.

4. To save your changes, click the Apply button.

5. Go to the Security node.

6. Choose the Filerealm tab.

7. Configure the Caching realm. For more information, see Configuring the Caching Realm.

   Note: When you use an LDAP Security realm, you must configure and enable the Caching realm; otherwise, the LDAP Security realm will not work.

   When configuring the Caching realm, select the defaultLDAPRealmforLDAPserver (for example, defaultLDAPRealmforOpenLDAPDirectoryServices) from the pull-down menu for the Basic attribute on the General tab. The Basic attribute defines the association between the Caching realm and the alternate security realm (in this case, the LDAP Realm).

8. Reboot WebLogic Server.

Configuring the Windows NT Security Realm

The Windows NT Security realm uses account information defined for a Windows NT domain to authenticate Users and Groups. You can view Users and Groups in the Windows NT Security realm through the Administration Console, but you must manage Users and Groups through the facilities provided by Windows NT.

The Windows NT Security realm provides authentication (Users and Groups) but not authorization (ACLs). To update the ACL information in the filerealm.properties file that WebLogic Server uses, click the Refresh button on the General tab in the Security node after you change an ACL. If you use Groups with your ACLs, you can reduce the frequency with which you must refresh the information in WebLogic Server. Changing the members of a Windows NT Group allows you to manage individual Users' access to WebLogic Server resources dynamically.

It is possible to use the Windows NT Security realm to authenticate against a Windows 2000 Active Directory primary domain controller. However, the authentication must be from a machine which is a member of the domain not the domain controller itself. There is no way to authenticate to the local User and Group store if the machine running the Windows NT Security realm is a member of another domain.

The Windows NT Security realm can be run on the primary domain controller, on a machine that is a member of a Windows NT domain, or on a machine that is a member of the Windows NT domain and wants to use a mutually trusted domain.

To use the Windows NT Security realm:

1. Go to the Security—>Realms node in the left pane of the Administration Console.

2. In the right pane of the Administration Console, click the Configure a New NT Realm link.

3. Configuring the Windows NT Security realm involves setting attributes that define a name for the realm and the computer on which the Windows NT domain is running. To specify a realm name and computer, you must define values for the attributes shown the NT Realm Create window of the Administration Console.

   The following table describes the attributes you set in the NT Realm Configuration window.

   Table 14-11 Windows NT Security Realm Attributes

   Attribute	Description
   Name	The name of the Windows NT Security realm, such as, AccountingRealm
   Primary Domain	The host and port number of the computer where Users and Groups are defined for the Windows NT domain. If you enter multiple host and port numbers, use a comma delineated list.

   
    

4. To save your changes, click the Apply button.

5. When you have finished defining the attributes, reboot WebLogic Server.

6. Configure the Caching realm. For more information, see Configuring the Caching Realm.

   Note: When you use an Windows NT Security realm, you must configure and enable the Caching realm; otherwise, the Windows NT Security realm will not work.

   When configuring the Caching realm, select your Windows NT Security realm from the pull-down menu for the Basic attribute on the General tab. The Basic attribute defines the association between the Caching realm and the alternate security realm (in this case, the Windows NT Security realm).

7. Go to the Security node.

8. Choose the Filerealm tab.

9. In the Caching Realm attribute, choose the name of the Caching Realm to be used with the Windows NT Security realm. A list of configured Caching Realms appears on the pull-down menu.

   Note: When you use an Windows NT Security realm, you must configure and enable the Caching realm; otherwise, the Windows NT Security realm will not work.

10. Reboot WebLogic Server.

Use the following command to verify that you have the correct privileges to run WebLogic Server as the specified Windows NT user:

java weblogic.security.ntrealm.NTRealm username password

where username and password are the username and password of the Windows NT account under which WebLogic Server runs.

The output from this command will tell if the specified username and password authenticated properly.

Command Output	Meaning
auth?poppy	The entered username and password authenticated correctly.
auth?null	The entered username and password did not authenticate properly.

 

If the test comes up with an immediate failure stating that the client or user running WebLogic Server does not have the privileges to run the Windows NT Security realm, you need to update the permissions (referred to as rights) for the Windows user running WebLogic Server.

To update the rights in Windows NT:

1. Go to Programs—>Administrative Tools.

2. Select User Manager.

3. Under the Policies menu, choose the User Rights option.

4. Check the Show Advanced Users Rights option.

5. Give the following rights to the Windows user running WebLogic Server:

   • Act as part of the operating system

   • Create a token object

   • Replace a process level token

6. Verify that the Windows user running WebLogic Server is a member of the Administrators group.

7. Reboot Windows NT to ensure all the modifications take effect.

8. Verify that the Logon as System Account option is checked. Note that the Allow System to Interact with Desktop option does not need to be checked. Running the Windows NT Security realm under a specific Windows NT user account does not work.

To update the rights in Windows 2000:

1. Go to Programs—>Administrative Tools.

2. Select Local Security Policy.

3. Go to Local Policies—>User Rights Assignment.

4. Give the following rights to the Windows user running WebLogic Server:

   • Act as part of the operating system

   • Create a token object

   • Replace a process level token

5. Verify that the Windows user running WebLogic Server is a member of the Administrators group.

6. Reboot Windows 2000 to ensure all the modifications take effect.

7. Verify that the Logon as System Account option is checked. Note that the Allow System to Interact with Desktop option does not need to be checked. Running the Windows NT Security realm under a specific Windows NT user account does not work.

The following are common Windows NT error codes that occur when using the Windows NT Security realm:

Error Code	Meaning
1326	The host machine running the security realm does not have a trust relationship with the primary domain controller. The host machine may not be a member of the domain or the domain may not trust the host machine.
53	A network error has occurred indicating that the path to the primary domain controller could not be located. This error could occur if the domain name is misspelled or if the domain name is specified rather than the host name of the primary domain controller.

 

A full explanation of the Windows NT error codes is found in the winerror.h file.

Configuring the UNIX Security Realm

Note: The UNIX Security realm runs only on the Solaris platform.

The UNIX Security realm executes a small native program, wlauth, to look up Users and Groups and to authenticate Users on the basis of their UNIX login names and passwords. The wlauth program uses PAM (Pluggable Authentication Modules) which allows you to configure authentication services in the operating system without altering applications that use the service.

In UNIX, a user is defined as a member of a group in the following ways:

• The user is defined in a default group in etc/passwd.

• The user ID for a user is included in the etc/group entry for a specific group. The UNIX Security realm supports only this method of determining the members of a group.

After you change an ACL, click the Refresh button on the General tab in the Security to update the information in the filerealm.properties file that WebLogic Server uses. If you use Groups with your ACLs, you can reduce the frequency with which you must refresh the information in WebLogic Server. Changing the members of a UNIX Group allows you to manage individual Users' access to WebLogic Server resources dynamically.

It is possible to run wlauth to verify authentication. At a UNIX command prompt:

1. Enter wlauth.

2. Enter -user_auth username, password.

If the command returns a 0, the authentication check was successful. If the command returns a 1, the authentication check failed.

To use the UNIX Security realm:

1. Go to the Security—>Realms node in the left pane of the Administration Console.

2. In the right pane of the Administration Console, click the Configure a New UNIX Realm link.

3. Configuring the UNIX Security realm involves setting attributes that define a name for the realm and the program that provides authentication services for the UNIX Security realm. To define these names, specify values for the attributes on the UNIX Realm Create window of the Administration Console.

   The following table describes the attributes you set in the UNIX Realm Create window.

   Table 14-12 UNIX Security Realm Attributes

   Attribute	Description
   Name	The name of the UNIX Security realm, such as AccountingRealm
   AuthProgram	The name of the program used to authenticate users in the UNIX security realm. In most cases, the name of the program is wlauth.
   Realm Classname	The name of the Java class that implements the UNIX Security realm. The Java class needs to be in the class path of WebLogic Server.

   
    

4. To save your changes, click the Apply button.

5. When you have finished defining the attributes, reboot WebLogic Server.

6. Configure the Caching realm. For more information, see Configuring the Caching Realm.

   Note: When you use an UNIX Security realm, you must configure and enable the Caching realm; otherwise, the UNIX Security realm will not work.

   When configuring the Caching realm, select your UNIX Security realm from the pull-down menu for the Basic attribute on the General tab. The Basic attribute defines the association between the Caching realm and the alternate security realm (in this case, the UNIX Security realm).

7. Go to the Security node.

8. Choose the Filerealm tab.

9. In the Caching Realm attribute, choose the name of the Caching Realm to be used with the UNIX Security realm. A list of configured Caching Realms appears on the pull-down menu.

   Note: When you use an UNIX Security realm, you must configure and enable the Caching realm; otherwise, the UNIX Security realm will not work.

10. Reboot WebLogic Server.

If wlauth is not in the WebLogic Server class path or if you have given the program a name other than wlauth, you must add a Java command-line property when you start WebLogic Server. Edit the script you use to start WebLogic Server and add the following option after the java command:

-Dweblogic.security.unixrealm.authProgram=wlauth_prog

Replace wlauth_prog with the name of the wlauth program, including the full path if the program is not in the search path. Start WebLogic Server. If the wlauth program is in the WebLogic Server path and is named wlauth, this step is not needed.

Configuring the RDBMS Security Realm

The RDBMS Security realm is a BEA-provided custom security realm that stores Users, Groups and ACLs in a relational database.The RDBMS Security realm is an example and is not ment to be used in a production environment. You can perform the following managment functions on the RDBMS Security realm through the Administration Console:

Managment Function	Support through the Administration Console
Create User	Yes but only in memory.
Delete User	Yes
Change Password	No
Create Group	No
Delete Group	Yes
Add Group Member	Yes
Delete Group Member	Yes
Create ACL	No
Delete ACL	No
Add Permission	No
Delete Permission	No

 

SQL scripts that populate a database are used to create Groups for the RDBMS Security realm

The RDBMS Security realm can be used as a starting point for creating a production security realm. You can extend the RDBMS Security realm by using the following interfaces in the weblogic.security.acl package to add management capabilities to the RDBMS Security realm:

• ManageableRealm—Create Groups, create and delete ACLs, and perform lookups of Users, Groups, and ACLs.

• User—Change the password.

• ACL—Add and remove permissions for Users and Groups.

If you extend the RDBMS Security realm with any of these interfaces, you may also need to update the database schema.

Note: The RDBMS example does not work with databases that have an autocommit feature enabled. If you use the RDBMS example as a starting point for your RDBMS implementation, use explicit commit statements in your code and make sure the autocommit feature in the database you are using is disabled.

To use the RDBMS Security realm:

1. Go to the Security—>Realms node in the left pane of the Administration Console.

2. In the right pane of the Administration Console, click the Configure a New RDBMS Realm link.

3. Define information about the class that implements the RDBMS Security realm.

   The following table describes the attributes you set on the General tab.

   Table 14-13 RDBMS Security Realm Attributes on the General Tab

   Attribute	Description
   Name	Name of the RDBMS Security realm, such as, AccountingRealm
   Realm Class	Name of the WebLogic class that implements the RDBMS Security realm. The Java class needs to be in the CLASSPATH of WebLogic Server.

   
    

4. To save your changes, click the Apply button.

5. Define attributes for the JDBC driver being used to connect to the database.

   The following table describes the attributes you set on the Database tab.

   Table 14-14 RDBMS Security Realm Attributes on the Database Tab

   Attribute	Description
   Driver	Full class name of the JDBC driver. This class name must be in the CLASSPATH of WebLogic Server.
   URL	URL for the database you are using with the RDBMS realm, as specified by your JDBC driver documentation.
   User Name	Default user name for the database.
   Password	Password for the default user of the database.

   
    

6. To save your changes, click the Apply button.

7. Define the schema used to store Users, Groups, and ACLs in the database in the Schema Properties box on the Schema tab.

   Listing  14-5 contains the database statements entered in the Schema properties for the RDBMS code example shipped with WebLogic Server in the /samples/examples/security/rdbmsrealm directory.

   Listing 14-5 Sample Schema for RDBMS Security Realm

   "getGroupNewStatement=true;getUser=SELECT U_NAME, U_PASSWORD FROM 
   users WHERE U_NAME = ?;
   getGroupMembers=SELECT GM_GROUP, GM_MEMBER from groupmembers WHERE 
   GM_GROUP = ?;
   getAclEntries=SELECT A_NAME, A_PRINCIPAL, A_PERMISSION FROM 
   aclentries WHERE A_NAME = ? ORDER BY A_PRINCIPAL;
   getUsers=SELECT U_NAME, U_PASSWORD FROM users;
   getGroups=SELECT GM_GROUP, GM_MEMBER FROM groupmembers;
   getAcls=SELECT A_NAME, A_PRINCIPAL, A_PERMISSION FROM aclentries 
   ORDER BY A_NAME, A_PRINCIPAL;
   getPermissions=SELECT DISTINCT A_PERMISSION FROM aclentries;
   getPermission=SELECT DISTINCT A_PERMISSION FROM aclentries WHERE 
   A_PERMISSION = ?;
   newUser=INSERT INTO users VALUES ( ? , ? );
   addGroupMember=INSERT INTO groupmembers VALUES ( ? , ? );
   removeGroupMember=DELETE FROM groupmembers WHERE GM_GROUP = ? AND 
   GM_MEMBER = ?;
   deleteUser1=DELETE FROM users WHERE U_NAME = ?;
   deleteUser2=DELETE FROM groupmembers WHERE GM_MEMBER = ?;
   deleteUser3=DELETE FROM aclentries WHERE A_PRINCIPAL = ?;
   deleteGroup1=DELETE FROM groupmembers WHERE GM_GROUP = ?;
   deleteGroup2=DELETE FROM aclentries WHERE A_PRINCIPAL = ?"
   

8. To save your changes, click the Apply button.

9. When you have finished defining the attributes, reboot WebLogic Server.

10. Configure the Caching realm. For more information, see Configuring the Caching Realm.

    Note: When you use an RDBMS Security realm, you must configure and enable the Caching realm; otherwise, the RDBMS Security realm will not work.

    When configuring the Caching realm, select the RDBMS Security realm from the pull-down menu for the Basic attribute on the General tab. The Basic attribute defines the association between the Caching realm and the alternate security realm (in this case, the RDBMS Security realm).

11. Go to the Security node.

12. Choose the Filerealm tab.

13. In the Caching Realm attribute, choose the name of the Caching Realm to be used with the RDBMS Security realm. A list of configured Caching Realms appears on the pull-down menu.

    Note: When you use an RDBMS Security realm, you must configure and enable the Caching realm; otherwise, the RDBMS Security realm will not work.

14. Reboot WebLogic Server.

Installing a Custom Security Realm

You can create a custom security realm that draws from an existing store of Users such as directory server on the network. To use a custom security realm, you create an implementation of the weblogic.security.acl.AbstractListableRealm interface or the weblogic.security.acl.AbstractManageableRealm interface and then use the Administration Console to install your implementation.

To install a custom security realm:

1. Go to the Security—>Realms node in the left pane of the Administration Console.

2. In the right pane of the Administration Console, click the Configure a New Custom Realm link.

3. Define a name for the custom security realm, specify the interface that implements the realm, and define how the Users, Groups, and optionally ACLs are stored in the custom security realm on the Configuration window.

   The following table describes the attributes you set on the Custom Security Realm Configuration window.

   Table 14-15 Custom Security Realm Attributes

   Attribute	Description
   Name	Name of the Custom Security realm, such as AccountingRealm
   Realm Class Name	Name of the WebLogic class that implements the Custom Security realm. The Java class needs to be in the CLASSPATH of WebLogic Server.
   Configuration Data	Information needed to connect to the security store.
   Password	Password for the Custom Security realm. If a password is supplied, WebLogic Server encrypts it.

   
    

4. To save your changes, click the Create button.

5. When you have finished defining the attributes, reboot WebLogic Server.

6. Configure the Caching realm. For more information, see Configuring the Caching Realm.

   Note: When you use an custom security realm, you must configure and enable the Caching realm; otherwise, the custom security realm will not work.

   When configuring the Caching realm, select the Custom Security realm from the pull-down menu for the Basic attribute on the General tab. The Basic attribute defines the association between the Caching realm and the custom security realm.

7. Go to the Security node.

8. Choose the Filerealm tab.

9. In the Caching Realm attribute, choose the name of the Caching Realm to be used with the custom security realm. A list of configured Caching Realms appears on the pull-down menu.

   Note: When you use an custom security realm, you must configure and enable the Caching realm; otherwise, the custom security realm will not work.

10. Reboot WebLogic Server.

For information about writing a custom security realm, see Writing a Custom Security Realm.

Migrating Security Realms

WebLogic Server provides a management architecture for security realms. The management architecture implemented through MBeans allows you to manage security realms through the Administration Console. If you have a security realm from a previous release of WebLogic Server, use the following information to migrate to the new architecture:

• If you are using the Windows NT, UNIX, or LDAP security realms, use the Convert weblogic.properties option in the Administration Console to convert the security realm to the new architecture. Note that you can view Users, Groups, and ACLs in a Windows NT, UNIX, or LDAP security realm in the Administration Console. However, you still need to use the tools in the Windows NT, UNIX, or LDAP environments to manage Users and Groups.

• If you are using a custom security realm, follow the steps in Installing a Custom Security Realm to specify information about how the Users, Groups, and optionally ACLs are stored in your custom security realm.

• The Delegating security realm is no longer supported. If you are using the Delegating security realm, you will have to use another type of security realm to store Users, Groups, and ACLs.

• If you are using the RDBMS security realm, use one of the following options to convert the security realm:

  • If you did not change the source for the RDBMS security realm, follow the steps in Configuring the RDBMS Security Realm to instantiate a new class for your existing RDBMS security realm and define information about the JDBC driver being used to connect to the database and the schema used by the security realm. In this case, you are creating a MBean in WebLogic Server for the RDBMS security realm.

  • If you customized the RDBMS security realm, convert your source to use the MBeans. Use the code example in the \samples\examples\security\rdbmsrealm directory as a guide to converting your RDBMS security realm. Once you have converted your RDBMS security realm to MBeans, follow the instructions inConfiguring the RDBMS Security Realm to define information about the JDBC driver being used to connect to the database and the schema used by the security realm.

 

---

Defining Users

Note: This section explains how to add Users to the File realm. If you are using an alternate security realm, you must use the administration tools provided in that realm to define a User.

User and group names must be unique. You can use multibyte characters and all special characters except a comma (,) in user and group names.

Users are entities that can be authenticated in a WebLogic Server security realm. A User can be a person or a software entity, such as a Java client. Each User is given a unique identity within a WebLogic Server security realm. As a system administrator you must guarantee that no two Users in the same security realm are identical.

Defining Users in a security realm involves specifying a unique name and password for each User that will access resources in the WebLogic Server security realm in the Users window of the Administration Console.

WebLogic Server has two special users, system and guest:

• The system User is the administrative user who controls system-level WebLogic Server operations, such as starting and stopping servers, and locking and unlocking resources. The system User and its password are defined during the WebLogic Server installation procedure. As a security precaution, BEA recommends changing the password for the system User. For more information, see Changing the System Password.

• The guest User is automatically provided by WebLogic Server. When authorization is not required, WebLogic Server assigns the guest identity to a client, thus giving the client access to any resources that are available to the guest user. A client can log in as the guest User by entering guest as the username and guest as the password when prompted by a Web browser or by supplying the guest username and password in a Java client. By default, the guest account is enabled.

  For a more secure deployment, BEA recommends running WebLogic Server with the guest account disabled. To disable the guest account, select the Guest Disabled attribute on the General tab of the Security Configuration window. Disabling the guest account just disables the ability to log in into the account guest; it does not disable the ability for unauthenticated users to access a WebLogic Server deployment.

Warning: Be advised it is still possible to access a deployment through an anonymous user if the ACLs on the anonymous user are not set properly. Set ACLs so that unauthorized access is not possible.

The system and guest Users are like other Users in a WebLogic Server security realm:

• To access WebLogic Server resources, they must have appropriate ACLs.

• To execute an operation on a WebLogic Server resource, they must provide a username and password (or digital certificate).

To define a User:

1. Go to the Security—>Users node in the left pane of the Administration Console.

   The User Configuration window appears.

2. In the User Configuration window, enter the name of the User in the Name attribute.

3. Enter the a password for the User in the Password attribute.

4. Enter the password again in the Confirm Password attribute.

5. Click Create.

To delete a User:

1. Enter the name of the User in the Delete Users box on the User Configuration window.

2. Click Delete.

To change the password of a User:

1. Enter the name of the User in the Name attribute on the User Configuration window.

2. Enter the old password in the Old Password attribute.

3. Enter the new password in the New Password attribute.

4. Enter the new password again to confirm the password change.

While using WebLogic Server, you may have Users that are locked. Perform the following steps to unlock a User:

1. Open the Users window in the Administration Console.

2. Click on the Unlock Users link.

3. Enter the names of the Users you want to unlock in the Users to Unlock field.

4. Choose the servers on which you want the Users unlocked.

5. Click Unlock.

For more information about Users and the access control model in WebLogic Server, see Introduction to WebLogic Security and Security Fundamentals.

 

---

Defining Groups

Note: This section describes how to add Groups to the File realm. If you are using an alternate security realm, you need to use the management tools provided in that realm to define a Group.

User and group names must be unique. You can use multibyte characters and all special characters except a comma (,) in user and group names.

A Group represents a set of Users who usually have something in common, such as working in the same department in a company. Groups are a means of managing a number of Users in an efficient manner. When a Group is granted a permission in an ACL, all members of the Group effectively receive that permission. BEA recommends assigning permissions to Groups rather than to individual Users.

By default, WebLogic Server has the following Groups:

• All Users defined in the security realm are automatically members of the everyone Group.

• All Users defined in the security realm except the guest user are automatically members of the users Group.

• The system User is a member of the Administrators Group. This Group should be given the permissions appropriate for a user responsible for starting and stopping servers and maintaining a running WebLogic Server deployment. Access to this group should be limited.

You can register a Group with the WebLogic Server security realm by performing the following steps:

1. Go to the Security—>Groups node in the left pane of the Administration Console.

2. Click the Create a New Group link.

   The Group Configuration window appears.

3. Enter the name of the Group in the Name attribute on the Group Configuration window. BEA recommends naming Groups in the plural. For example, Administrators instead of Administrator.

4. Click on the Users attribute and select the WebLogic Server Users you want to add to the Group.

5. Click on the Groups attribute and select the WebLogic Server Groups you want to add to the Group.

6. Click on the Apply button to create a new Group.

To delete Groups, enter the name of the Group in the Remove These Groups list box on the Group Configuration window and click Remove.

For more information about Groups and the access control model in WebLogic Server, see Introduction to WebLogic Security and Security Fundamentals.

 

---

Defining ACLs

Users access resources in a WebLogic Server security realm. Whether or not a User can access a resource is determined by the access control lists ACLs for that resource. An ACL defines the permissions by which a User can interact with the resource. To define ACLs, you create an ACL for a resource, specify the permission for the resource and then grant the permission to a specified set of Users and Groups. BEA recommends assigning ACLs to Groups.

Each WebLogic Server resource has one or more permissions that can be granted. The following table summarizes the functions for various WebLogic Server resources for which permissions can be restricted with an ACL.

Table 14-16 ACLs for WebLogic Server Resources

For this WebLogic Server resource...	This ACL...	Grants Permission for these functions...
WebLogic Servers	weblogic.server weblogic.server.servername	boot
Command-line Administration Tools	weblogic.admin Note: To add ACLs through the Administration Console, you need to define weblogic.admin.acl.modify.	shutdown, lockServer unlockServer, modify
MBeans	weblogic.admin.mbean.mbeaninstancename weblogic.admin.mbean.mbeantypename	read, write, access
WebLogic Events	weblogic.event.topicName	send receive
WebLogic JDBC connection pools	weblogic.jdbc.connectionPool.poolname Note: If you specify a value in the ACL field when configuring a JDBC connection pool, you must define the same value on the Security—>ACLs node in order for the ACL to work. If you chose to use the weblogic.jdbc.connectionPool.poolname syntax to create an ACL for a JDBC connection pool, leave the ACL field in the JDBC connection pool configuration place blank.	reserve reset admin
WebLogic Passwords	weblogic.passwordpolicy	unlockuser
WebLogic JMS destinations	weblogic.jms.topic.topicName weblogic.jms.queue.queueName	send, receive
WebLogic JNDI contexts	weblogic.jndi.path	lookup modify list

 

Note: When you specify an ACL for a JDBC connection pool, you must specifically define access to the JDBC connection pool for the system and guest user in the filerealm.properties file. For example:

acl.reserve.poolforsecurity=system, guest
acl.reset.poolforsecurity=system, guest

To create ACLs for a WebLogic Server resource, open the Administration Console and perform the following steps:

1. Go to the Security—>ACLs node in the left pane of the Administration Console.

2. In the right pane of the Administration Console, click the Create a New ACL link.

   The ACL Configuration window appears.

3. Specify the name of WebLogic Server resource that you want to protect with an ACL in the New ACL Name field.

   For example, create an ACL for a JDBC connection pool named demopool.

4. Click Create.

5. Click on the Add a New Permission link.

6. Specify a permission for the resource.

   You can either create separate ACLs for each permission available for a resource or one ACL that grants all the permissions for a resource. For example, you can create three ACLs for the JDBC connection pool, demopool: one with reserve permission, one with reset permission, and one with shrink permission. Or you can create one ACL with reserve, reset, and shrink permissions.

7. Specify Users or Groups that have the specified permission to the resource.

8. Click Apply.

When creating ACLs for resources in WebLogic Server you need to use the syntax in Table  14-16 to refer to the resource.

If you modify an existing ACL, click the Refresh button on the General tab in the Security node to update the information in the filerealm.properties file that WebLogic Server uses.

Before you can boot WebLogic Server, you need to give boot permission for the server to a specific Group. This security measure prevents unauthorized users from booting WebLogic Server.

By default, only the system user can modify MBeans. BEA recommends limiting the number of users that can access and modify MBeans. Use the following ACL to access to all the WebLogic Server MBeans:

access.weblogic.admin.mbean=Group or User name

If a user or group fails in an attempt to access a MBean, a weblogic.management.NoAccessRuntimeException is returned. The server log contains the details indicating which user attempted to access what MBean.

Before you can grant permissions to Users or Groups through the Administration Console, you need to give the Administrators Group the following permission:

acl.modify.weblogic.admin=Administrators

 

---

Configuring the SSL Protocol

The following sections describe how to obtain digital certificates and configure the SSL protocol:

• Obtaining a Private Key and Digital Certificate

• Storing Private Keys and Digital Certificates

• Defining Trusted Certificate Authorities

• Defining Attributes for the SSL Protocol

• Modifying Parameters for SSL Session Caching

For a complete description of the SSL Protocol, see Introduction to WebLogic Security and Security Fundamentals.

This release of WebLogic Server supports SSL v3.0.

Obtaining a Private Key and Digital Certificate

You need a private key and digital certificate for each deployment of WebLogic Server that will use the SSL protocol. To acquire a digital certificate from a certificate authority, you must submit your request in a particular format called a Certificate Signature Request (CSR). WebLogic Server includes a Certificate Request Generator servlet that creates a CSR. The Certificate Request Generator servlet collects information from you and generates a private key file and a certificate request file. You can then submit the CSR to a certificate authority such as VeriSign or Entrust.net. Before you can use the Certificate Request Generator servlet, WebLogic Server must be installed and running.

Note: If you obtain a private key file from a source other than the Certificate Request Generator servlet, verify that the private key file is in PKCS#5/PKCS#8 PEM format.

To generate a CSR, perform the following steps:

1. Start the Certificate Request Generator servlet. The .war file for the servlet is located in the \wlserver6.1\config\\applications directory. The .war file is automatically installed when you start WebLogic Server.

2. In a Web browser, enter the URL for the Certificate Request Generator servlet as follows:

   https://hostname:port/certificate/

   The components of this URL are defined as follows:

   • hostname is the DNS name of the machine running WebLogic Server.

   • port is the number of the port at which WebLogic Server listens for SSL connections. The default is 7002.

     For example, if WebLogic Server is running on a machine named ogre and it is configured to listen for SSL communications at the default port 7002 to run the Certificate Request Generator servlet, you must enter the following URL in your Web browser:

     https://ogre:7002/certificate/
     

3. The Certificate Request Generator servlet loads a form in your Web browser. Complete the form displayed in your browser, using the information in the following table:

   Table 14-17 Fields on the Certificate Request Generator Form

   Field	Description
   Country code	Two-letter ISO code for your country. The code for the United States is US.
   Organizational unit name	Name of your division, department, or other operational unit of your organization.
   Organization name	Name of your organization. The certificate authority may require any host names entered in this attribute belong to a domain registered to this organization.
   E-mail address	E-mail address of the administrator. The digital certificate is mailed to this e-mail address.
   Full host name	Fully qualified name of the WebLogic Server on which the digital certificate will be installed. This name is the one used for DNS lookups of the WebLogic Server, for example, node.com. Web browsers compare the host name in the URL to the name in the digital certificate. If you change the host name later, you must request a new digital certificate.
   Locality name (city)	Name of your city or town. If you operate with a license granted by a city, this attribute is required; you must enter the name of the city that granted your license.
   State name	Name of the state or province in which your organization operates if your organization is in the United States or Canada, respectively. Do not abbreviate.
   Private Key Password	The password used to encrypt the private key. Enter a password in this field if you want to use a protected key with WebLogic Server. If you choose to use a protected key, you are prompted for the password whenever the key is used. If you specify a password, you get a PKCS-8 encrypted private key. BEA recommends using a password to protect private keys. If you do not want to use a protected key, leave this field blank. To use protected private keys, enable the Key Encrypted attribute on the SSL tab of the Server window in the Administration Console.
   Strength	The length (in bits) of the keys to be generated. The longer the key, the more difficult it is for someone to break the encryption. If you have the domestic version of WebLogic Server, you can choose 512-, 768-, or 1024-bit keys. The 1024-bit key is recommended. Note: This field only appears on the domestic version of the Certificate Request Generator servlet.

   
    
    

4. Click the Generate Request button.

   The Certificate Request Generator servlet displays messages informing you if any required attributes are empty or if any attributes contain invalid values. Click the Back button in your browser and correct any errors.

   When all attributes have been accepted, the Certificate Request Generator servlet generates the following files in the startup directory of your WebLogic Server:

   • www__com-key.der—The private key file. The name of this file should go into the Server Key File Name attribute field on the SSL tab in the Administration Console.

   • www__com-request.dem—The certificate request file, in binary format.

   • www__com-request.pem—The CSR file that you submit to the certificate authority. It contains the same data as the .dem file but is encoded in ASCII so that you can copy it into e-mail or paste it into a Web form.

5. Select a certificate authority and follow the instructions on that authority's Web site to purchase a digital certificate.

   • VeriSign, Inc. offers two options for WebLogic Server: Global Site Services, which features strong 128-bit encryption for domestic and export Web browsers, and Secure Site Services, which offers 128-bit encryption for domestic Web browsers and 40-bit encryption for export Web browsers.

   • Entrust.net digital certificates offer 128-bit encryption for domestic browser versions and 40-bit encryption for export browser versions.

6. When you are instructed to select a server type, choose BEA WebLogic Server to ensure that you receive a digital certificate that is compatible with WebLogic Server.

7. When you receive your digital certificate from the certificate authority, you need to store it in the \wlserver6.1\config\ directory.

8. Configure WebLogic Server to use the SSL protocol, you need to enter the following information on the SSL tab in the Server Configuration window:

   • In the Server Certificate File Name attribute, enter the full directory location and name of the digital certificate that establishes the identity of WebLogic Server.

   • In the Trusted CA File Name attribute, enter the full directory location and name of the digital certificate for the certificate authority who signed the digital certificate of WebLogic Server.

   • In the Server Key File Name attribute, enter the full directory location and name of the private key file for WebLogic Server.

     For more information about configuring the SSL protocol, see Defining Attributes for the SSL Protocol.

9. If you are using a protected private key, use the following command-line option to start WebLogic Server.

   -Dweblogic.management.pkpassword=password

   where password is the password for the private key.

Storing Private Keys and Digital Certificates

Once you have a private key and digital certificate, copy the private key file generated by the Certificate Request Generator servlet and the digital certificate you received from the certificate authority into the \wlserver6.1\config\ directory.

Private key files and digital certificates are generated in either PEM or Definite Encoding Rules (DER) format. The filename extension identifies the format of the digital certificate file.

A PEM (.pem) format private key file begins and ends with the following lines, respectively:

  -----BEGIN ENCRYPTED PRIVATE KEY-----

  -----END ENCRYPTED PRIVATE KEY-----

A PEM(.pem) format digital certificate begins and ends with the following lines, respectively:

  -----BEGIN CERTIFICATE-----

  -----END CERTIFICATE-----

Note: Your digital certificate may be one of several digital certificates in the file, each of which is bounded by the BEGIN CERTIFICATE and END CERTIFICATE lines. Typically, the digital certificate file for a WebLogic Server is in one file, with either a .pem or .der extension, and the WebLogic Server certificate chain is in another file. Two files are used because different WebLogic Servers may share the same certificate chain.

The first digital certificate in the certificate authority file is the first digital certificate in the WebLogic Server's certificate chain. The next certificates in the file are the next digital certificates in the certificate chain. The last certificate in the file is a self-signed digital certificate that ends the certificate chain.

A DER (.der) format file contains binary data. WebLogic Server requires that the file extension match the contents of the certificate file so be sure to save the file you receive from your certificate authority with the correct file extension.

Assign protections to the private key file and digital certificates so that only the system User of WebLogic Server has read privileges and all other users have no privileges to access the private key file or digital certificate. If you are creating a file with the digital certificates of multiple certificate authorities or a file that contains a certificate chain, you must use PEM format. WebLogic Server provides a tool to for converting DER-format files to PEM format, and visa versa. For more information, see WebLogic Utilities.

Defining Trusted Certificate Authorities

When establishing an SSL connection, WebLogic Server checks the identity of the certificate authority against a list of trusted certificate authorities to ensure the certificate authority currently being used is trusted.

Copy the root certificate of the certificate authority into the \wlserver6.1\config\ directory of your WebLogic Server and set the attributes described in Defining Attributes for the SSL Protocol.

If you want to use a certificate chain, append the additional PEM-encoded digital certificates to the digital certificate of the certificate authority that issued the digital certificate for WebLogic Server. The last digital certificate in the file should be a digital certificate that is self-signed (that is, the rootCA certificate).

If you want to use mutual authentication, take the root certificates for the certificate authorities you want to accept and include them to the trusted CA file.

Defining Attributes for the SSL Protocol

The Secure Sockets Layer (SSL) protocol provides secure connections by allowing two applications connecting over a network connection to authenticate the other's identity and by encrypting the data exchanged between the applications. The SSL protocol provides server authentication and optionally client authentication, confidentiality, and data integrity.

To define attributes for the SSL protocol, perform the following steps:

1. Open the Administration Console.

2. Open the Server Configuration window.

3. Select the SSL tab. Define the attributes on this tab by entering values and selecting the required checkboxes. (For details, see the following table.)

4. Click the Apply button to save your changes.

5. Reboot WebLogic Server.

Note: If you are using a PKCS-8 protected private key, you need to specify the password for the private key on the command line when you start WebLogic Server.

The following table describes each attribute on the SSL tab of the Server Configuration window.

Table 14-18 SSL Protocol Attributes

Attribute	Description
Enabled	Enables the use of the SSL protocol. By default, this attribute is enabled.
Listen Port	Number of the dedicated port on which WebLogic Server listens for SSL connections. The default is 7002.
Server Key File Name	Directory location and name of the private key file for WebLogic Server. Start the directory location needs at the root of the WebLogic Server installation. For example: \wlserver6.1\config\myapp\privatekey.pem. The file extension (.DER or .PEM) indicates the method that WebLogic Server should use to read the contents of the file.
Server Certificate File Name	Full directory location and name of the digital certificate file that establishes the identity of WebLogic Server. Start the directory location at the root of the WebLogic Server installation. For example: \wlserver6.1\config\myapp\cert.pem. The file extension (.DER or .PEM) indicates the method that WebLogic Server should use to read the contents of the file.
Server Certificate Chain File Name	Full directory location of the digital certificate used to sign the digital certificate for WebLogic Server. Start the directory location at the root of the WebLogic Server installation. For example: \wlserver6.1\config\myapp\cacert.pem. The file extension (.DER or .PEM) indicates the method that WebLogic Server should use to read the contents of the file. When using a certificate chain with WebLogic Server, the file should contain as its first member the digital certificate used to sign the digital certificate for WebLogic Server, the second member should contain a digital certificate used to sign the first digital certificate in the file and so on. The last digital certificate in the file should be self-signed. The Server Certificate Chain File Name attribute is required to have at least one digital certificate. If there is only one digital certificate in the file, the digital certificate must be self-signed (i.e., it must be a root CA digital certificate). When obtaining a digital certificate from a certificate authority, you should receive the digital certificate of the certificate authority and other immediate digital certificates from the certificate authority.
Client Certificate Enforced	Defines whether or not clients must present digital certificates from a trusted certificate authority to WebLogic Server.
Trusted CA File Name	Name of the file that contains the digital certificate for the certificate authorities trusted by WebLogic Server. The file specified in this attribute can contain a single digital certificate or multiple digital certificates for certificate authorities. The file extension (.DER or .PEM) tells WebLogic Server how to read the contents of the file.
CertAuthenticator	Name of the Java class that implements the CertAuthenticator interface. For more information about using the weblogic.security.acl.CertAuthenticator interface, see Mapping a Digital Certificate to a WebLogic User.
Key Encrypted	Specifies that the private key for WebLogic Server is encrypted with a password. The default is false. If you specify this attribute, you need to use protected keys with WebLogic Server. Also, when you boot WebLogic Server, use the following command-line option to start WebLogic Server. -Dweblogic.management.pkpassword=password where password is the password for the private key.
Use Java	When selected, enables the use of native Java libraries. WebLogic Server provides a pure-Java implementation of the SSL protocol: native Java libraries enhance the performance for SSL operations on the Solaris, Windows NT, and IBM AIX platforms. By default, this attribute is not enabled.
Handler Enabled	Specifies whether or not WebLogic Server rejects SSL connections that fail client authentication for one of the following reasons: The requested client digital certificate was not furnished. The client did not submit a digital certificate. The digital certificate from the client was not issued by a certificate authority specified by the Trusted CA Filename attribute. By default, the SSL Handler allows one WebLogic Server instance to make outgoing SSL connections to another WebLogic Server instance. For example, an EJB in a WebLogic Server may open an HTTPS stream on another Web server. With the HandlerEnabled attribute enabled, WebLogic Server acts as a client in an SSL connection. By default this attribute is enabled. Disable this attribute only if you want to provide your own implementation for outgoing SSL connections. Note: The SSL Handler has no effect on the ability of WebLogic Server to manage incoming SSL connections.
Export Key Lifespan	Number of times WebLogic Server uses an exportable key between a domestic server and an exportable client before generating a new one. The more secure you want WebLogic Server to be, the fewer times the key should be used before a new one is generated. The default is to use it 500 times.
Login Timeout Millis	Number of milliseconds that WebLogic Server should wait for an SSL connection before timing out. SSL connections take longer to negotiate than regular connections. If clients are connecting over the Internet, raise the default number to accommodate additional network latency. The default value is 25,000 milliseconds.
Certificate Cache Size	Number of digital certificates that are tokenized and stored by WebLogic Server. The default is 3.
Ignore HostName Verification	Disables the default Host Name Verifier. The Host Name Verifier compares the Subject DN of a digital certificate to the host name of the server that initiated the SSL connection. Check this attribute if you do not want host name verification performed (for example, if you are using the demonstration digital certificates shipped with WebLogic Server). Disabling this attribute leaves WebLogic Server vulnerable to man-in-the-middle attacks. BEA does not recommend using the demonstration digital certificates or disabling host name verification in any type of production environment.
HostName Verifier	Name of the Java class that implements the Host Name Verifier interface. For more information about using the weblogic.security.SSL.HostNameVerifier interface, see Using a Custom HostName Verifier.

 

Note: In previous releases of WebLogic Server, it was possible to define digital certificates that were self-signed and not validated in the Server Certificate File Name attribute (or in the weblogic.security.certificate.server property). This was not a good security policy. Now WebLogic Server requires that both the Server Certificate File Name and the Server Certificate Chain File Name attributes be defined.

Using PKCS#7 Files

PKCS#7 files can be used with WebLogic Server. However, the certificate chain in the file must be separated into individual pb7 format files, convert the pb7 files to PEM format, and append the files into a single PEM file. Each PKCS#7 file has the following parts:

• Certificate information in plain text

• The digital certificate for the server

• The trusted CA certificate for the certificate authority that issued the digital certificate for the server

The digital certificate for the server and the trusted CA certificate need to be separated into pb7 files.

Before performing the steps in this section, verify that the file is PKCS#7 format by opening the file in a text editor and locating the following information:

"Base 64 encoded certificate with CA certificate chain in pkcs7 format"

To use the PKCS#7 file with WebLogic Server:

1. Open the PKCS#7 file in a text editor.

2. Copy the digital certificate for the server and the trusted CA certificate in the PKCS#7 file into separate p7b files (for example, servername.p7b and CA.p7b).

3. In Windows Explorer on Windows 2000, click one of the p7b files.

   A Certificates window appears.

4. In the left pane of the Certificates window, select the p7b file you want to convert.

5. Select the Certificates option.

6. The Certificate Export wizard appears.

7. Click Next.

8. Select the Base64 Encoded Cert option (exports PEM formats).

9. Click Next.

10. Enter a name for the converted digital certificate.

11. Click Finish.

    The resulting file is in PEM format.

12. Perform steps 3-11 for the other pb7 file.

13. Open a text editor and include both the PEM files into a single PEM file. The order is important (include the files in the order of trust). The server digital certificate should be the first digital certificate in the file. The trusted CA certificate should be the next file.

    You cannot have blank lines between digital certificates.

Modifying Parameters for SSL Session Caching

As of WebLogic Server 6.1 Service Pack 2, the SSL code includes parameters for SSL session caching. Using a cached SSL session eliminates the need for the connection to go through the SSL handshake again. The connection can simply pick up where it left off. By using a cached SSL session, an application significantly reduces the time spent establishing SSL connections, greatly improving performance. To use a cached SSL session, both the client and the server must have the ability to do SSL session caching. All browsers have the ability to do SSL session-caching.

The server-session caching is saved in the TTL Cache. For more information about TTL Cache, see Configuring the Caching Realm. The client-side SSL session cache will only hold one SSL session on the thread of execution.

SSL session caching is turned on by default. You can modify the server-session caching default size and time-to-live by using the following command line flags:

-Dweblogic.security.SSL.sessionCache.size=211
-Dweblogic.security.SSL.sessionCache.ttl=600

Table 14-19 Parameters

parameters	min	max	default
sessionCache.size	1	65537	211
sessionCache.ttl	1	max Integer.MAX_VALUE	600

 

---

Configuring Mutual Authentication

When WebLogic Server is configured for mutual authentication, clients are required to present their digital certificates to WebLogic Server, which validates digital certificates against a list of trusted certificate authorities.

To configure your WebLogic Server for the SSL protocol and certificate authentication, complete the procedures in Configuring the SSL Protocol section.

Copy the root certificates for the certificate authorities to be used by WebLogic Server to the \wlserver6.1\config\ directory. During mutual authentication, clients are required to present a digital certificate issued by one of these trusted certificate authorities.

To configure mutual authentication, select the Client Certificate Enforced option on the SSL tab in the Server Configuration window of the Administration Console. By default, this option is not enabled.

 

---

Configuring RMI over IIOP with SSL

You can use the SSL protocol to protect IIOP connections to RMI remote objects. The SSL protocol secures connections through authentication and encrypts the data exchanged between objects. To use the SSL protocol to protect RMI over IIOP connections, do the following:

1. Configure WebLogic Server to use the SSL protocol. For more information, see Defining Attributes for the SSL Protocol

2. Configure the client Object Request Broker (ORB) to use the SSL protocol. Refer to the product documentation for your client ORB for information about configuring the SSL protocol.

3. Use the host2ior utility to print the WebLogic Server IOR to the console. The host2ior utility prints two versions of the interoperable object reference (IOR), one for SSL connections and one for non-SSL connections. The header of the IOR specifies whether or not the IOR can be used for SSL connections.

4. Use the SSL IOR when obtaining the initial reference to the CosNaming service that accesses the WebLogic Server JNDI tree.

For more information about using RMI over IIOP, see Programming WebLogic RMI Over IIOP.

 

---

Protecting Passwords

It is important to protect the passwords that are used to access resources in WebLogic Server. In the past, usernames and passwords were stored in clear text in a WebLogic Server security realm. Now WebLogic Server hashes all passwords. When WebLogic Server receives a client request, the password presented by the client is hashed and WebLogic Server compares it to the already hashed password for matching.

Each filerealm.properties file has an associated SerializedSystemIni.dat file that is used to hash the passwords. During installation, the SerializedSystemIni.dat file is put in the \wlserver6.1\config\ directory.

If for any reason the SerializedSystemIni.dat file is corrupted or destroyed, you must reconfigure WebLogic Server.

Take the following precautions:

• Make a backup copy of the SerializedSystemIni.dat file and put it in the same location as a copy of its associated filerealm.properties file.

• Set the permissions on the SerializedSystemIni.dat file protections such that the administrator of the WebLogic Server deployment has write and read privileges and no other users have any privileges.

• If you have a weblogic.properties file with passwords that you want to hash, use the Convert weblogic.properties option on the main window in the Administration Console to convert the weblogic.properties file to a config.xml file. Once the file is converted, all existing passwords are protected.

The config.xml file no longer has clear text passwords. In place of clear text passwords, the config.xml file has encrypted, hashed passwords. You cannot copy encrypted passwords from one domain to another. Instead, you can edit the config.xml file and replace the existing encrypted and hashed passwords with clear text passwords and then copy the file to the new domain. The Administration Console will encrypt and hash the passwords the next time it writes to the file.

Password guessing is a common type of security attack. In this type of attack, a hacker attempts to log in to a computer using various combinations of usernames and passwords. WebLogic Server has strengthened its protection against password guessing by providing a set of attributes designed to protect passwords.

To protect the passwords in your WebLogic Server deployment, you must perform the following steps:

1. Open the Administration Console.

2. Click on the Security node.

3. In the right pane of the Administration Console, click on the Passwords tab.

4. Define the desired attributes on this tab by entering values at the appropriate prompts and selecting the required checkboxes. (For details, see the following table).

5. Click the Apply button to save your choices.

6. Reboot WebLogic Server.

The following table describes each attribute on the Passwords tab.

Table 14-20 Password Protection Attributes

Attribute	Description
Minimum Password Length	Number of characters required in a password. Passwords must contain a minimum of 8 characters. The default is 8.
Lockout Enabled	Requests the locking of a user account after invalid attempts to log in to that account exceed the specified Lockout Threshold. By default, this attribute is enabled.
Lockout Threshold	Number of failed password entries for a user that can be tried to log in to a user account before that account is locked. Any subsequent attempts to access the account (even if the username/password combination is correct) raise a Security exception; the account remains locked until it is explicitly unlocked by the system administrator or another login attempt is made after the lockout duration period ends. Invalid login attempts must be made within a span defined by the Lockout Reset Duration attribute. The default is 5.
Lockout Duration	Number of minutes that a user's account remains inaccessible after being locked in response to several invalid login attempts within the amount of time specified by the Lockout Reset Duration attribute. In order to unlock a user account, you need to have the unlockuser permission for the weblogic.passwordpolicy. The default is 30 minutes.
Lockout Reset Duration	Number of minutes within which invalid login attempts must occur in order for the user's account to be locked. An account is locked if the number of invalid login attempts defined in the Lockout Threshold attribute happens within the amount of time defined by this attribute. For example, if the value in this attribute is five minutes and three invalid login attempts are made within a six-minute interval, then the account is not locked. If five invalid login attempts are made within a five-minute period, however, then the account is locked. The default is 5 minutes.
Lockout Cache Size	Specifies the intended cache size of unused and invalid login attempts. The default is 5.

 

 

---

Installing an Audit Provider

WebLogic Server enables you to create an audit provider to receive and process notifications of security events such as authentication requests, failed or successful authorization attempts, and receipt of invalid digital certificates.

To use an audit provider, you create an implementation of the weblogic.security.audit.AuditProvider interface. Then use the Administration Console to install and activate your implementation.

To install an audit provider, enter the name of your implementation of the AuditProvider class in the Audit Provider Class attribute on the General tab under the Security node in the Administration Console. Reboot WebLogic Server.

For more information about writing an audit provider, see Auditing Security Events. For an example of creating a connection filter, see the LogAuditProvider example in the \samples\examples\security directory of the WebLogic Server installation.

 

---

Installing a Connection Filter

You can create connection filters that allow you to reject or accept client connections based on a client's origin and protocol. After the client connects, and before any work is performed on its behalf, WebLogic Server passes the client's IP number and port, protocol (HTTP, HTTPS, T3, T3S, or IIOP), and WebLogic Server port number to the connection filter. By examining this information, you can choose to allow the connection or throw a FilterException to terminate it.

To use a connection filter, you must first create an implementation of the weblogic.security.net.ConnectionFilter interface. Then use the Administration Console to install your implementation.

To install a connection filter, enter the name of your implementation of the weblogic.security.net.ConnectionFilter interface, in the Connection Filter attribute on the Advanced tab under Security in the Administration Console. Reboot WebLogic Server.

For information about writing a connection filter, see Filtering Network Connections. For an example of creating a connection filter, see the SimpleConnectionFilter example in the \samples\examples\security directory of the WebLogic Server installation.

 

---

Setting Up the Java Security Manager

When you run WebLogic Server under Java 2 (JDK 1.2 or 1.3), WebLogic Server can use the Java Security Manager in Java 2 to provide additional access control for WebLogic Server resources. The Java Virtual Machine (JVM) has security mechanisms built into it that you which manage through a security policy file. The Java Security Manager can enforce a set of permissions granted to CodeSource or SignedBy classes. The permissions allow certain classes running in that instance of the JVM to do or not do certain runtime operations. In many cases, where the threat model does not include malicious code being run on the JVM, the Java Security Manager is unnecessary. In cases such as when an Application Service Provider uses WebLogic Server and unknown classes are being run, the Java Security Manager is necessary.

Note: In pre-6.0 releases of WebLogic Server, you enabled the Java Security Manager by using the -Dweblogic.security.manager property when starting WebLogic Server. Please note the change in the property for WebLogic Server version 6.0 and greater.

To use the Java Security Manager with WebLogic Server, specify the -Djava.security.manager property when starting WebLogic Server.

The Java Security Manager uses a security policy file that defines permissions. The full pathname of security policy is specified in the -Djava.security.policy property when you start WebLogic Server. If you enable the Java Security Manager but do not specify a security policy file, the Java Security Manager uses the default security policies defined in the java.security and java.policy files in the $JAVA_HOME/lib/security directory.

WebLogic Server includes an example security policy file named weblogic.policy. This file contains a set of default permissions.

To use the Java Security Manager security policy file with your WebLogic Server deployment:

1. Edit the following lines in the weblogic.policy file, replacing the specified location with the location of your WebLogic Server installation:

   grant codebase "file://BEA/-"{
   

     permission java.io.FilePermission "D:${/}BEA${/}=", ...
   

Note: This change assumes your installation directory structure is the same as the one described in the BEA WebLogic Server Installation Guide.

1. If you want to run the Administration Console, add the following grant block and permissions to the weblogic.policy file:

   grant {
   

   	    permission java.io.FilePermission     
   "D:{/}BEA${/}wlserver6.1${/}weblogic${/}management${/}console${
   /}-", "read";
   

   	    permission java.io.FilePermission     
   "D:{/}BEA${/}wlserver6.1${/}config${/}${/}applications${/}.wl_t
   emp_do_not_delete${/}weblogic${/}management${/}console${/}-", 
   "read";
   

   	    permission java.util.PropertyPermission   "user.*",   "read";
   

   	   };
   

2. If you have extra directories in your CLASSPATH or if you are deploying applications in extra directories, add specific permissions for those directories to your weblogic.policy file.

3. BEA recommends taking the following precautions:

   • Make a backup copy of the weblogic.policy file and put the backup copy in a secure location.

   • Set the permissions on the weblogic.policy file such that the administrator of the WebLogic Server deployment has write and read privileges and no other users.

4. To use the Java Security Manager and the weblogic.policy file with your WebLogic Server deployment, use the following properties when starting WebLogic Server:

   $java... -Djava.security.manager\
   

   -Djava.security.policy==D:/BEA/wlserver6.1/lib/weblogic.policy
   

Caution: The Java security manager is partially disabled during the booting of Administration and Managed Servers. During the boot sequence, the current Java security manager is disabled and replaced with a variation of the Java security manager that has the checkRead() method disabled. While disabling this method greatly improves the performance of the boot sequence, it also minimally diminishes security. The startup classes for WebLogic Server are run with this partially disabled Java security manager and therefore the classes need to be carefully scrutinized for security considerations involving the reading of files.

For more information about the Java Security Manager, see the Javadoc shipped with Java 2.

 

---

Modifying the weblogic.policy File for Third Party or User-Written Classes

The best location for your server-side user code is the weblogic/myserver/serverclasses directory. If you have third party or user-written classes that are not in that directory, perform the following steps to protect them:

1. Copy the entire block of code in the weblogic.policy file from "grant codeBase..." to the closing bracket and semicolon.

2. Paste the selection back into the weblogic.policy file below the section you just copied.

3. Edit the grant codeBase and the permission.java.io.FilePermission statements so that the directories point to the location of your third party or user-written code.

This procedure creates a security policy for your code that contains exactly the same permissions as those for WebLogic Server. You should examine these permissions closely to make sure that this is the security policy you want for those directories.

Caution: JavaSoft JDK version 1.2.1 on UNIX systems applies security policies improperly if your WebLogic Server software is not installed in the root directory of the file system or disk drive. Policy is only applied correct if the path in a grant codeBase URL has just one component. For example, if you install WebLogic Server in c:\test\weblogic (or even /home/weblogic on Solaris), you will see AccessControlException even though you use the correct URL in your security policy file.

To workaround this limitation, you can either install WebLogic in the root directory (recommended) or modify the URL so that it contains only the first component of the path to your WebLogic installation. For example:

grant codeBase "file:/c:/test/" {

Problems occur when using the "/-" in the specified URL. This problem has been acknowledged by Sun Microsystems as bug #4261298, but they have determined that this is not a bug in the JDK. They state, "when a path is trailed with "/-" it means that the element preceding it is a directory and that grant functions for all elements below it. It does not mean that you can read the directory itself." The workaround for this nuance is to add an additional FilePermission entry that consists of just the directory itself (with no trailing "/-').

 

---

Using the Recording Security Manager Utility

The Recording Security Manager utility can be used to detect permission problems that occur when starting and running WebLogic Server. The utility outputs permissions that can be added to your security policy file to resolve the permission problems that the utility finds. The Recording Security Manager is available at the BEA Developer's Center.

 

---

Configuring Security Context Propagation

Security context propagation enables Java applications running in a WebLogic Server environment to access objects and operations in BEA Tuxedo domains. The BEA WebLogic Enterprise Connectivity component of WebLogic Server provides the security context propagation capability.

With security context propagation, the security identity of a User defined in a WebLogic Server security realm is propagated as part of the service context of an Internet Inter-ORB Protocol (IIOP) request sent to the BEA Tuxedo domain over a network connection that is part of a WLEC connection pool. Each network connection in the WLEC connection pool has been authenticated using a defined User identity.

To use security context propagation, create a WLEC connection pool for each BEA Tuxedo domain you want to access from WebLogic Server. WebLogic Server populates each WLEC connection pool with IIOP connections. Java applications in a WebLogic Server environment obtain IIOP connections from a WLEC connection pool and use those connections to call objects and invoke operations in BEA Tuxedo domains.

Before using security context propagation, add TUXDIR/lib/wleorb.jar and TUXDIR/lib/wlepool.jar to the CLASSPATH variable in the startAdminWebLogic.sh or startAdminWebLogic.cmd file.

For more information, see Using WebLogic Enterprise Connectivity..

To implement security context propagation:

1. Go to the Services—>WLEC node in the left pane of the Administration Console.

2. In the right pane of the Administration Console, click the Create a new WLEC Connection Pool link.

3. Define the attributes in the following table:

   Table 14-21 WLEC Connection Pool Attributes on the General Tab

   Attribute	Description
   Name	Name of the WLEC connection pool. The name must be unique for each WLEC connection pool.
   Primary Addresses	A list of addresses for IIOP Listener/Handlers that can be used to establish a connection between the WLEC connection pool and the BEA Tuxedo domain. The format of each address is //hostname:port. The addresses must match the ISL addresses defined in the UBBCONFIG file. Multiple addresses are separated by semicolons. For example: //main1.com:1024; //main2.com:1044. To configure the WLEC connection pool to use the SSL protocol, use the corbalocs prefix with the address of the IIOP Listener/Handler. For example: corbalocs://hostname:port.
   Failover Addresses	A list of addresses for IIOP Listener/Handlers that are used if connections cannot be established with the addresses defined in the Primary Addresses attribute. Multiple addresses are separated by semicolons. This attribute is optional.
   Domain	Name of the BEA Tuxedo domain to which this WLEC connection pool connects. You can have only one WLEC connection pool per BEA Tuxedo domain. The domain name must match the domainid parameter in the RESOURCES section of the UBBCONFIG file for the BEA Tuxedo domain.
   Minimum Pool Size	Number of IIOP connections to be added to the WLEC connection pool when WebLogic Server starts. The default is 1.
   Maximum Pool Size	Maximum number of IIOP connections that can be made from the WLEC connection pool. The default is 1.

   
    

4. Click the Create button.

5. Propagate the security context for a User in a WebLogic Server security realm to a BEA Tuxedo domain by defining the attributes on the Security tab in the WLEC Connection Pool Configuration window in the Administration Console. The following table describes these attributes.

   Table 14-22 WLEC Connection Pool Attributes on the Security Tab

   Attribute	Description
   User Name	A BEA Tuxedo user name. Required only when the security level in the BEA Tuxedo domain is USER_AUTH, ACL or MANDATORY_ACL.
   User Password	Password for the User defined in the User Name attribute. Required only when you define the User Name attribute.
   User Role	BEA Tuxedo user role. This attribute is required when the security level in the BEA Tuxedo domain is APP_PW, USER_AUTH, ACL, or MANDATORY_ACL.
   Application Password	BEA Tuxedo application password. Required when the security level in the BEA Tuxedo domain is APP_PW, USER_AUTH, ACL, or MANDATORY_ACL.
   Minimum Encryption Level	Minimum SSL encryption level used between the BEA Tuxedo domain and WebLogic Server. The possible values are 0, 40, 56, and 128. Zero (0) indicates that the data is signed but not sealed. 40, 56, and 128 specify the length, in bits, of the encryption key. If the minimum level of encryption is not met, the SSL connection between BEA Tuxedo and WebLogic Server fails. The default is 40.
   Maximum Encryption Level	Maximum SSL encryption level used between the BEA Tuxedo domain and WebLogic Server. The possible values are 0, 40, 56, and 128. Zero (0) indicates that the data is signed but not sealed. 40, 56, and 128 specify the length, in bits, of the encryption key. If the minimum level of encryption is not met, the SSL connection between BEA Tuxedo and WebLogic Server fails. The default is the maximum level allowed by the Encryption Package kit license.
   Enable Certificate Authentication	Enables the use of certificate authentication. By default certificate authentication is disabled.
   Enable Security Context	Enables the passing of the security context of the WebLogic Server User passed to the BEA Tuxedo domain. By default, security context is disabled.

   
    

6. To save your changes, click the Apply button and reboot WebLogic Server.

7. Run the tpusradd command to define the WebLogic Server User as an authorized User in the WebLogic Enterprise domain.

8. Set the -E option of the ISL command to configure the IIOP Listener/Handler to detect and utilize the propagated security context from the WebLogic Server realm. The -E option of the ISL command requires you to specify a principal name. The principal name defines the principal used by the WLEC connection pool to log in to the WebLogic Enterprise domain. The principal name should match the name defined in the User Name attribute when creating a WLEC connection pool.

Using certificate authentication between the WebLogic Server environment and the BEA Tuxedo environment implies performing a new SSL handshake when establishing a connection from the WebLogic Server environment to a BEA Tuxedo CORBA object. To support multiple client requests over the same SSL network connection, you must set up certificate authentication so that it operates as follows:

1. Obtain a digital certificate for the WebLogic Server User and put the private key in the TUXDIR/udataobj/security/keys directory of BEA Tuxedo.

2. In the UBBCONFIG file for the BEA Tuxedo CORBA application, use the tpusradd command to define the WebLogic Server User as a BEA Tuxedo user.

3. Define the IIOP Listener/Handler in the UBBCONFIG file with the -E option to indicate the WebLogic Server User is to be used for authentication.

4. Define the WebLogic Server User name in the User Name attribute when creating a WLEC Connection pool in the Administration Console of WebLogic Server.

5. Obtain a digital certificate for the IIOP Listener/Handler.

6. Specify the digital certificate in the SEC_PRINCIPAL_NAME option of the ISL command and use the -S option to indicate that a secure port should be used for communication between the BEA Tuxedo domain and the WebLogic Server security realm.

For more information about the UBBCONFIG file, see Creating a Configuration File in the BEA Tuxedo documentation.

For more information about the corbalocs prefix, see Understanding the Address Formats of the Bootstrap Object in the BEA Tuxedo documentation.

For information about BEA Tuxedo security levels, see Defining a Security Level in the BEA Tuxedo documentation.

 

---

SSL Certificate Validation

In previous releases, WebLogic Server did not ensure each certificate in a certificate chain was issued by a certificate authority. This problem meant anyone could get a personal certificate from a trusted CA, use that certificate to issue other certificates and WebLogic Server would not detect the invalid certificates. A patch (CR090101_610sp4) was made so that all X509 V3 CA certificates used with WebLogic Server must have the Basic Constraint extension defined as CA thus ensuring all certificates in a certificate chain were issued by a certificate authority. By default, any CA certificates not meeting this criteria are rejected. This section provides installation instructions for the patch and describes the command-line argument that controls the level of certificate validation.

Installation Instructions

To install patch CR090101_610sp4:

1. Backup the current WebLogic Server installation. If any of the following files were changed, the changes will be lost when the patch is installed onto the current WebLogic Server installation:

   %WL_HOME%\common\nodemanager\config\democert.pem
   

   %WL_HOME%\common\nodemanager\config\demokey.pem
   

   %WL_HOME%\samples\server\config\examples\demo.crt
   

   %WL_HOME%\samples\server\config\examples\democert.pem
   

   %WL_HOME%\samples\server\config\examples\demokey.pem
   

   %WL_HOME%\samples\server\examples\trusted.crt
   

   %WL_HOME%\samples\server\config\petstore\demo.crt
   

   %WL_HOME%\samples\server\config\petstore\democert.pem
   

   %WL_HOME%\samples\server\config\petstore\demokey.pem
   

   %WL_HOME%\samples\server\config\petstore\trusted.crt
   

   %WL_HOME%\server\lib\cacerts
   

   %WL_HOME%\server\lib\demo.crt
   

   %WL_HOME%\server\lib\trusted.crt
   

   Generally these files have not be modified. However, if you modified these files you will need to decide how to proceed with installing the updated certificates, private keys, and keystores from the patch. For example, you may decide to only select and install the service pack JAR files from the patch.

2. Unzip the contents of the zip files for the patch starting at WL_HOME and retaining the directory structure in the zip file.

   The following files are added to the WebLogic Server installation:

   %WL_HOME%\server\lib\CR090101_610sp4_.jar
   

   The following files in the WebLogic Server installation are modified:

   %WL_HOME%\common\nodemanager\config\democert.pem
   

   %WL_HOME%\common\nodemanager\config\demokey.pem
   

   %WL_HOME%\samples\server\config\examples\demo.crt
   

   %WL_HOME%\samples\server\config\examples\democert.pem
   

   %WL_HOME%\samples\server\config\examples\demokey.pem
   

   %WL_HOME%\samples\server\examples\trusted.crt
   

   %WL_HOME%\samples\server\config\petstore\demo.crt
   

   %WL_HOME%\samples\server\config\petstore\democert.pem
   

   %WL_HOME%\samples\server\config\petstore\demokey.pem
   

   %WL_HOME%\samples\server\config\petstore\trusted.crt
   

   %WL_HOME%\server\lib\cacerts
   

   %WL_HOME%\server\lib\demo.crt
   

   %WL_HOME%\server\lib\trusted.crt
   

   To avoid name conflicts, the new demo CA certificates have Subject DNs that differ from existing demo CA certificates. The modified Subject DN also makes it easier to differentiate between old and new certificate chains. New demo and demo1024 CA certificates have Constraints in the Common Name of their Subject DN.

   If you only have the end entity certificate, you can also tell whether it is old or new by looking at the Issuer DN.

3. Update the environment scripts for WebLogic Server to include the JAR files for the patch.

   • On Windows NT, edit the following files:

     %WL_HOME%\server\bin\setWLSEnv.cmd

     %WL_HOME%\server\bin\startWLS.cmd

     %WL_HOME%\server\bin\startNodeManager.cmd

     Add the following to the CLASSPATH before the weblogic_sp.jar:

     %WL_HOME%\server\lib\CR090101_610sp4_webservice.jar;
%WL_HOME%\server\lib\CR090101_610sp4_.jar;

   • On UNIX, edit the following files:

     $WL_HOME/server/bin/setWLSEnv.sh

     $WL_HOME/server/bin/startWLS.sh

     $WL_HOME/server/bin/startNodeManager.sh

     Add the following to the CLASSPATH before the weblogic_sp.jar :

     $WL_HOME/server/lib/CR090101_610sp4_webservice.jar;
$WL_HOME/lib/CR090101_610sp4.jar;

4. Using the files from the patch, update the certificates, private keys, and keystores in existing domains.

Older unpatched applications will not trust the new demo CA certificates that are installed by this patch. For example, a client that is still trusting the old demo CA certificate, will reject a server that has a new demo certificate chain. Resolve this problem by updating the client's trusted CA list to include the new demo CA supplied by this patch.

Controlling the Level of Certificate Validation

By default WebLogic Server will reject any certificates in a certificate chain that do not have the Basic Constraint extension defined as CA. However, you may be using certificates that do not meet this requirement or you may want to increase the level of security to conform to the IETF RFC 2459 standard. Use the following command-line argument to control the level of certificate validation performed by WebLogic Server:

-Dweblogic.security.SSL.enforceConstraints

Table  14-23 describes the options for the command-line argument.

Table 14-23 Options for -Dweblogic.security.SSL.enforceConstraints

Option	Description
strong or true	Use this option to check that the Basic Constraints extension on the CA certificate is defined as CA. For example: -Dweblogic.security.SSL.enforceConstraints=strong or -Dweblogic.security.SSL.enforceConstraints=true By default, WebLogic Server performs this level of certificate validation.
strict	Use this option to check the Basic Constraints extension on the CA certificate is defined as CA and set to critical. This option enforces the IETF RFC 2459 standard. For example: -Dweblogic.security.SSL.enforceConstraints=strict This option is not the default because a number of commercially available CA certificates do not conform to the IETF RFC 2459 standard.
off	Use this option to disable certificate validation. Use this option carefully. For example, if you purchased CA certificates from a reputable commercial certificate authority and the certificates do not pass the new validation, use this option. However, CA certificates from most commercial certificate authorities should work with the default strong option. For example: -Dweblogic.security.SSL.enforceConstraints=off BEA does not recommend use this option in production environment. Instead, purchase new CA certificates that comply with the IETF RFC 2459 standard.

 
 

Checking Certificate Chains

WebLogic Server provides a ValidateCertChain command-line utility to check whether or not an existing certificate chain will be rejected by WebLogic Server. The utility uses certificate chains from PEM files, PKCS-12 files, PKCS-12 keystores, and JDK keystores. A complete certificate chain must be used with the utility. The following is the syntax for the ValidateCertChain command-line utility:

java utils.ValidateCertChain -file pemcertificatefilename
java utils.ValidateCertChain -pem pemcertificatefilename
java utils.ValidateCertChain -pkcs12store pkcs12storefilename
java utils.ValidateCertChain -pkcs12file pkcs12filename password
java utils.ValidateCertChain -jks alias storefilename [storePass]

Example of valid certificate chain:

java utils.ValidateCertChain -pem zippychain.pem

Cert[0]: CN=zippy,OU=FOR TESTING
ONLY,O=MyOrganization,L=MyTown,ST=MyState,C=US

Cert[1]: CN=CertGenCAB,OU=FOR TESTING
ONLY,O=MyOrganization,L=MyTown,ST=MyState,C=US

Certificate chain appears valid

Example of invalid certificate chain:

java utils.ValidateCertChain -jks mykey mykeystore

Cert[0]: CN=corba1,OU=FOR TESTING ONLY, 
O=MyOrganization,L=MyTown,ST=MyState,C=US

CA cert not marked with critical BasicConstraint indicating it is 
a CA
Cert[1]: CN=CACERT,OU=FOR TESTING ONLY, 
O=MyOrganization,L=MyTown,ST=MyState,C=US

Certificate chain is invalid

Troubleshooting Problems with Certificates

If SSL communications were working before the patch but are failing after installing the patch, the problem is mostly likely because the certificate chain used by WebLogic Server is failing the validation.

Determine where the certificate chain is being rejected, and decide whether to update the certificate chain with one that will be accepted or change the setting of the -Dweblogic.security.SSL.enforceConstraints command-line argument.

To troubleshoot problems with certificates, use one of the following methods:

• If you know where the certificate chains for the processes using SSL communication are located, use the ValidateCertChain command-line utility to check whether the certificate chains will be accepted.

• Turn on SSL debug tracing on the processes using SSL communication. The syntax for SSL debug tracing is:

  -Dssl.debug=true -Dweblogic.StdoutDebugEnabled=true

  The following message indicates the SSL failure is due to problems in the certificate chain:

  <CA certificate rejected. The basic constraints for a CA certificate were not marked for being a CA, or were not marked as critical>

  When using one-way SSL, look for this error in the client log. When using two-way SSL, look for this error in the client and server logs.