Skip navigation.
Downloads | Product Documentation | Support

Programming Security For Java Applications

# Java Security Service Module Concepts

This section describes the concepts that you need to understand to use the Java Security Service Module product effectively. The concepts are grouped into two categories:

General Concepts

Concepts that Relate to Interfaces and Classes

# General Concepts

The following sections describe the general concepts:

- Anonymous User
- Compatibility
- DeepTokenEnumeration
- TokenEnumeration

## Anonymous User

An anonymous user is a special user that includes everyone that is not authenticated. You use the `com.bea.security.SecurityRuntime.getAnonymousIdentity()` method to get the anonymous user `AuthenticIdentity` from the security Runtime object (see RuntimeAction on page 2-7).

## Compatibility

Compatibility relates to versions of the services required by the Java Security Service Module application and versions of the service APIs in the Java Security Service Module. If the versions are not compatible, the portion of the application that uses that service API will not work and security holes may exist in the application. Therefore, you may choose to check each service API for compatibility before you attempt to use it.

All the service APIs support an `isCompatible()` method which may be used by the application to determine whether the version of the service API is compatible with the application.

## DeepTokenEnumeration

A deep-token enumeration re-curses into references to other naming authorities until the given name is completely resolved into a token. A token, in this case, is analogous to an attribute.

As with `TokenEnumeration`, `DeepTokenEnumeration` is another area where an application developer may choose to override the default implementation for a given naming authority. If you want recursion based on the value of a given attribute, then you can implement this extraneous logic in a custom naming authority class.

## TokenEnumeration

One duty of a naming authority is to resolve names into a series of tokens. A token, in this case, is analogous to an attribute. Standard token evaluation parses a name and returns a list of `NameAttributeValues` that contains the value and the `NameAttributeType`. If that attribute references another authority, this reference is not resolved during this type of enumeration.

Token enumeration may be one area in particular where an application developer may choose to override the base class. If a name is sufficiently complex, there may not be a straightforward way for a naming authority to parse it into its attribute forms by the built-in parsing rules.

# Concepts that Relate to Interfaces and Classes

The following concepts relate to the Java application programming interface (API) interfaces and classes:

- AccessResult
- Application Configuration
- Application Context
- AppContextElement
- AttributeValueEnumeration
- AuthenticIdentity
- ContextAuditRecord
- HashMapContext
- IdentityRole
- NameAttributeType
- NameAttributeValue
- NamedObjects
- NamingAuthority
- NamingAuthorityManager
- PolicyDomain
- RuntimeAction
- RuntimeResource
- SecurityRuntime
- ServiceType
- ServiceVersion
- SimpleContextElement

## AccessResult

An`AccessResult` is the object returned to an Java Security Service Module application after an access decision is made. Primarily, this object returns a Boolean value as to whether access is permitted (`true`) or denied (`false`) through its `isAllowed()` method. The `AccessResult` object also returns a date and time as to when the decision was evaluated and optionally lets an application re-query the decision without having to locate the original arguments.

## Application Configuration

The application configuration is a representation of your application that you pass into the Java Security Service Module when you initialize it. The application configuration is passed in as the `AppConfig` object. The `AppConfig` object is used to configure a runtime based on the configuration of your application. The `AppConfig` object supports a method for adding an XML file that contains naming authority definitions to the configuration object. On initialization of the Java Security Service Module, this XML file is loaded into the Naming Authority Manager.

## Application Context

The application context is a description of the environment as it relates to your application. It is a collection of names and values that the security providers can query to get information from the application. Thus, the application context enables the providers to react appropriately and to be configured properly. Specifying the application context also allows the application developer to publish name/value pairs from within the application to the Java Security Service Module runtime. The Java Security Service Module may use these values to assist it in providing security decisions or information.

Note: `The com.bea.security.HashMapContext` class provides a sample implementation of an `AppContext` interface. As a developer, you have the option of using the `HashMapContext` class within an application as the specific way to implement an `AppContext` object or using the `com.bea.security.AppContext` interface to implement your own version.

## AppContextElement

The `AppContextElement` interface is a simple interface for representing a name/value pair. This interface is applied to application specific context entries so that those values can be evaluated as context to a security decision. `The SimpleContextElement` class provides a sample implementation of an `AppContextelement`.

## AttributeValueEnumeration

The `AttributeValueEnumeration` class is used to implement naming authorities. The `AttributeValueEnumeration` class is a representation of an ordered list of name attribute values. This class is used to return an ordered list for named objects. It provides an enumeration interface to the ordered list as well as several methods to return different views of that list. This class is used and consumed by named objects for constructing string names.

## AuditRecord

The `AuditRecord` class allows a user to log an audit message conforming to a naming convention.

## AuthenticIdentity

The `AuthenticIdentity` class represents an authenticated person or process. There is also a special case of `AuthenticIdentity` that represents the anonymous, or non-authenticated user. This class is meant to be an opaque representation of the user. The `toString()` method provides a human readable string that represents this identity suitable to display or for logging.

## ContextAuditRecord

The `ContextAuditRecord` class allows a user to log an event or audit message that conforms to a naming convention and automatically extracts elements of the event from the application context of the event.

## HashMapContext

The `HashMapContext` class is a simple implementation of an application context based on top of a java hashmap. Applications may choose to use this class as a basis for their application context or implement their own.

## IdentityRole

An `IdentityRole` is any representation of a canonical role assigned to an identity for a particular resource, action, and application context. An `IdentityRole` contains a role name and a description. The `IdentityRole` class represents a role assigned to an identity. You use the `com.bea.security.RoleService`.`getrole()` method to get the appropriate set of roles assigned to an identity. For example, an `IdentityRole` for `admin` includes a description that says administrators can do this or that. An `IdentityRole` is read only.

## NameAttributeType

The `NameAttributeType` class is used to implement naming authorities. The `NameAttributeType` class represents a single named field within a name as defined by a naming authority.

## NameAttributeValue

The `NameAttributeValue` class is used to implement naming authorities. The `NameAttributeValue` class subclasses `NameAttributeType` adding a value in addition to the type. `NameAttributeType` is the class used when a name is tokenized by its naming authority.

## NamedObjects

The `NamedObject` class is used to implement naming authorities. The`NamedObject` is the base class for all objects managed by a naming authority. It provides accessor functions for consumers of name managed objects and core fields that reference which naming authority manages this object and whether or not this object is validated. In the BEA AquaLogic Enterprise Security environment, a named object is any object that conforms to a naming code, structure, or convention. There are four types named objects: `AuditRecord`, `ContextAuditRecord`, `RuntimeAction`, and `RuntimeResource`.

You define the structure of named objects when you design and implement the naming authority that your Java Security Service Module application uses. Because the named objects conform to the naming conventions and structures that you specify in the naming authority, the BEA AquaLogic Enterprise security providers can consult the naming authority and determine what values are contained in the object. Thus, named objects along with naming authorities provide a data-driven way for your application to control which named objects are supported and to define the structure of and the values used by those objects. This capability, in effect, removes all limitations on the naming and structure of objects that can be supported by applications developed using the Java Security Service Module APIs and the Security Services Provider Interfaces (SSPI).

## NamingAuthority

The `NamingAuthority` class is used to implement naming authorities. The `NamingAuthority` class is the base class for all instances of naming authorities. If an application programmer wants to implement a naming authority in Java to streamline name parsing, this class would the base class. Default implementations of the `getTokenEnumeration` and `getDeepTokenEnumeration` functions are provided in this base class as a convenience to application developers.

## NamingAuthorityManager

The `NameAuthorityManager` class is used to implement naming authorities. The `NameAuthorityManager` class is a central registrar for all naming authorities that the Java Security Service Module recognizes. Within an Java Security Service Module if the name is not registered with its naming authority's manager, then the name effectively does not exist.

This class is also responsible for managing the dependencies of the naming authorities. If a naming authority's dependencies are not met, then it will not be available to the Java Security Service Module runtime. The naming authority remains associated with the Naming Authority Manager, and every time a new authority is added, it's dependencies are re-evaluated and enabled once the dependencies are all met. This class is also responsible for loading XML definitions of authorities and validating them.

## PolicyDomain

The `PolicyDomain` class is used to implement naming authorities. The `PolicyDomain` object provides security services to an Java Security Service Module application that is scoped within a single policy domain. This object allows an application to determine which services are available and create instances of services.

## RuntimeAction

The `RuntimeAction` object represents an action or privilege to the Java Security Service Module runtime. `RuntimeAction` is a `NamedObject` and, therefore, is managed by a naming authority that determines its format and delimiters.

## RuntimeResource

The `RuntimeResource` object represents a resource to the Java Security Service Module runtime. A `RuntimeResource` is a `NamedObject` and, therefore, is managed by a naming authority that determines its format and delimiters. A `RuntimeResource` also contains functions that allow it to return a reference to its parent or a sibling (as determined by a string suffix) or a child (as determined by a string suffix). Each parent reference is managed by the naming authority as the original resource.

## SecurityRuntime

The `SecurityRuntime` object is the largest abstract concept within an Java Security Service Module application. The `SecurityRuntime` class provides a way for the Java Security Service Module application to query the runtime for its capabilities and to fetch several other application level resources. Specifically, `SecurityRuntime` objects are used to initialize, instantiate, and fetch `PolicyDomain` objects for use within an application, and to fetch the instance of the Naming Authority Manager. The Java Security Service Module runtime provides your application environment. There can only be one runtime of a certain type in a specific application environment.

An application usually has one policy domain, although container applications can have more than one. In the Java Security Service Module API, a `PolicyDomain` object aggregates services related to that policy domain into one interface. To get an instance of a `PolicyDomain` object, a Java Security Service Module application developer writes code to initialize and fetch an instance of the `SecurityRuntime` object (a singleton). Once this instance is fetched, the application can query the runtime to ensure that a policy domain exists, and then create an instance of a policy domain.

## ServiceType

`ServiceType` indicates what type of service is available. The `com.bea.security.ServiceType` class represents a service that is offered for use by the application and the Security Service Module runtime. Five service types are supported by the `ServiceType` class to facilitate their use in your applications: Audit Service, Authentication Service, Authorization Service, Credential Mapper Service, and Role Service. However, you may expand the service types beyond the knowledge of the `ServiceType` class and used them with Java Security Service Module applications.

## ServiceVersion

The`ServiceVersion` is an encapsulation of the current version of the service and is useful for managing compatibility within your application. The `com.bea.security.ServiceVersion` class is used to represent a service version. A service version contains a major number, minor number, and a string for the patch number (which is represented as a string), for example 1.0sp1, or 1.1sp2, etc.

When the service type is returned by the service, the application can determine which version of the service is running on the instance of a Java Security Service Module runtime in use. The service version can then be used by the application to determine whether the application is compatible with the service that is running. For example, if you have programmed your application to be compatible with Authentication Service version 1.0, then you can instantiate an Authentication Service version 1.0, pass it into the Authentication Service using the `com.bea.security.AuthenticationService.isCompatible` method. The `isCompatible` method returns `COMPATIBLE`, `NOT_COMPATIBLE`, `COMPATIBLE_DEPRICATED`, or `COMPATIBLE_UNKNOWN` to indicate whether or not the Authentication Service API that you just fetched is compatible with API version 1.0.

## SimpleContextElement

The `SimpleContextElement` class is used with `HashMapContext` for Java Security Service Module applications that want to present their context information using these simple classes.