Chapter 5. Developing Customized Security Services

Table of Contents

5.1. Overview
5.2. Service Class
5.3. The Basic Pattern of Implementing Custom Security Services
5.4. SPI Class
5.4.1. SubjectValidationService SPI
5.4.2. SubjectFactoryService SPI
5.4.3. AuthenticationService SPI
5.4.4. AuthenticationRepositoryService SPI
5.4.5. IdentityAssertionService SPI
5.4.6. CredentialMappingService SPI
5.4.7. CredentialVerificationService SPI
5.4.8. AuthorizationService SPI
5.4.9. AuthorizationRepositoryService SPI
5.4.10. EventHandlingService SPI
5.4.11. Dependencies between SPI Implementations
5.5. Security Services Configurations

This chapter describes how to develop custom security services, which is a key feature of the JEUS security system.

Using this feature, users can easily integrate the JEUS security system with various kinds of external security systems or security data repositories.

The following sections describe how to develop the custom security services.

The most basic class of the pluggable security architecture is the classjeus.security.base.Service class.

The Service class is an abstract class that must be extended by all security service implementation classes. Currently, all available security SPI classes in the eus.security.spi package extend this class.

The following is the class diagram for the Service class.


The Service class provides a few basic things that apply to all security services.

This section briefly describes how to implement the custom security services.

The following are required to implement a customized security service.

  1. Users must have a general understanding of the security system and its architecture.

  2. Choose the security functions that the custom security service needs to provide.

  3. Choose the SPI class that has the necessary features. For more information about main SPI classes, refer to "5.4. SPI Class".

  4. Refer to the documents for information on SPI class. (Refer to Javadoc, References, and "5.4. SPI Class".)

  5. Make a sub-class of the selected SPI class and implement the following methods. An empty public constructor without parameter must be provided.

    1. Optionally define a set of properties that are used to initialize services. Each property is a public static final string type and what each property represents must be documented.

    2. Implement the doCreate() method. This method will be called once when the security service is started and it performs general initialization operations such as resource allocation. This method reads the property values using the getProperty() method. The parameter of the getProperty() method is the property name that was defined in the previous step.

    3. Implement the doDestroy() method. This method is called once when the service is terminated. The method should release any resources that were allocated during the doCreate() method call and also perform clean-up operations such as writing logs to a certain file.

    4. Implement all abstract methods in the selected SPI class as specified in the Javadoc.

    5. Optionally implement the methods to be used for managing the service through JMX. Implement the getMBean() or getMBeanInfo() method.

  6. Compile the class that implements SPI.

  7. Register the new security service with JEUS as described in "Chapter 2. Configuring the Security System".

The following SPI classes are defined in the jeus.security.spi package.

The following is the list of SPI classes defined in the jeus.security.spi package. The cardinality indicates how many SPI instances can exist for each security domain.


The jeus.security.spi.SubjectValidationService SPI is used to check whether all the credentials held by a subject are valid. This means that there should be no invalid credentials for any reason. An invalid credential means that the Subject is invalid and consequently that the subject should not be allowed to log in.

A typical use for the SubjectValidationService instance is to check whether the subject contains a lock credential. If so, it can be concluded that the subject is locked out and that any login process should not be allowed to proceed.

Thus, the SubjectValidationService.checkValidity(Subject) method is usually called during the login process. If a SecurityException occurs, the login process will fail. EventHandlingService class is used to automatically configure a lock credential for the subject. For more information, refer to "5.4.10. EventHandlingService SPI".

Note that the issue of authentication (verifying whether the returned subject corresponds to the actual subject) is different from the validation of the Subject. Authentication and validation are not dependent upon one another. However, login is dependent on both, as already mentioned.

ZERO OR MORE SubjectValidationService instances can be configured for each domain. If no SecurityException occurs during the SubjectValidationService process, the subject is regarded as valid, and the login process is allowed to proceed. However, if at least one SecurityException occurs, the overall validation will fail and the login must NOT be allowed to proceed.

Note

SubjectValidationService SPI class is functionally different from the CredentialVerificationService class.

SubjectValidationService checks the credential to determine the validity of the subject. CredentialVerificationService checks if the subject has at least one credential to prove its authenticity. So the SubjectValidationService class is used after the subject has been successfully authenticated, while CredentialVerificationService class is used during the process of authentication in the AuthenticationService class.

The jeus.security.spi.AuthenticationService class is used to authenticate a Subject. It is used to verify that the subject, which was received as a parameter, indeed corresponds to the subject that is registered with the subject repository.

The authentication procedure is as follows:

  1. Calls the jeus.security.spi.CredentialMappingService.getSubjectName(Object) in the login mechanism to check for the user the credential of the subject is mapped to.

  2. Calls the jeus.security.spi.AuthenticationRepository.getSubject(String username) method to copy the registered subject from the subject repository to the local server. This is called a local subject.

  3. If the local subject is not null, check whether the credential of the local subject matches that of the subject that needs to be authenticated. The comparison can be done by calling the SPI method, jeus.security.spi.CredentialVerificationService.verifyCredentials(Subject, Subject).

    In some cases, equals(Object) method is used to compare the credentials, but it lacks flexibility.

  4. Finally, if all of the previous steps were completed successfully, the local Subject is returned from the authenticate(Subject) method and eventually, that Subject will be used to log into the SecurityCommonService.

ONE OR MORE AuthenticationService instances can be configured for each domain. If at least one of the configured AuthenticationService instances is successfully authenticated, the entire AuthenticationService will regard the authentication as successful. If one instance successfully authenticates the subject, no additional AuthenticationService will be queried.

jeus.security.spi.CredentialVerificationService SPI is used to support a new type of Proof Credential.

Proof Credential is a kind of credential that may be used to prove the authenticity of the Subject that is returned as a parameter, which means that it corresponds to an existing subject. A typical example of the proof credential is a password that is implemented by the jeus.security.resource.Password class.

CredentialVerificationService SPI essentially declares the doVerifyCredentials(Subject, Subject) method, which is one method that must be implemented by its sub-class. The first subject in the signature of this method is the reference Subject, which contains the credentials of the actual subject that is registered with the subject repository. The second argument is the proof Subject, which contains the proof credentials. The doVerifyCredentials(Subject, Subject) method compares the credentials of the two subjects and checks for a match.

The matching between credentials may be done in a number of different ways (just using the equals(Object) method may not be enough). If the credentials of any two subjects match, the method will return, otherwise, a jeus.security.base.SecurityException will occur.

Note

In some cases, it is not necessary to actually use the information of the reference subject. Certain proof credentials can be checked by using only the information of the proof Subject, such as a Certificate Credential.

The CredentialVerificationService that matches with the jeus.security.resource.Password is the jeus.security.impl.verification.PasswordVerificationService class.

ZERO OR MORE CredentialVerificationService's can be configured for each domain. If at least one match is found in the CredentialVerificationService, the entire CredentialVerificationService verification is regarded as a success. Otherwise, a SecurityException occurs and the entire verification is regarded as a failure, and the authentication will fail.

EventHandlingService SPI is an interface that captures and processes various security events.

Using the EventHandlingService SPI, users can easily implement operations, including logging and sending a notification email to the administrator when a security event occurs, setting a lock on a subject, etc.

The basic concepts are very simple: the occurrences of jeus.security.base.Event's in the security service will be notified to all EventHandlingService's in the domain. Then EventHandlingService handles the event according to its content.

For example, an EventHandlingService can be used when a lock needs to be applied to a Subject. Whenever the AuthenticationService fails to authenticate a Subject, it will generate a security.authentication.failed Event. The lockout EventHandlingService catches this event and executes the handleEvent(Event) method. In the method, a login counter is kept and when it reaches a certain value (such as 3), a lock credential is applied to the Subject.

Then SubjectValidationService confirms that the subject is locked, and as a result, all attempts to log in using this Subject will fail. Thus, by using EventHandlingService with SubjectValidationService, user can implement a function that prohibits a subject from logging into the system if it fails to log in three times in a row.

However, the most common use of the EventHandlingService SPI is probably to implement various kinds of security loggers that record events. The events can be written in a text file, an XML file, or sometimes in an encrypted file to prevent repudiation.

ZERO OR MORE EventHandlingService's can be configured for each security domain.

After a new SPI implementation class is compiled, the class must be registered with the JEUS security system. For more information, refer to "2.3. Configuring Security Domain Components".