★ wanayoo — archive 1999 http://jserv.java.sun.com/products/java-server/documentation/realms/tutorial.htmlNouvelle recherche | Portail wanayoo

    Developing Custom Realms.

1.0 Introduction

Realms are security abstractions that are used to provide controlled access to the resources served by the Java Web Server (JWS). Realms are objects that provide a persistent access to Users, Groups and Access Control Lists (ACLs) within a security framework.  By default, JWS ships with the following realms:
    • SharedPasswordRealm: Users, Groups and ACLs are stored within files.
    • UNIXRealm or NTRealm: Reflects UNIX or Windows NT Users. But Groups and ACLs are stored within files.
    • CertificateRealm: Authenticates Users based on their X.509 certificate.
This tutorial is meant for developers who wish to create their own realms for access control of the resources served by JWS.  This tutorial only deals with the authentication systems that are pass phrase based.  Developing realms that are not pass phrase based is very similar. A typical example of a place where you would want to use pass phrase based realms are:
  • Protecting resources served by Java Web Server (JWS) by using the Users and Groups stored within a database.
  • Storing ACLs. within a database.
  • Imposing your own security policies for managing the resources served by the JWS.

2.0 Developing Custom Realms

Core APIs that are needed to develop custom realms are included within the JWS. The core APIs for developing custom realms are independent of how & where Users, Groups and ACLs are stored. So, one can implement a custom realm that stores the Users & Groups within a database and ACLs within files. Or one can store ACLs within a database and store Users & Groups within flat files.

Developing custom realms within JWS involves:

  1. Implementing following entities within the Realm.
    • ACLs: Controls access to ACLs within the realm.
    • Groups: Controls access to Groups within the realm.
    • User: Controls access to Users within the realm.
    • Overall Realm: Controls ownership and access to the entire realm.
  2. Defining a User class that stores some profile data and supports an authentication scheme.
  3. Providing a configuration file to tell the JWS how to find the realm.
Once you restart the JWS, all the realms stored within the realms will be recognized by the JWS. You can then use Admin Applet to administer the realms. Now you can define the ACLs within the realm and the resources that protected by the JWS.
 

 2.1 Developing a Custom Realm using the Core APIs within JWS

You can use the core APIs to develop a custom realm that uses the users and groups stored in the database. We have provided an example (DatabaseRealm.java) of such an implementation. This implementation stores ACLs within files. You would need to add code at a few methods that extracts the users and groups from your database.

 Steps for developing custom realms using the Core APIs.

  1. Subclass the class sun.security.acl.PrincipalImpl and implement the interfaces com.sun.server.realm.User and com.sun.server.realm.Passphrase. We have provided a sample implementation of such a class. You would  need to provide implementation for the following method:
    • authenticate() : You would need to check the database and verify if the user name and pass phrase are correct within this method.
  2. 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.
  3. Make sure you have the following <server-root>/lib/jws.jar in your classpath when you compile these classes.
  4. 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/.
  5. Create the directory <name-of-directory>
  6. Stop the server. Set the classpath so the JWS can load your custom realm classes.
  7. Restart the server.
  8. Create ACLs and protect the resources served by the JWS using your realm.

  2.2 Extending the Core APIs within JWS for developing Custom Realms.

 In the process of developing this tutorial we have defined several wrapper classes that simplify the development of custom realms. These wrapper classes emerged as an attempt to modularize the components constituting any realm. We have provided implementations for storing ACLs, Groups and Users in a persistent manner using files. These have been implemented in the classes FileAclEntity, FileGroupEntity and FileUserEntity.  By using these wrapper classes you can mix and match these implementations with any other implementation for your custom realm. They are still under a process of development. These are not supported. Please send email to jserv-interest@javasoft.com for your suggestions on improving the API.  The classes that have been developed are:

 Steps for developing custom realms:

  1. Setting Acls: You can define ACLs within your custom realm in one of the following ways:
    • If you wish to use a database for storing ACLs then extend and override methods defined within the class AclEntityImpl.
    • If you wish to store ACLs within a file extend or use the class FileAclEntity.
    • Or you can provide an implementation for the interface AclEntity in any other way.
     
  2. Setting Groups: You can define Groups within your custom realm in one of the following ways:
    • If you wish to use a database for storing Groups then extend and override methods defined within the class GroupEntityImpl.
    • If you wish to store Groups within a file extend or use the class FileGroupEntity.
    • Or you can provide an implementation for the interface GroupEntity in any other way.
     
  3.  Setting Users: You can define Users within your custom realm in one of the following ways:
    • If you wish to use a database for storing Users then extend and override methods defined within the class UsersEntityImpl.
    • If you wish to store Users within a file extend or use the class FileUsersEntity.
    • Or you can provide an implementation for the interface UserEntity in any other way.
    NOTE: You MUST return an object of either the class RealmUser or its subclass within the method getUser().
     
  4.   Setting Overall Realm methods: You can define Overall Realm methods within your custom realm by sub classing class CustomRealm and overriding the following methods: (see, the class PasswordRealm as an example)
    1. setDefaultAclOwner(). You must override this method to set the Owner of the realm. By default the base class sets the AclOwner to "admin". For example, Within UNIX realm, root is the default owner etc.
    2. setDefaultPolicies(). You must override this method if you wish to set any default policies within your realm. For example, default policy could be "by default the realm has the following users: root, system, nobody".
    3. verifyNotInPolicies(). If you have set policies within your realm (like an existence of a set of users) then this method should be overridden. This method is called before deleting users or groups. For example, this method can be overridden to set a policy on the realm such as: "Users & Groups cannot be deleted within this realm".
    4. init(). Override this method if you want to perform any initializations for this realm.
     
  5.  Installing the Realm Object:
    1. After creating objects that enforce User, Group and ACL entities use the methods setUserEntity(), setGroupEntity() and setAclEntity() methods of the class CustomRealm to set the entities. (see, the class PasswordRealm as an example).
    2. Make sure you have the following <server-root>/lib/jws.jar in your classpath when you compile these classes.
    3. 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/.
    4. Create the directory <name-of-directory>
    5. Stop the server. Set the classpath so the JWS can load your custom realm classes.
    6. Restart the server.
    7. Create ACLs and protect the resources served by the JWS.

      8.  
 

 

JavaServer Products
Brewed by JavaSoft
A unit of Sun Microsystems, Inc.