Administering the WebLogic caching realm
This document describes CachingRealm, a WebLogic security realm that provides caching services for delegate realms. CachingRealm hosts a delegate realm and improves WebLogic Server performance by caching lookups, reducing the number of calls into the delegate realm.
A realm provides access to a set of Users, Groups, Permissions, and ACLs (Access Control Lists). During startup, WebLogic Server sets up a realm, called the "weblogic" realm, which it uses to authenticate and authorize WebLogic Server users. The default realm, WLPropertyRealm, is based on the weblogic.properties file. It reads User, Group, and ACL properties at startup time. WLPropertyRealm stores all of its security objects in memory, so it has no use for caching.
You can substitute a different realm for the WLPropertyRealm. For example, using the Windows NT realm, WebLogic Server authenticates users in a Windows NT domain, so any user with a Windows NT login can be a WebLogic Server user. Similar alternative realms are included for UNIX password authentication and LDAP servers, such as Microsoft Site Server, Netscape Directory Server, or Novell NDS. You can also create your own custom realm to provide access to any other external store you would like to use for authentication and/or authorization with WebLogic Server.
WebLogic Server uses CachingRealm to host any alternative realm. You specify an alternative realm by setting the weblogic.security.realmClass property to the class name of the realm you want to use. When you start WebLogic Server, it sets up CachingRealm to delegate to the realm class you specified. WebLogic Server calls CachingRealm for its security requests and CachingRealm calls the delegate realm.
CachingRealm can cache the results of realm lookups--both successful and unsuccessful. It manages separate caches for Users, Groups, Permissions, ACLs, and authorizations. You can selectively enable each type of cache, set the number of objects cached, and the number of seconds a cached object is valid.
When cache is enabled, WebLogic Server does not immediately recognize changes you make in the underlying store. Using the default cache settings, any change you make should be recognized within 60 seconds.
Setting up CachingRealm
CachingRealm is enabled automatically when you set up an alternate realm, by setting the weblogic.security.realmClass property to the classname for the alternate realm. Follow the instructions for the alternate realm to configure and set up the realm before you configure the cache.
Installing the alternate realm sets up CachingRealm to delegate to the alternate realm, but it does not enable caching. You must do that separately. This section tells you how to set up caching after you have installed an alternate realm.
Setting cache case sensitivity
CachingRealm, by default, assumes that the delegate realm is case-sensitive. If a realm treats the usernames "bill" and "BILL" as two distinct users, it is a case-sensitive realm. WebLogic Server is case-sensitive, as are most realms.
The Windows NT and LDAP realms are examples of realms that are not case-sensitive. In a Windows NT domain, the usernames "bill" and "BILL" are equivalent.
If a realm is not case-sensitive, you must set this property in the weblogic.properties file:
When this property is set, CachingRealm converts usernames to lowercase so that WebLogic Server gives correct results for the realm when it does its case-sensitive comparisons. This means that when you reference users from a realm that is not case-sensitive within WebLogic Server--for example, in applications, or in the weblogic.properties file--you must type usernames with all lowercase letters.
Enabling the cache
When you enable caching, CachingRealm saves the results of a realm lookup in its cache. Lookup results remain in cache until either a number of seconds has passed (the lookup result has expired) or the cache has filled. When the cache is full, new lookup results replace the cached results added least recently.
You enable caching for each type of realm object individually. CachingRealm can cache results of five kinds of realm lookups:
The last of these, authenticate, takes login information from a client and returns an authenticated User if the login information is valid.
The following table lists the properties that enable each type of cache:
Tuning the cache
CachingRealm is extensively tunable. For each of the five types of cache, you can set the following parameters:
The size of a cache should be a prime number for best lookup performance.
The ttl (time-to-live) values determine how long a cached object is valid. The higher you set these, the less often CachingRealm calls the delegate realm, and the greater contribution the cache makes to improved performance. The trade-off is that changes to the underlying store are not recognized until the cached object has expired.
Note: Once you obtain an object from the realm, the object will not reflect any changes in the underlying store. 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 realm with a getGroup() call. To update the group, you must call getGroup() again.
The following table lists the cache-tuning properties.
Copyright © 2000 BEA Systems, Inc. All rights reserved.