Realms are security abstractions that control access to the resources served by the Java Web Server. Java Web Server ships with the following realms: certificateRealm, defaultRealm, servletMgrRealm, and UNIXRealm or NTRealm. This document is meant for developers who wish to create their own realm.

This document only deals with the authentication systems that are passphrase based. Developing realms that are not passphrase based is very similar.

Developing custom realms for the Java Web Server involves the following:

1. Implementing Required Entities Within the Realm
2. Defining a User class
3. Creating a Configuration File
4. Loading the New Realm into the Java Web Server
5. Administering the Custom Realm

Once you restart the Java Web Server, all the realms stored within the realms/ directory will be recognized. You can then use Administration Tool to administer your custom realm just as you do the default realms. That includes defining resources protected by the realm and setting permissions in the access control list for the realm.

The steps for creating a custom realm are discussed in greater detail in the remainder of this document.

1. Implementing required entities within the Realm

   Core APIs that are needed to develop custom realms are included within the Java Web Server. These APIs are independent of how and where Users, Groups and ACLs are stored. So, you can implement a custom realm that stores the Users and Groups within a database and ACLs within files. Or, you can store ACLs within a database, and store Users and Groups within flat files.

   1. You need to add code for a few of the methods that extract the users and groups from your database.

      Subclass the class com.sun.server.realm.Realm and override the following methods:

      • init() : Use this method to perform any database related initialization.
      • getAcl() : Return an object of java.security.acl.Acl.
      • getAclNames() : Return an enumeration of all the ACLs within this realm.
      • addAcl() : Add a java.security.acl.Acl object to this realm.
      • removeAcl() : Remove this ACL from this realm.
      • getGroupNames() : Make a database query and return an enumeration of the groups.
      • getGroup() : Check for the existance of the Group within the database and return an object of java.security.acl.Group within the database.
      • addGroup() : Add a java.security.acl.Group object to the database.
      • removeGroup() : Remove the group from database.
      • getUserNames() : Return an enumeration of users stored within the database.
      • getUser() : Check for the existance of the user within the database and return an object of DatabaseRealmUser.
      • deleteUser() : Delete the user from the database.
      • getDefaultAclOwner() : In this method you can set who is the owner of the realm. For example, by default the owner in UNIX realm is "root" etc.
      • setDefaultPolicies() : In this method policies such as existance of "admin" etc.
      
       
   2. Make sure you have server_root/lib/jws.jar in your classpath, then compile these classes.
       
2. Defining a user class

   The User class stores some profile data and supports an authentication scheme.

   1. Subclass the class sun.security.acl.PrincipalImpl and implement the following interfaces:
      • com.sun.server.realm.User
      • com.sun.server.realm.Passphrase
      
       

3. Creating a configuration file

   The configuration file tells the Java Web Server how to find the realm.

   1. Within the directory server-root/realms create a file with the name of your custom realm. There must be two entries within this file. (For an example, please see a file called defaultRealm within the server-root/realms directory)  The entries are:
      • classname=full-name-of-class
      • directory=name-of-directory
        It is customary to create a directory within server-root/realms/data/.
   2. Create the directoryname-of-directory
       
4. Loading the new realm into the Java Web Server.
   1. Stop the server.
   2. Set the classpath so the Java Web Server can find your custom realm classes.
   3. Restart the server.
       
5. Administering the custom realm
   
   • Use the Administration Tool to create ACLs and protect the resources using your custom realm, just as you would do if using the default realms.
      

---

Top java-server-feedback@java.sun.com

Copyright © 1999 Sun Microsystems, Inc. All Rights Reserved.