Managing Security

 

This section discusses the following topics:

• Overview of Configuring Security

• Changing the System Password

• Specifying a Security Realm

• Defining Users

• Defining Groups

• Defining a Group for a Virtual Host

• Defining ACLs

• Configuring the SSL Protocol

• Configuring Mutual Authentication

• Configuring RMI over IIOP over SSL

• Protecting Passwords

• Installing an Audit Provider

• Installing a Connection Filter

• Configuring Security Context Propagation

• Setting Up the Java Security Manager

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

Overview of Configuring Security

Implementing security in a WebLogic Server deployment largely consists of configuring fields 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, specify security-specific values for the following elements of your deployment:

• Realms

• Users and Groups

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

• SSL protocol

• Mutual authentication

• 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, we recommend the following procedure:

1. Change the system password to protect your WebLogic Server deployment.

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.

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

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

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 an optional but we recommend it.

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 we recommend it.

This section describes these configuration steps and the fields you set in the Administration Console. For a complete description of WebLogic Server security features, see Introduction to WebLogic Security and Security Fundamentals.

For information about setting the security fields in the Administration Console and detailed descriptions of each field, see the Administration Console Online Help.

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

For information about security in WebLogic web applications, see Deploying 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.0\config\mydomain directory. The specified password corresponds to the Administration server for the domain and all the managed servers associated with that Administration server.

The password is encrypted and is further protected when WebLogic Server applies a hash to it. To improve security, we recommend frequently changing the system password that was set during installation.

To change the system password, do the following:

1. Open the Users window in the Administration Console.

2. Enter system in the User field.

3. Enter a new password in the Password field.

4. Confirm the password.

When using 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. The new password is propagated to all the managed server in the domain. Remember the system password for a domain must match across all the servers in the domain.

Note: The Petstore and the ExampleServer domains still store the system password in a password.ini file. When using these domains, modify the system password by modifying the password information in the password.ini file.

Specifying a Security Realm

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

The following table describes each field on the Filerealm tab.

Table 12-1 File Realm Fields

Field	Description
Max Users	Specifies the maximum number of Users to be used with the File realm. The File realm is intended to be used with 10,000 or fewer Users. The minimum value for this field is 1 and the maximum value is 10,000. The default is 1,000.
Max Groups	Specifies the maximum number of Groups to be used with the File realm. The minimum value for this field is 1 and the maximum value is 10,000. The default is 1,000.
Max ACLs	Specifies the maximum number of ACLs to be used with the File realm. The minimum value for this field is 1 and the maximum value is 10,000. The default is 1,000.

If for any reason, fileRealm.properties is corrupted or destroyed, you must reconfigure all the security information for WebLogic Server. Therefore, we recommend 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 protections such that the administrator of the WebLogic Server deployment has write and read privileges and no other users have any privileges.

  Note: You should 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 fields for the desired realm and reboot WebLogic Server.

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

Configuring the Caching Realm

Note: All configuration instructions are based on the use of the Administration Console.

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, 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 but caching is not enabled. You have to enable caching through the Administration Console.

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) fields 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 fields determine how long a cached object is valid. The higher you set these fields, 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, you must 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 secondary 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 field. When this field 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.

Configuring the Caching realm involves enabling various types of caches (such as ACL, Authentication, Group, and Permission) and defining how each cache operates. To do these tasks, define values for the field shown on the General tab in the Caching Realm Configuration window. To save your changes, click the Apply button. When you have finished defining the fields, reboot WebLogic Server.

The following table describes each field on the General tab.

Table 12-2 Caching Realm Fields

Field	Description
Name	Displays the active security realm. This field can not be changed.
Basic Realm	The name of the class for the alternate security realm or custom security realm being used with the Caching realm.
Case Sensitive Cache	Defines whether the specified security realm is case-sensitive. By default, this field 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 field.

To enable and configure the ACL cache, define values for the fields shown on the ACL tab in the Caching Realm Configuration window. To save your changes, click the Apply button. When you have finished defining the fields, reboot WebLogic Server.

The following table describes each field on the ACL tab.

Table 12-3 ACL Cache Fields

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

To enable and configure the Authentication cache, define values for the fields shown on the Authentication tab in the Caching Realm Configuration window. To save your changes, click the Apply button. When you have finished defining the fields, reboot WebLogic Server.

The following table describes each field on the Authentication tab.

Table 12-4 Authentication Cache Fields

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

To enable and configure the Group cache, define values for the fields shown on the Groups tab in the Caching Realm Configuration window. To save your changes, click the Apply button. When you have finished defining the fields, reboot WebLogic Server.

The following table describes each field on the Group tab.

Table 12-5 Group Cache Fields

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

To enable and configure the User cache, define values for the fields shown on the User tab in the Caching Realm Configuration window. To save your changes, click the Apply button. When you have finished defining the fields, reboot WebLogic Server.

The following table describes each field on the User tab.

Table 12-6 User Cache Fields

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

To enable and configure the Permission cache, define values for the field shown on the Permission tab in the Caching Realm Configuration window. To save your changes, click the Apply button. When you have finished defining the fields, reboot WebLogic Server.

The following table describes each field on the Permission tab.

Table 12-7 Permission Cache Fields

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

Configuring the LDAP Security Realm

Note: The LDAP security realm has been rewritten to provide improved performance and configurability. BEA recommends upgrading your WebLogic Server 6.0 installation to Service Pack 1.0 to take advantage of this functionality. WebLogic Server 6.0 Service Pack 1.0 is available from the BEA Systems Download page on the Web.

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 has been tested against the following LDAP servers:

• Open LDAP

• Netscape Directory Server

• Microsoft Site Server

Although BEA cannot committ to supporting LDAP servers that have not been tested, the implementation of the LDAP security realm in WebLogic Server should work with most LDAP servers.

Configuring the LDAP Security realm involves defining fields that enable the LDAP Security realm in WebLogic Server to communicate with the LDAP server and fields that describe how Users and Groups are stored in the LDAP directory.

Before you can use the LDAP Security realm, you need to enable the Caching Realm and enter the class name of the LDAP Security realm in the Basic Realm field.

To use the LDAP Security realm instead of the File realm, go to the SecurityRealms node in the left pane of the Administration Console. In the right pane of the Administration Console, click the Create a New LDAP Realm link.

To specify the name of the LDAP Security realm and the name of the class that contains the LDAP Security realm define values for the fields shown on the General tab in the LDAP Realm Create window. To save your changes, click the Apply button. When you have finished defining the fields, reboot WebLogic Server.

The following table describes each field n the General tab.

Table 12-8 LDAP Security Realm Fields on the General Tab

Field	Description
Name	The name of the LDAP Security realm such as AccountingRealm
Realm Class Name	The name of the Java class that contains the LDAP Security realm. The Java class should be included in the CLASSPATH of WebLogic Server.

To enable communication between the LDAP server and WebLogic Server define values for the fields shown on the LDAP tab in the LDAP Realm Create window. To save your changes, click the Apply button. When you have finished defining the fields, reboot WebLogic Server.

The following table describes each field on the General tab.

Table 12-9 LDAP Security Realm Fields on the LDAP Tab

Field	Description
LDAPURL	The 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. 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	The 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	The password that authenticates the LDAP User, as defined in the Principal field.
Enable SSL	Option for enabling the use of the SSL protocol to protect communications between the LDAP server and WebLogic Server. Keep in mind the following guidelines: Disable this field if the LDAP server is not configured to use the SSL protocol. If you set the UserAuthentication field to external, this field must be enabled.
AuthProtocol	The type of authentication used to authenticate the LDAP server. Set this field to one of the following values: None for no authentication Simple for password authentication CRAM-MD5 for certificate authentication Netscape Directory Server supports CRAM-MD5. Microsoft Site Server and Novell NDS support Simple.

To specify how Users are stored in the LDAP directory define the fields shown on the Users tab in the LDAP Realm Create window. To save your changes, click the Apply button. When you have finished defining the fields, reboot WebLogic Server.

The following table describes each field on the Users tab.

Table 12-10 LDAP Security Realm Fields on the Users Tab

Field	Description
User Authentication	Determines the method for authenticating Users. Set this field 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. When using Netscape Directory Server, this field needs to be set to Bind.
User Password Attribute	The password of the LDAP User.
User DN	A list of attributes that, when combined with the attributes in the User Name Attribute field, uniquely identifies an LDAP User.
User Name Attribute	The login name of the LDAP User. The value of this field can be the common name of an LDAP User but usually it is an abbreviated string, such as the User ID.

To specify how Groups are stored in the LDAP directory, assign values to the fields shown on the Groups tab in the LDAP Realm Create window. To save your changes, click the Apply button. When you have finished defining the fields, reboot WebLogic Server.

The following table describes each field on the Groups tab.

Table 12-11 LDAP Security Realm Field on the Groups Tab

Field	Description
Group DN	The list of attributes that, combined with the Group Name Attribute field, uniquely identifies a Group in the LDAP directory.
Group Name Attribute	The name of a Group in the LDAP directory. It is usually a common name.
Group Is Context	This Boolean checkbox specifies how Group membership is recorded in the LDAP directory. Check this checkbox if each Group entry contains one User. By default, the field is enabled. Uncheck this checkbox if there is one Group entry containing an attribute for each Group member.
Group Username Attribute	The name of the LDAP attribute that contains a Group member in a Group entry.

If you have enabled caching, 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 field 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 60 seconds for unsuccessful lookups and 10 seconds for successful lookups. Unless you change the TTL fields 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 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). The system User defined in WebLogic Server must also be declared in the Windows NT domain. On a Windows NT platform, WebLogic Server must be run under the system User account, and clients must supply the system User password to authenticate successfully. When you define the system User account in Windows NT, make sure the owner of the account has administrative privileges and can read security-related information from the Windows NT Domain controller.

To use the Windows NT Security realm, you must run WebLogic Server as a Windows NT Service on a computer in the Windows NT domain. You do not have to run WebLogic Server on a domain controller.

Because WebLogic Server reads ACLs from the fileRealm.properties file at startup time, you must restart WebLogic Server after you change an ACL. If you use Groups with your ACLs, you can reduce the frequency with which you must restart WebLogic Server. Changing the members of a Windows NT Group allows you to manage individual Users' access to WebLogic Server resources dynamically.

Before you can use the Windows NT Security realm, you need to enable the Caching Realm and enter the class name of the Windows NT Security realm in the Basic Realm field.

To use the Windows NT Security realm instead of the File realm, go to the SecurityRealms node in the left pane of the Administration Console. In the right pane of the Administration Console, click the Create a New NT Realm link.

Configuring the Windows NT Security realm involves setting fields 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 fields shown the NT Realm Create window of the Administration Console. To save your changes, click the Apply button. When you have finished defining the fields, reboot WebLogic Server.

The following table describes each field in the NT Realm Configuration window.

Table 12-12 Windows NT Security Realm Fields

Field	Description
Name	The name of the Windows NT Security realm, such as, AccountingRealm
Realm Class Name	The name of the Java class that implements the Windows NT Security realm. The Java class needs to be in the CLASSPATH of WebLogic Server.
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.

Once you have configured the Windows NT Security realm in the Administration Console, you need to define the system User in Windows NT:

1. Use the Administrator account to log on to the Windows NT domain you are using with WebLogic Server.

2. Go to ProgramsAdministrative Tools.

3. Select User Manager.

4. Define the system User.

5. Check the Show Advanced User Rights option.

6. Select the Act as part of the operating system option from the Rights pull-down menu.

7. Check the Add button.

8. Make sure the Windows NT PATH environment variable includes the \wlserver6.0\bin directory. (WebLogic Server loads the W1ntrealm.dll from this directory.)

Configuring the UNIX Security Realm

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. On some platforms, wlauth uses PAM (Pluggable Authentication Modules) which allows you to configure authentication services in the operating system without altering applications that use the service. On platforms for which PAM is not available, wlauth uses the standard login mechanism, including shadow passwords, where supported.

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.

Because WebLogic Server reads ACLs from the fileRealm.properties file at startup time, you must restart WebLogic Server after you change an ACL. If you use Groups with your ACLs, you can reduce the frequency with which you must restart WebLogic Server. Changing the members of a UNIX Group allows you to manage individual Users' access to WebLogic Server resources dynamically.

The wlauth program runs setuid root. You need root permissions to modify the ownership and file attributes on the wlauth program and to set up the PAM configuration file for wlauth.

Perform the following steps to configure the UNIX Security realm:

1. If WebLogic Server is installed on a network drive, copy the wlauth file to a file system on the computer that executes WebLogic Server, for example, the /usr/sbin directory. The wlauth file is in the weblogic/lib/arch directory, where arch is the name of your platform.

2. As the root user, run the following commands to change the wlauth owner and permissions:

     # chown root wlauth
     # chmod +xs wlauth

3. On PAM platforms (Solaris and Linux), set up the PAM configuration for wlauth.

   Solaris-Add the following lines to your /etc/pam.conf file:

     # Setup for WebLogic authentication on Solaris machines
     #
     wlauth auth required      /usr/lib/security/pam_unix.so.1 
     wlauth password required  /usr/lib/security/pam_unix.so.1 
     wlauth account required   /usr/lib/security/pam_unix.so.1

   Linux-Create a file called /etc/pam.d/wlauth containing the following:

     #%PAM-1.0
     #
     # File name:
     # /etc/pam.d/wlauth 
     #
     # If you do not use shadow passwords, delete "shadow".
     auth required     /lib/security/pam_pwdb.so shadow
     account required  /lib/security/pam_pwdb.so

   Note: Omit shadow if you are not using shadow passwords.

To use the UNIX Security realm instead of the File realm, go to the SecurityRealms node in the left pane of the Administration Console. In the right pane of the Administration Console, click the Create a New UNIX Realm link.

Before you can use the UNIX Security realm, you need to enable the Caching Realm and enter the class name of the UNIX Security realm in the Basic Realm field.

Configuring the UNIX Security realm involves setting fields 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 fields on the UNIX Realm Create window of the Administration Console. To save your changes, click the Apply button. When you have finished defining the fields, reboot WebLogic Server.

The following table describes each field in the UNIX Realm Create window.

Table 12-13 UNIX Security Realm Fields

Field	Description
Name	The name of the UNIX Security realm, such as, AccountingRealm
Realm Class Name	The name of the WebLogic class that implements the UNIX Security realm. The Java class needs to be in the CLASSPATH of WebLogic Server.
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.

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 can be managed through the Administration Console.

To use the RDBMS Security realm instead of the File realm, go to the SecurityRealms node in the left pane of the Administration Console. In the right pane of the Administration Console, click the Create a New RDBMS Realm link.

Before you can use the RDBMS Security realm, you need to enable the Caching Realm and enter the class name of the RDBMS Security realm in the Basic Realm field.

Configuring the RDBMS Security realm involves setting fields that define the JDBC driver being used to connect to the database and defining the schema used to store Users, Groups, and ACLs in the database.

To define these fields, you must specify values for the fields shown on three tabs of the RDBMS Realm Create window: the General tab, the Database tab, and the Schema tab. The following table describes each field that you must set on the General tab.

Table 12-14 RDBMS Security Realm Fields on the General Tab

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

The following table describes the fields you must set on the Database tab.

Table 12-15 RDBMS Security Realm Fields on the Database Tab

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

The Schema properties used to define the Users, Groups, and ACLs stored in the database are listed on the Schema tab. When you finish defining values for the necessary fields on each of the three tabs, save your changes by clicking the Apply button. Then 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, go to the SecurityRealms node in the left pane of the Administration Console. In the right pane of the Administration Console, click the Create a New Custom Realm link.

Before you can use a custom security realm, you need to enable the Caching Realm and enter the class name of the custom security realm in the Basic Realm field.

Configuring a custom security realm involves setting fields that define a name for the realm and the interface that implements the realm, and specifying information that defines how the Users, Groups, and optionally ACLs are stored in the custom security realm. To define this information, you must specify values for the fields of the Custom Realm Create window of the Administration Console. To save your changes, click the Apply button. When you have finished defining the fields, reboot WebLogic Server.

The following table describes the fields you must set on the Custom Security Realm Create window.

Table 12-16 Custom Security Realm Fields

Field	Description
Name	The name of the Custom Security realm, such as, AccountingRealm
Realm Class Name	The 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	The information needed to connect to the security store.

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

Testing an Alternate Security Realm or a Custom Security Realm

If you have started WebLogic Server with an alternate or a custom security realm, perform the following steps to ensure the realm is working properly:

1. Start the Administration Console. The Administration Console displays all the Users, Groups, and ACLs known in the security realm.

2. Use the Administration Console to add an ACL for the HelloWorld example servlet. Give a User and a Group in your security realm access to the HelloWorld example servlet. Select a Group that does not include the specified User.

3. Restart WebLogic Server and load the HelloWorld servlet with an ACL using the following URL:

     http://localhost:portnumber/helloWorld

   Try entering the username and password for a User who is not included in the ACL you added for the servlet. You should get a message telling you that you are not authorized to do so.

   Try entering the username and password of a User who is included in the ACL, either as an individual User or as a member of the Group. The servlet should load and display the Hello World message.

Migrating Security Realms

WebLogic Server 6.0 provides a new 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 support in WebLogic Server 6.0. 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 6.0 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 in Configuring 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 management tools provided in that realm to define a User.

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.

The following table describes the fields in the Users window.

Table 12-17 User Fields

Field	Description
Name	The name of a User, that is, an entity that will access WebLogic Server resources. Names are case-sensitive.
Password	The password for the User. The password must contain a minimum of 8 characters in length. Passwords are case-sensitive.

The File realm 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 is defined during the WebLogic Server installation procedure.

• The guest User is automatically provided by WebLogic Server. When authorization is not required, WebLogic Server assigns the guest identity to a client this 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.

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 improve the security of your WebLogic Server deployment, we recommend disabling the guest User. To do so, check the Guest Disabled option on the General tab in the Security window in the Administration Console. When you disable the guest User, the guest User is not deleted rather it just becomes unavailable so that no one can log on as the guest User.

To delete Users, enter the name of the User in the Remove These Users list box and click Remove.

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 explains 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.

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 used primarily to manage 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.

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

1. Setting the Name field in the Groups window of the Administration Console.

2. Clicking the Create button.

3. Entering Users in the Add User field.

4. Clicking the Update Group button when you finish adding Users.

The File realm has one built-in Group: everyone. All Users defined in the defined security realm are automatically members of the everyone Group.

To delete Groups, enter the name of the Group in the Remove These Groups list box 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 a Group for a Virtual Host

In WebLogic Server, virtual hosts that require authentication are represented in a security realm as a group. All the users of the virtual host are defined first as users of the security realm for a particular WebLogic Server and then defined as members of the group that represents the virtual host.

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.

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 12-18 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 Note: Only the system user can start a Managed Server.
Command-line Administration Tools	weblogic.admin	shutdown, lockserver unlockserver
WebLogic Events	weblogic.servlet.topicName	send receive
WebLogic servlets	weblogic.servlet.servletName	execute
WebLogic JDBC connection pools	weblogic.jdbc.connectionPool.poolname	reserve reset shrink
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

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

1. Specify the name of WebLogic Server resource that you want to protect with an ACL.

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

2. 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.

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

When creating ACLs for resources in WebLogic Server you need to use the syntax in Table 12-18 to refer to the resource. For example, the JDBC connection pool named demopool would be specified as weblogic.jdbc.connectionPool.demopool.

Before you can boot a WebLogic Server, you need to give permission to the boot the server to a set of Users. This security measure prevents unauthorized Users from booting WebLogic Server.

Configuring 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 configure the SSL protocol, perform the following steps:

1. Obtain a private key and digital certificate for WebLogic Server. You need a digital certificate and private key for each WebLogic Server that will use the SSL protocol.

2. Store the private key and digital certificate for WebLogic Server.

3. Through the Administration Console, set fields for the SSL protocol and the private key, digital certificate, and certificate authorities trusted by WebLogic Server. These fields are defined on a per-server basis; you must define them on any WebLogic Server that will use the SSL protocol.

The following sections describe these steps in detail.

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

Requesting a Private Key and Digital Certificate

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.

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.0\config\mydomain\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 12-19 Fields on the Certificate Request Generator Form

   Field	Description
   Country code	The two-letter ISO code for your country. The code for the United States is US.
   Organizational unit name	The name of your division, department, or other operational unit of your organization.
   Organization name	The name of your organization. The certificate authority may require any host names entered in this field belong to a domain registered to this organization.
   E-mail address	The e-mail address of the administrator. The digital certificate is mail to this e-mail address.
   Full host name	The 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.mydomain.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)	The name of your city or town. If you operate with a license granted by a city, this field is required; you must enter the name of the city that granted your license.
   State name	The 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 this 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 Use Encrytped Keys field on the SSL tab of the Server window in the Administration Console.
   Random String	A string of characters to be used by the encryption algorithm. You do not have to remember this string in the future. It adds an external factor to the encryption algorithm, making it more difficult for anyone to break the encryption. For this reason, enter a string that is not likely to be guessed. BEA strongly recommends a long string with a good mixture of uppercase and lowercase letters, digits, spaces, and punctuation characters; these long, mixed strings contribute to more secure encryption.
   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. We recommend the 1024-bit key.

4. Click the Generate Request button.

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

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

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

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

   • www_mydomain_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 email 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.0\config\mydomain directory.

   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.

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 field, enter the full directory location and name of the digital certificate for WebLogic Server.

   • In the Trusted CA File Name field, 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 field, 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 Fields for the SSL Protocol.

9. Use the following command-line option to start WebLogic Server.

   -Dweblogic.management.pkpassword=password

   where password is the password defined when requesting the digital certificate.

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.0\config\mydomain 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.0\config\mydomain directory of your WebLogic Server and set the fields described in Defining Fields 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 Fields for the SSL Protocol

To define fields 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 fields on this tab by entering values and checking the required checkboxes. (For details, see the following table.)

4. Click the Apply button to save your changes.

5. Reboot WebLogic Server.

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

Note: Remember 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.

Table 12-20 SSL Protocol Fields

Field	Description
Enabled	Checkbox that enables the use of the SSL protocol. By default, this field is enabled.
SSL Listen Port	The number of the dedicated port on which WebLogic Server listens for SSL connections. The default is 7002.
Server Key File Name	The full directory location and name of the private key file for WebLogic Server. The file extension (.DER or .PEM) indicates the method that should be used by WebLogic Server to read the contents of the file.
Server Certificate File Name	The full directory location and name of the digital certificate file for WebLogic Server. The file extension (.DER or .PEM) indicates the method that should be used by WebLogic Server to read the contents of the file.
Server Certificate Chain File Name	The full directory location of the rest of the digital certificates for WebLogic Server. The file extension (.DER or .PEM) indicates the method that should be used by WebLogic Server to read the contents of the file.
Client Certificate Enforced	Checkbox that enables mutual authentication.
Trusted CA File Name	The name of the file that contains the digital certificate for the certificate authority(s) trusted by WebLogic Server. This file specified in this field 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	The 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.
Use Java	Checkbox that 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 field is not enabled.
Use Encrypted Keys	Field that specifies that the private key for the WebLogic Server has been encyrpted with a password. The default is false.
Handler Enabled	Field that 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 field. By default, the SSL Handler allows one WebLogic Server to make outgoing SSL connections to another WebLogic Server. For example, an EJB in WebLogic Server may open an HTTPS stream on another Web server. With the HandlerEnabled field enabled, the WebLogic Server acts as a client in an SSL connection. By default this field is enabled. Disable this field 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	The 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	The number of milliseconds that WebLogic Server should wait for an SSL connection before timing out. The default value is 25,000 milliseconds. 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.
Certificate Cache Size	The number of digital certificates that are tokenized and stored by WebLogic Server. The default is 3. For more information, see Using Mutual Authentication with Applets.

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 procedure in Configuring the SSL Protocol section.

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

To configure mutual authentication, check 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 over SSL

The SSL protocol can be used 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 IIOP over RMI connections, do the following:

1. Configure WebLogic Server to use the SSL protocol. For more information, see Configuring 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 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 IIOP over RMI.

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.0\config\mydomain directory. If for any reason the SerializedSystemIni.dat file is corrupted or destroyed, you must reconfigure WebLogic Server.

We recommend that you take the following steps:

• 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 already have a weblogic.properties file and you want to hash the passwords in the file, 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.

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 fields 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. Open the Security Configuration window.

3. Select the Passwords tab. Define the desired fields on this tab by entering values at the appropriate prompts and checking the required checkboxes. (For details, see the following table).

4. Click the Apply button to save your choices.

5. Reboot WebLogic Server.

The following table describes each field on the Passwords tab of the Security Configuration window.

Table 12-21 Password Protection Fields

Field	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	Checkbox that requests the locking of a user account when an invalid attempt it made to log in to that account. By default, this field is enabled.
Lockout Threshold	The 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. Note that invalid login attempts must be made within a span defined by the Lockout Reset Duration field. The default is 5.
Lockout Duration	The 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 field. The default is 30 minutes. In order to unlock a user account, you need to have the unlockuser permission for the weblogic.passwordpolicy.
Lockout Reset Duration	The 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 field happens within the amount of time defined by this field. For example, if the value in this field 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 allows 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 field on the Security Configuration window. 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 field on the General tab of the Security Configuration window 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..

Configuring Security Context Propagation

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

When security context propagation is used, 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 WLE 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 WLE 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 WLE domains.

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

For more information, see Using WLEC.

The steps for implementing security context propagation are as follows:

1. Create a new WLEC connection pool for the purpose of security context propagation. To create a WLEC connection pool, go to the ServicesWLEC node in the left pane of the Administration Console. In the right pane of the Administration Console, click the Create a new WLEC Connection Pool link. Define the fields in the following table:

   Table 12-22 WLEC Connection Pool Fields on the General Tab

   Field	Description
   Name	The 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 WLE domain. The format of each address is //hostname:port. The addresses must match the ISL addresses defined in the UBBCONFIG file. Multiple addresses are seperated 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 field. Multiple addresses are separated by semicolons. This field is optional.
   Domain	The name of the WLE domain to which this WLEC connection pool connects. You can have only one WLEC connection pool per WLE domain. The domain name must match the domainid parameter in the RESOURCES section of the UBBCONFIG file for the WLE domain.
   Minimum Pool Size	The number of IIOP connections to be added to the WLEC connection pool when WebLogic Server starts. The default is 1.
   Maximum Pool Size	The maximum number of IIOP connections that can be made from the WLEC connection pool. The default is 1.

2. Click the Create button.

3. Propagate the security context for a User in a WebLogic Server security realm to a WLE domain. To do so, define the fields on the Security tab in the Connection Pool Configuration window. The following table describes these fields.

   Table 12-23 WLEC Connection Pool Fields on the Security Tab

   Field	Description
   User Name	A WLE user name. This field is required only when the security level in the WLE domain is USER_AUTH, ACL or MANDATORY_ACL.
   User Password	The password for the User defined in the User Name field. This field is required only when you define the User Name field.
   User Role	The WLE user role. This field is required when the security level in the WLE domain is APP_PW, USER_AUTH, ACL, or MANDATORY_ACL.
   Application Password	The WLE application password. This field is required when the security level in the WLE domain is APP_PW, USER_AUTH, ACL, or MANDATORY_ACL.
   Minimum Encryption Level	The minimum SSL encryption level used between the WLE domain and WebLogic Server. The possible values are 0, 40, 56, and 128. The default is 40. 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 this minimum level of encryption is not met, the SSL connection between WLE and WebLogic Server fails.
   Maximum Encryption Level	The maximum SSL encryption level used between the WLE domain and WebLogic Server. The possible values are 0, 40, 56, and 128. The default is the maximum level allowed by the Encryption Package kit license. 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 this minimum level of encryption is not met, the SSL connection between WLE and WebLogic Server fails.
   Enable Certificate Authentication	Checkbox that enables the use of certificate authentication. By default certificate authentication is disabled.
   Enable Security Context	Check this checkbox to pass the security context of the WebLogic Server User passed to the WLE domain. By default, security context is disabled.

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

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

6. 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 field when creating a WLEC connection pool.

Using certificate authentication between the WebLogic Server environment and the WebLogic Enterprise environment implies performing a new SSL handshake when establishing a connection from the WebLogic Server environment to a CORBA object, RMI object, or EJB in a WebLogic Enterprise environment is initiated. 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 principal and put the private key in the TUXDIR/udataobj/security/keys directory of WebLogic Enterprise.

2. Use the tpusradd command to define the principal as a WebLogic Enterprise user.

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

4. Define the principal name in the User Name field 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 WebLogic Enterprise domain and the WebLogic Server security realm.

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

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

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

Setting Up the Java Security Manager

When you run WebLogic Server under Java 2 (JDK 1.3), WebLogic Server uses the Java Security Manager to control access to WebLogic Server resources. The Java Security Manager requires a security policy file to set up the permissions. The WebLogic Server distribution includes a security policy file called weblogic.policy that contains a set of default permissions. With this file you can start WebLogic Server without first creating your own security policy file.

Edit the following lines in the weblogic.policy file, replacing the location of the directory in which you installed WebLogic Server.

grant codebase "file:./c:/weblogic/-"{
permission java.io.FilePermission "c:${/}weblogic${/}-", ...

Once you make these changes, we recommend that you take the following steps:

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

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

Set the java.security.manager and java.security.policy properties on the Java command line when you start WebLogic Server. These properties perform the following functions:

• The java.security.manager property specifies that a security policy will be used by the Java Virtual Machine (JVM). You do not need to specify any arguments to this property.

• The java.security.policy property specifies the location of the security policy file to be used by the JVM. The argument to this property is the fully qualified file name of the weblogic.policy file.

For example:

$ java ... -Djava.security.manager\
-Djava.security.policy==c:/weblogic/weblogic.policy

Be sure to use == instead of = when specifying the java.security.policy argument so that only the weblogic.policy file is used by the Java security manager. The == causes the weblogic.policy file to override any default security policy. A single equal sign (=) causes the weblogic.policy file to be appended to an existing security 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.

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 "/-').