
	Corporate Info \| News \| Solutions \| Products \| Partners \| Services \| Events \| Download \| How To Buy
	e-docs \| Site Map \| Search \| Contact \| Glossary \| WebLogic Server Documentation

Administering the WebLogic caching realm

About CachingRealm
Setting up CachingRealm: Setting cache case sensitivity; Enabling the cache; Examples
Tuning the Cache
Other documents
Using WebLogic Realms and ACLs
Administering the Windows NT security realm
Administering the WebLogic LDAP security realm
Administering the WebLogic UNIX security realm
RDBMSRealm example

About CachingRealm

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:

  weblogic.security.realm.cache.caseSensitive=false

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:

get User
get Group
get Permission
get ACL
authenticate User

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:

weblogic.security.realm.cache.acl.enable=true Enables ACL caching

weblogic.security.realm.cache.auth.enable=true Enables authorization caching

weblogic.security.realm.cache.group.enable=true Enables group caching

weblogic.security.realm.cache.user.enable=true Enables user caching

weblogic.security.realm.cache.perm.enable=true Enables permission caching

Examples

Using the Windows NT security realm
To set up the Windows NT realm, you must first set up the NTRealm.properties file. See Administering the WebLogic Windows NT security realm for complete instructions on using the Windows NT realm.
To set up caching for the Windows NT realm, set the following properties in the weblogic.properties file:
```
  weblogic.security.realmClass=weblogic.security.ntrealm.NTRealm
  weblogic.security.realm.cache.caseSensitive=false
  weblogic.security.realm.cache.user.enable=true
  weblogic.security.realm.cache.group.enable=true
  weblogic.security.realm.cache.auth.enable=true
```

Using the RDBMSRealm

The RDBMSRealm example requires setting up a database and compiling the example. See examples.security.rdbmsrealm for instructions. To enable the realm and all available caching, set the following properties in the weblogic.properties file:

  weblogic.security.realmClass=examples.security.rdbmsrealm.RDBMSRealm
  weblogic.security.realm.cache.user.enable=true
  weblogic.security.realm.cache.group.enable=true
  weblogic.security.realm.cache.permission.enable=true
  weblogic.security.realm.cache.acl.enable=true
  weblogic.security.realm.cache.auth.enable=true

Tuning the cache

CachingRealm is extensively tunable. For each of the five types of cache, you can set the following parameters:

size -- maximum number of objects to hold in the cache. The default is 211 objects.
ttl.positive -- the number of seconds to cache the result of a successful lookup. The default is 60 seconds.
ttl.negative -- the number of seconds to retain the result of an unsuccessful lookup. The default is 5 seconds.

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.

weblogic.security.realm.cache.acl.size=int The number of ACLs to cache.

weblogic.security.realm.cache.acl.ttl.positive=int Number of seconds to cache successful ACL lookups.

weblogic.security.realm.acl.ttl.negative=int Number of seconds to cache unsuccessful ACL lookups.

weblogic.security.realm.cache.auth.size=int The number of authentications to cache.

weblogic.security.realm.cache.auth.ttl.positive=int Number of seconds to cache successful authentication lookups.

weblogic.security.realm.auth.ttl.negative=int Number of seconds to cache unsuccessful authentication lookups.

weblogic.security.realm.cache.group.size=int The number of groups to cache.

weblogic.security.realm.cache.group.ttl.positive=int Number of seconds to cache successful group lookups.

weblogic.security.realm.group.ttl.negative=int Number of seconds to cache unsuccessful group lookups.

weblogic.security.realm.cache.perm.size=int The number of Permissions to cache.

weblogic.security.realm.cache.perm.ttl.positive=int Number of seconds to cache successful permission lookups.

weblogic.security.realm.perm.ttl.negative=int Number of seconds to cache unsuccessful permission lookups.

weblogic.security.realm.cache.user.size=int The number of users to cache.

weblogic.security.realm.cache.user.ttl.positive=int Number of seconds to cache successful user lookups.

weblogic.security.realm.user.ttl.negative=int Number of seconds to cache unsuccessful user lookups.