A
JAAS Provider APIs

This appendix describes the JAAS Provider public packages.

This appendix contains these topics:

• JAAS Provider API Overview

• Package oracle.security.jazn

• Package oracle.security.jazn.policy

• Package oracle.security.jazn.realm

JAAS Provider API Overview

This appendix provide brief descriptions of the JAAS Provider APIs. For detailed information on these APIs, see the JAAS Provider Javadoc available in the OC4J section of the Oracle9i Application Server Documentation Library.

Package oracle.security.jazn

Package oracle.security.jazn provides the classes and interfaces for Oracle's authorization/policy provider for the Java Authentication and Authorization Service (JAAS).

Besides providing a full implementation of javax.security.auth.Policy, the JAAS provider enhances JAAS in the following ways:

• Defines a realm-based user and role management API

• Defines an administrative API for administering the following aspects of the authorization policy:
  • Permission-to-user assignment

  • Permission-to-role assignment

  • User-to-role assignment

• Provides role-based access control (RBAC) support through the realm framework, with full support for role hierarchies.

Interfaces

Persistable

Persistable defines the basic behavior for a persistable object.

Classes

JAZNConfig

JAZNConfig provides a starting point for obtaining JAAS Provider-related objects and a centralized place for managing JAAS Provider properties

JAZNConfig enables you to run multiple JAAS provider instances. You can deploy several different applications using JAAS provider in the same Java virtual machine (JVM), each with different configurations. For example, you can have one application using JAAS provider with LDAP-based Oracle Internet Directory as the provider type and another application using JAAS provider with XML-Based Provider Type as the provider type in the same JVM.

JAZNContext

JAZNContext provides a starting point for obtaining JAAS Provider-related objects and a centralized place for managing the JAAS provider properties. JAZNContext is essentially a single-instance version of JAZNConfig.

JAZNPermission

JAZNPermission is for authorization permissions. A JAZNPermission contains a name (also referred to as a target name), but no actions list; you either have the named permission or you do not.

The target name is the name of the JAAS provider permission.

Table A-1 lists the possible target names for a JAZNPermission, describes what the permission allows, and describes the risks of granting the permission.

Table A-1 JAZNPermission Target Names

Permission Name	The Permission Allows	Risks of Allowing this Permission
getPolicy	The caller to retrieve the JAZNPolicy object	This enables someone to retrieve a JAZNPolicy object. Since the JAZNPolicy object can modify the JAAS Provider type, grant this permission only to the administrators.
getRealmManager	The caller to retrieve the RealmManager object	This enables someone to retrieve a RealmManager object. Since the RealmManager object can create, drop, and modify realms, grant this permission only to the administrators.
getProperty. {propertyName}	The caller to retrieve the value of the JAAS provider property named {propertyName}	Depending on the particular key for which access has been granted, the code may have access to the location of the backend server as well as security credentials used to access the backend server. Carefully protect this permission and grant it only to administrators.
setProperty. {propertyName}	The caller to set the value of the JAAS provider property named {propertyName}	This can include setting a new backend server and new credentials to access the backend server. Since this can bypass the enterprise policy, carefully protect this permission and grant it only to administrators.

JAZNWebAppConfig

JAZNWebAppConfig represents a <jazn-web-app> Configuration instance.

Exceptions

JAZNConfigException

JAZNConfigException represents an authorization exception.

JAZNException

JAZNException represents an authorization exception.

JAZNInitException

JAZNInitException is thrown when an initialization error occurs.

JAZNNamingException

JAZNNamingException is used to wrap a javax.naming.NamingException.

JAZNObjectExistsException

JAZNObjectExistsException is thrown when an attempt is made to create an object that already exists.

JAZNObjectNotFoundException

JAZNObjectNotFoundException is thrown when an attempt is made to access an object that does not already exist.

JAZNRuntimeException

JAZNRuntimeException represents an authorization exception.

Package oracle.security.jazn.login

Package oracle.security.jazn.login provides the classes and interfaces for administering Login Modules.

Classes

LoginModuleManager

LoginModuleManager extends javax.security.auth.login. Configuration by defining management methods (add/remove AppConfigurationEntry).

Package oracle.security.jazn.policy

Package oracle.security.jazn.policy provides the classes and interfaces for administering the authorization policy.

Interfaces

GlobalPolicy

GlobalPolicy represents the Global JAAS Provider Policy.

JAZNPolicy

JAZNPolicy represents the repository of authorization policies. More specifically, JAZNPolicy deals with the assignment of permissions or privileges to grantees (these can be users or roles or any valid grantee).

In order for a grant or revocation to succeed, the grantor or revoker (represented by the current subject) must have the relevant permissions granted to them.

In general, the methods that return a list or set represent a snapshot of a JAZNPolicy provider at the time of the query. If the JAAS provider is further modified, the returned set of permissions and roles may no longer be valid.

In general, JAZNPolicy implementation should cache the policy information, so that repeated calls using the same parameters do not result in repeated network round trips to the backing store.

JAZNPolicy also defines methods that change the persistent state of the JAAS Provider type (for example, grant or revoke xx methods). The implementation must ensure that whenever a grant or revoke is attempted, the relevant cache entries are invalidated.

PermissionClassManager

The PermissionClassManager is an utility to help manage permission classes.

PermissionClassManager represents the repository of all registered Permission classes. Registering a permission class allows access to stored metadata that provides specific information about a given permission's target, action, and/or description. Failure to register a given permission class will not affect JAAS provider's ability to use the permission class. That is, JAAS does not limit permission grants or revocations to those classes registered with the PermissionClassManager.

PolicyManager

PolicyManager defines basic methods for managing JAAS Provider policies.

PrincipalClassManager

The PrincipalClassManager is an utility to help manage principal classes.

PrincipalClassManager represents the repository of all registered Principal classes. Registering a principal class allows access to stored metadata that provides specific information about a given principal's name and description. Failure to register a given principal class will not affect the JAAS provider's ability to use the principal class. That is, the JAAS provider recognizes all principal classes whether or not they have been registered with the PrincipalClassManager.

RealmPolicy

RealmPolicy is a Realm-specific Policy.

Classes

AdminPermission

AdminPermission represents the right to administer a permission. Given a Permission p, the grantee of AdminPermission(p) is granted the right to:

• Grant or revoke permissions implied by p (say p')

• Grant or revoke AdminPermission(p')

For example:

 p = java.io.FilePermission("/home/frank/-","read,write"); 

If grantee frank is granted AdminPermission(p), then frank is granted the following rights:

• The right to further grant or revoke p' (that is, read and write privileges for any file in the file system under /home/frank) to and from other grantees

• The right to further grant or revoke AdminPermission(p')

Consider the following information:

• An AdminPermission embedding another AdminPermission is not supported. There is no need to do so, since granting a grantee AdminPermission(p) implies that the grantee can further grant/revoke AdminPermission(p')

• Granting a grantee AdminPermission(p) does not imply granting the grantee. That must be granted separately.

Grantee

Grantee represents a grantee in a policy entry.

PermissionClassDesc

PermissionClassDesc defines the descriptor (metadata) for a Permission class.

PrincipalClassDesc

PrincipalClassDesc defines the descriptor (metadata) of a Principal class.

RoleAdminPermission

The grantee of RoleAdminPermission is granted the right to further grant or revoke the target role.

Package oracle.security.jazn.realm

Package oracle.security.jazn.realm provides the classes and interfaces for the realm framework.

Interfaces

InitRealmInfo.RealmType

InitRealmInfo.RealmType defines the different realm types supported by JAAS Provider.

Realm

Realm provides access to a store of roles and users. The JAAS provider separates role management from user management by providing each realm instance with its own UserManager for user management and RoleManager for role management.

Realm defines methods for managing realm's metadata (properties) and getting its UserManager and RoleManager.

Realm.LDAPProperty

Realm.LDAPProperty defines the LDAP properties applicable for creating a realm (user manager and role manager) using an LDAP directory as a backing store.

RealmPrincipal

RealmPrincipal extends from java.security.Principal. It is a principal associated with a realm instance.

RealmRole

RealmRole is a role associated with a realm. It can be associated with a group of privileges or roles.

RealmUser

RealmUser is a user associated with a realm. This is an empty interface for tagging objects as being RealmUser objects. It differs from RealmRole in that it cannot contain other roles.

RoleManager

RoleManager defines the APIs for managing roles in a realm.

UserManager

UserManager defines the APIs for managing users in a realm.

Classes

InitRealmInfo

InitRealmInfo is a placeholder for specifying realm properties when creating a new realm.

RealmLoginModule

RealmLoginModule is a realm-based login module.

RealmManager

RealmManager manages realms.

RealmPermission

RealmPermission is defined to represent permissions for a realm. It extends from java.security.Permission, and is used like any regular Java permission. RealmPermission consists of the name of the realm (also known as permission target name) and a set of actions specifying privileges applicable to that realm. The target name of a RealmPermission instance is the name of the realm in question. The individual action name is specific to the realm in question and is system-defined.

Table A-2 lists all the system-defined RealmPermission action names.

Table A-2 RealmPermission Action Names

Permission Action	Enables User To
createRealm	Create realms
dropRealm	Drop realms
createUser	Create users in the target realm
dropUser	Drop users in the target realm
createRole	Create roles in the target realm
dropRole	Drop roles in the target realm
modifyRole	Modify roles in the target realm
grantRole	Grant roles in the target realm
revokeRole	Revoke roles from the target realm