Skip navigation.
Downloads | Product Documentation | Support

Programming Security For Java Applications

# Java Security Service Module APIs

To develop Java Security Service Module (SSM) applications, you use the Java interfaces and classes developed by BEA Systems and by Sun Microsystems, Inc.

This section covers the following topics:

- Java Security Service Module APIs on page 4-1.
- Java SDK APIs on page 4-6.

# Java Security Service Module APIs

The `com.bea.security` package contains all the BEA developed interfaces, classes, and exceptions that are supported by the Java Security Service Module.

This section lists and describes the key interfaces and classes that you use to develop Java Security Service Module applications. For a complete listing and description of the interfaces, classes, and exceptions included in the `com.bea.security` package, see Javadocs for Java API.

The key interfaces and classes are described in the following topics:

- AuthenticationService API on page 4-2.
- AuthorizationService API on page 4-3.
- AuditingService API on page 4-3.
- RoleService API on page 4-4.
- CredentialMappingService API on page 4-5.

## AuthenticationService API

The authentication service provides functions to an application related to establishing, verifying, and transferring a person or process identity. Thus, the authentication service provides two main functions: authentication and identity assertion.

The type of authentication supported is determined by the providers configured for the Java Security Service Module through the Administration Application. Each provider requires the Java application to respond to a callback specific to the type of authentication used by the Java application. The application is responsible for collecting the necessary credentials through user interaction.

The type of assertion token supported is also determined by what providers are configured in the Java Security Service Module runtime through the Administration Application. Each provider may implement one or more identity assertion token types.

An additional feature related to identity assertion is the ability for an identity assertion provider to provide a challenge first, which the Java Security Service Module application then has to process in an implementation dependant way before redeeming that token for an identity. Not all assertion providers support this challenge capability so knowledge of the configured provider is required when using this feature.

The `AuthenticationService` API is intended to provide a minimum level of limitation on the Java Security Service Module application concerning the use of features embodied by the authentication providers. Certain elements of this API are implemented according to the standard established by the Java Authentication and Authorization Service (JAAS). The use of the standard JAAS `CallbackHandler` interface and of the standard JAAS callbacks themselves provides a common and familiar means for application developers to authenticate users.

Elements of the identity assertion functions in this API rely on an assertion token name and an object reference. It is the responsibility of the authentication provider to choose suitably unique token names to represent the various types of tokens that it supports. It is possible, however, to have several authentication providers that support tokens described by the same token name. However, if these providers are configured within the same Security Service Module configuration for authentication, the results are undetermined, so it is not recommended that this be done. The object reference associated with an identity assertion token name is merely a way to pass a relevant object to the appropriate provider.

For more information on the `AuthenticationService` API and the methods it supports, see Javadocs for Java API.

## AuthorizationService API

The authorization service is a service that allows an application to determine if a specific identity is permitted to access a specific resource. This decision may then enforced in the application directly at the policy enforcement point.

This service revolves primarily around variations of the `isAccessAllowed()` method. At a minimum, this method collects information about the identity of the accessor, or requestor, the resource the accessor is attempting to accessed, and the action the accessor is attempting to perform on that resource. The longer form of this method supports passing in an `AppContext` object that makes available name/value pairs that security providers may use in their security evaluation.

The `isAccessAllowed()` method always requires that a valid, authenticated identity be present when requesting an access decision. For more information about using this method, see the Javadocs for Java API for the `com.bea.AuthorizationService.isAccessAllowed()` method.

The `AuthorizationService` API also provides the `isAuthenticationRequired()` method. This method provides a mechanism that an application can use to test to see whether the Java Security Service Module requires authentication to access any specific resource.

## AuditingService API

The auditing service allows an application to log events based on activity related to enterprise security. The Java Security Service Module runtime uses these mechanisms to log appropriate data when events occur.

The `AuditingService` API is based on an event model. When something of note occurs, an application can derive a new class from the `AuditRecord` class or use the `AuditRecord` directly as it is a named object.

The Auditing Service is based on a single method, `recordEvent()`. This method accepts an object of the type `AuditRecord`, which encapsulates the logged information, and then passes it to the Java Security Service Module runtime. Based on its configuration, the Security Service Module runtime routes the event to the proper auditing providers so that it can be recorded.

For more information on the AuditingService API and the methods it supports, see Javadocs for Java API.

## RoleService API

The role service allows an application to extract role information about specific identities and resources within the context of the application. These roles can then be used for customizing an interface or other purposes.

Note: Do not use roles themselves as authorization, because many policies allowing or disallowing access to a resource may be written against a role. Use the Authorization Service to determine actual rights.

The Role Service evaluates an interaction of an identity with a resource within an application context and returns a list of role names associated with the configuration of that identity. These roles can change with every resource or be static for the identity across all resources. The roles assigned to an identity are determined by the policy written within the policy domain.

The RoleService requires that the application pass in a valid identity, a valid resource, and a valid action. The application context is optional and may be set to `null` if no context is passed in.

The `RoleService` API has one key method that supports its primary function, `getRoles()`. This method gets the roles for an `AuthenticIdentity` in reference to a `RuntimeResource`, `RuntimeAction`, and an optional `AppContext`. Table 4-1 describes the `getRoles()` method parameters.

Table 4-1 getRoles Method Parameters

Parameter | Description
--- | ---
`AuthenticIdentity ident` | Identifies the user with which the roles are associated.
`RuntimeResource` resource | Represents the Java Security Service Module runtime resource for which the roles are present.
`RuntimeAction action` | Represents the Java Security Service Module runtime action for which the roles are relevant.
`AppContext context` | Specifies an object with an `AppContext` interface that contains the name/value pairs that represent this application's current context.

The `getRoles()` method returns a vector of `IdentityRole` objects that lists the roles associated for this identity. If the identity provided is invalid or not properly authenticated, this method throws an exception.

For more information on the `RoleService` API and the methods it supports, see Javadocs for Java API.

## CredentialMappingService API

The credential mapping service allows an application to fetch credentials of certain types that are associated with a specific identity for a specific resource. These credentials can then be used on behalf of that identity to provide some privileged function, such as logging into a database or sending e-mail.

The `CredentialMappingService` API has one key method that supports its primary function, `getCredentials()`. This method gets a set of credentials relevant to a specific resource and action for an AuthenticIdentity. Table 4-2 describes the `getCredentials()` method parameters.

Table 4-2 getCredentials Method Parameters

Parameter | Description
--- | ---
`AuthenticIdentity byident` | Identifies the AuthenticIdentity of the user requesting this credential set.
`AuthenticIdentity` forident | Identifies the AuthenticIdentity of the user for whom the credentials are being fetched
`RuntimeResource` `resource` | Represents the Java Security Service Module runtime resource relevant to this credential mapping.
`RuntimeAction action` | Represents the Java Security Service Module runtime action relevant to this credential mapping.
`java.lang.String[] credtypes` | Specifies an array of `Strings` containing the credential types requested.

The `getCredentials()` method returns a vector of credentials relevant for the types requested as follows:

- Password-based credentials are returned as an instance of the `javax.resource.spi.security.PasswordCredential` class.
- Other credentials are returned as a class that implements the `javax.resource.spi.security.GenericCredential` interface.

Note: Additional credential formats can also be returned. The caller is responsible for detecting and casting the credential formats to the appropriate Java class.

The user identities passed in using the `getCredentials()` method can contain any names, valid or invalid. If credentials are present matching that name (case sensitive), then they are returned. Any names requested, but not available, are ignored. This presents the possibility of an empty vector being returned with no exception thrown.

The `getCredentials()` method accepts an identity for the user for whom credentials are requested and an identity for the user querying for the credentials. Thus, the `getCredentials()` method must have two authenticated identities. If either of the identities is not valid or not properly authenticated, an exception is thrown. Additionally, the security policy must permit the user requesting the credentials to fetch the credentials of the other identity, or to fetch the credentials for themselves if they one and the same identity.

For more information on the `CredentialMappingService` API and the methods it supports, see Javadocs for Java API.

# Java SDK APIs

The following Java SDK APIs can be used with the BEA WebLogic Enterprise Security API:

- Java 2 Platform Standard Edition v1.4.2.
- Java 2 Platform Enterprise Edition v1.4.