All Packages  Class Hierarchy  This Package  Previous  Next  Index

Class com.sun.server.realm.Realm

java.lang.Object
   |
   +----com.sun.server.realm.Realm

public abstract class Realm
extends Object

A realm is an administrative entity around which basic operational security policies revolve. Realms are normally used to organize the objects used in defining access control policies. For example, the resources on a particular web server are all expressed in terms of the users, groups, and access control lists provided by a realm.

Other uses of realms include organizing entities used for defining trust policies. For example, a group can be defined to say what X.509 certificate authorities are trusted to authenticate clients, or whose signatures on code modules implies granting special privileges.

A Realm object provides access to the following data, and supports modifying (and extending) it according to policies defined by the realm administrator and by each particular kind of realm:

Users are the main principals around which a realm is organized.
Different Authentication Protocols are used by the different realms to control how people prove that they are in fact the user who they say they are. For example, passwords (or passphrases), public key certificates, or challenge/response systems that might rely on hardware tokens.
Groups of users (and of other groups) are used to define various policies applying to many users.
Access Control Lists (ACLs) are associated with realms in that the entries in them, which identify users and groups, are only meaningful within a particular realm.
Administrative Privileges over the realm itself are extended to users within the realm, using a special ACL. There are server security manager checks for listing realm names and also for getting a realm, given its name.

A realm is an abstract class. Simple implementations of realms will just provide the user authentication (and home directory) component. Other implementations may desire more control over the data formats used to represent groups and ACLs. For example, they may use a database to support particular scaling or performance goals; or may use a replicated administrative database such as NIS in order to meet requirements for robustness in the face of network failures.

When objects associated with a realm are modified, they will automatically store their persistent state.

At this time, realms are not intended to be used except within network services.

Notes:

This API is still a "work in progress". Comments are solicited! It is not intended to be a complete (or final) API at this time.
Programming interfaces used to repair corrupt realm data structures are currently not defined.
The responsibility for enforcing realm security policies will as a rule lie within that realm, but at this time there are no good examples of how to make that work. In particular, the current admin tools impose their own policy which is distinct from framework set out in this class.
This uses the java.server.realm.home system property to identify where realm configuration files are stored. Those files define what realms exist.

See Also:: Principal, Acl, Group

Realm(): The default constructor creates a realm which will later be initialized, either from propertys or by deserializing.

addAcl(String, Principal): Returns a newly created empty ACL.
addGroup(String): Returns a newly created empty group, with the name which is given as a parameter.
deleteUser(String): Deletes the identified user, if it is supported by the underlying realm implementation.
get(String): Returns the realm identified by the name which is passed as a parameter.
getAcl(): Returns the access control list controlling which users within this realm should administrative privileges on this realm itself.
getAcl(String): Returns a particular named Access Control List (ACL) which is associated with this realm.
getAclNames(): Returns names of all the Acls in this realm.
getDefaultAclOwner(): Returns the Principal which, by default, owns ACLs within this realm.
getGroup(String): Returns the group with the name which is given as a parameter.
getGroupNames(): Returns names of all the groups in this particular realm.
getName(): Returns the name of this realm, as presented to users
getRealmDir(): Normally identifies the directory where the realm stores realm-specific information, such as group membership lists, ACLs, and user authentication information.
getRealmNames(): Returns the names of accessible realms.
getUser(String): Returns the information recorded about a particular named user.
getUserNames(): Returns names of all the users in this particular realm.
init(Properties): Initialize a realm from some properties.
logError(Exception, String): Logs an error in realm operation in a place where a realm administrator can find the error message.
logError(String)
removeAcl(String): Deletes the named ACL.
removeGroup(String): Deletes a group, if it is empty and is a member of no group or ACL
setDefaultPolicies(): Establishes default realm policies, such as existence of an "adminGroup" principal which owns the realm's "adminAcl".
setName(String): Assigns the name of this realm, and stores it in the cache of realms.
setRealmDir(File): Initializer for use by subclasses.
toString(): Identifies this realm
verifyNotInPolicies(Principal): Utility for use when checking if it's alright to delete a user or group: raises an exception if the principal is in a group or ACL.

Realm

 protected Realm()

The default constructor creates a realm which will later be initialized, either from propertys or by deserializing.

getAcl

 public abstract Acl getAcl() throws BadRealmException

Returns the access control list controlling which users within this realm should administrative privileges on this realm itself. The following initial behaviours are predefined:

The ACL named adminAcl controls administrative privileges.
A realm-specific principal defines the owner of that ACL. (See getDefaultAclOwner).

Returns:: the ACL controlling administrative privileges
Throws: BadRealmException: if realm data structures are bad

getAclNames

 public abstract Enumeration getAclNames() throws BadRealmException

Returns names of all the Acls in this realm.

Throws: BadRealmException: if realm data structures are bad

getAcl

 public abstract Acl getAcl(String name) throws NoSuchAclException, BadRealmException

Returns a particular named Access Control List (ACL) which is associated with this realm.

Parameters:: name - the name of the ACL which is requested
Throws: NoSuchAclException: if the ACL doesn't exist
Throws: BadRealmException: if realm data structures are bad

addAcl

 public abstract Acl addAcl(String name,
                            Principal owner) throws BadRealmException

Returns a newly created empty ACL. This ACL has a single owner.

Parameters:: name - name of the group whose creation is desired; owner - initial owner of the ACL, which must be a principal returned via getUser.
Returns:: the newly created empty acl
Throws: BadRealmException: if realm data structures are bad
See Also:: getUser

removeAcl

 public abstract void removeAcl(String name) throws NoSuchAclException, BadRealmException

Deletes the named ACL. It is the caller's responsibility to make sure that this ACL is not used for anything.

Parameters:: name - the name of the ACL to be deleted
Throws: NoSuchAclException: if the ACL doesn't exist
Throws: BadRealmException: if realm data structures are bad

getUserNames

 public abstract Enumeration getUserNames() throws BadRealmException

Returns names of all the users in this particular realm.

Returns:: enumeration of user names (strings)
Throws: BadRealmException: if realm data structures are bad

getUser

 public abstract User getUser(String name) throws NoSuchUserException, BadRealmException

Returns the information recorded about a particular named user.

Parameters:: name - name of the user whose information is desired
Returns:: the user object
Throws: NoSuchUserException: if the user doesn't exist
Throws: BadRealmException: if realm data structures are bad

deleteUser

 public abstract void deleteUser(String name) throws NoSuchUserException, BadRealmException, InUseException

Deletes the identified user, if it is supported by the underlying realm implementation.

Parameters:: name - name of the user to be deleted
Throws: NoSuchUserException: if the user doesn't exist
Throws: BadRealmException: if realm data structures are bad
Throws: InUseException: if the user object could not be deleted because it is involved in some aspect of realm security policy

getDefaultAclOwner

 public abstract Principal getDefaultAclOwner() throws BadRealmException

Returns the Principal which, by default, owns ACLs within this realm. This is typically a group. This is a messy spot in the API, since ACL owners can't be examined and because there's an assumption in most places that there is really only one owner, but the core interface expects there to be multiple owners.

Returns:: the principal of this realm's default ACL owner
Throws: BadRealmException: in case of error

getGroupNames

 public abstract Enumeration getGroupNames() throws BadRealmException

Returns names of all the groups in this particular realm.

Returns:: enumeration of group names (strings)
Throws: BadRealmException: if realm data structures are bad

getGroup

 public abstract Group getGroup(String name) throws BadRealmException, NoSuchGroupException

Returns the group with the name which is given as a parameter.

Parameters:: name - name of the group whose information is desired
Returns:: the group
Throws: NoSuchGroupException: if the Group doesn't exist
Throws: BadRealmException: if realm data structures are bad

addGroup

 public abstract Group addGroup(String name) throws BadRealmException, InUseException

Returns a newly created empty group, with the name which is given as a parameter.

Parameters:: name - name of the group whose creation is desired
Returns:: the newly created empty group
Throws: BadRealmException: if realm data structures are bad
Throws: InUseException: if the group name is already in use

removeGroup

 public abstract boolean removeGroup(String name) throws BadRealmException, NoSuchGroupException, InUseException

Deletes a group, if it is empty and is a member of no group or ACL

Parameters:: name - name of the group
Returns:: true iff the group is successfully deleted; false if it could not be deleted because the group is used in some aspect of realm security policy
Throws: NoSuchGroupException: if the Group doesn't exist
Throws: BadRealmException: if realm data structures are bad
Throws: InUseException: if the group name is in use as part of the realm's security policies

get

 public static Realm get(String name) throws NoSuchRealmException, BadRealmException

Returns the realm identified by the name which is passed as a parameter. This function knows about all the realms which exist; it is not possible to store (or create) one which is not accessible through this routine.

Parameters:: name - identifies the realm
Returns:: the requested realm
Throws: NoSuchRealmException: if the realm is invalid
Throws: BadRealmException: if realm data structures are bad

getRealmNames

 public static Enumeration getRealmNames()

Returns the names of accessible realms.

Returns:: set of realm names

getName

 public final String getName()

Returns the name of this realm, as presented to users

setName

 protected final void setName(String name)

Assigns the name of this realm, and stores it in the cache of realms. Used when initializing a newly created in-memory realm object; if the realm already has a name, there is no effect.

Parameters:: name - name to be assigned to this realm.

toString

 public String toString()

Identifies this realm

Overrides:: toString in class Object

init

 protected void init(Properties props) throws BadRealmException, NoSuchRealmException

Initialize a realm from some properties. This can be used when instantiating realms from their descriptions. This method may only be called a single time. By default, this sets up the realm to store ACLs in a specified directory.

Parameters:: props - initialization parameters used by this realm.
Throws: BadRealmException: if the configuration parameters identify a corrupt realm
Throws: NoSuchRealmException: if the configuration parameters specify a realm which doesn't exist

setRealmDir

 protected void setRealmDir(File realmDir)

Initializer for use by subclasses. This records the directory where realm's data is stored.

Parameters:: realmDir - directory where the realm's state is stored.

setDefaultPolicies

 protected void setDefaultPolicies() throws BadRealmException

Establishes default realm policies, such as existence of an "adminGroup" principal which owns the realm's "adminAcl". This is intended to be used by subclasses as part of creating new realms.

Throws: BadRealmException: if realm data structures are bad

getRealmDir

 public File getRealmDir()

Normally identifies the directory where the realm stores realm-specific information, such as group membership lists, ACLs, and user authentication information.

verifyNotInPolicies

 public void verifyNotInPolicies(Principal p) throws BadRealmException, InUseException

Utility for use when checking if it's alright to delete a user or group: raises an exception if the principal is in a group or ACL.

Deleting the principal would make the security policy expressed in an ACL invalid. Later creation of a user with the same name could cause problem since the user might be in groups they'd not normally be permitted to join.

Parameters:: p - user, or group, being checked
Throws: BadRealmException: if realm data structures are bad
Throws: InUseException: if the principal is in use.

logError

 public static void logError(Exception e,
                             String info)

Logs an error in realm operation in a place where a realm administrator can find the error message. Most such errors are worth looking into, since they can reflect major system security problems.

logError

 public static void logError(String info)

All Packages  Class Hierarchy  This Package  Previous  Next  Index