Programming with the Security System API

This chapter explains about programming with the security system API.

1. Overview

This chapter explains how to develop programs with the security system API to add user’s own security features to user applications. For example, there is the registration Servlet (called "auto-registration") that automatically registers a new user to the JEUS security system by using an application.

Before developing a security service, application programmers should check whether the standard Jakarta EE security model and the JEUS security services support the desired security features. Developing a program using the security API will decrease the compatibility between Jakarta EE servers. It is recommended to use only the standard Jakarta EE security interfaces to maintain the compatibility.

2. Configuring Java SE Permissions

The security system API can be used to protect the JEUS system from malicious user code (Servlet or EJB) injections.

The security API can be used for user codes (Servlet or EJB) in the case when the Java security manager is used, or when the source code (Servlet, EJB) successfully logs in using the LoginService.login (Subject) method. In this case, the Subject is the subject of the user defined in the accounts.xml file in the target security domain and has the necessary JEUS Permission configured in the policies.xml file.

For more information about how to configure each file, refer to the following:

3. Basic API

The following classes in the jeus.security.base package play an important role when working with the security system at the application programming level.

Class Description

jeus.security.base.Subject

A user.

A Subject has a single main principal, which acts as the Subject ID (username). Several string property values may be sent to the jeus.security.base.Subject class.

jeus.security.base.CredentialFactory

The member variable of the Subject class. It is used to create the actual credentials of a Subject.

For example, the PasswordFactory class creates a password credential instance, and the JKSCertificateFactory class gets a certificate from JKS keystore and creates a credential instance for a certificate.

jeus.security.base.Policy

Represents a single principal-to-role mapping and several role-to-resource mappings. Contains PermissionMaps as a member variable.

jeus.security.base.PermissionMap

The container for java.security.Permission instances and the member variables of the Policy class.

jeus.security.base.Role

The interface that represents a logical role.

In role-to-resource PermissionMap, the role instance is mapped to the resource permission. In the same way, in principal-to-role PermissionMap, the principal is mapped to role permission.

jeus.security.base.SecurityCommonService

Authenticates the subject and checks the permission for the Subject.

jeus.security.base.SecurityException

The exception that occurs due to a security violation, such as failed login, failed authentication, and failed authorization.

jeus.security.base.ServiceException

The exception that occurs due to a critical runtime error in the security system.

4. Resource API

As well as the basic classes in the jeus.security.base package, the classes in the jeus.security.resource package also play an important role related to resources.

Class Description

jeus.security.resource.PrincipalImpl

The implementation class of the java.security.Principal interface.

jeus.security.resource.GroupPrincipalImpl

The subclass of PrincipalImpl that represents group principals and the implementation class of the java.security.acl.Group that manages members of the related nested groups.

jeus.security.resource.Password

A simple Password Credential instance. It is created by the PasswordFactory.

jeus.security.resource.PasswordFactory

The CredentialFactory that creates the Password Credential.

jeus.security.resource.Lock

A credential that locks the relevant subject.

Any attempt to login to the locked subject will always fail.

jeus.security.resource.LockFactory

The CredentialFactory that creates the lock credential.

jeus.security.resource.ExpiryTime

A credential. Sets the expiration of the subject.

Any attempt to login with the subject, that has already expired, will always fail.

jeus.security.resource.ExpiryTimeFactory

The CredentialFactory that creates the ExpiryTime.

jeus.security.resource.RoleImpl

The class that implements the role interface.

jeus.security.resource.RolePermission

The subclass of java.security.Permission that represents a particular principal belonging to a particular role. The RolePermission is used to express principal-to-role mapping.

jeus.security.resource.TimeConstrainedRolePermission

A sub class of RolePermission that represents a principal being in the role expressed by the its super class only during the specified time period.

jeus.security.resource.ResourcePermission

The subclass of java.security.Permission that expresses the concept that a role can access a resource and perform particular actions.

ResourcePermission is used to express role-to-resource mapping.

For more information about the classes, refer to the Javadoc and References.

5. SPI Class

To communicate with the services that are the foundation of the security system, use the following SPI classes from the jeus.security.spi package.

Class Description

jeus.security.spi.AuthenticationRepositoryService

Used to add, remove, and search for Subject to/from a Subject repository. A Subject (user) can be added within the program using this class.

jeus.security.spi.AuthorizationRepositoryService

Used to add, remove, and search for Policy data to/from a Policy repository. Permission can be added within the program using this class.

Refer to the Javadoc and References for more information. Also refer to Developing Custom Security Service for more information about these SPI classes.

6. Example

The following shows how to develop a program with the security API.

// Login the CodeSubject so that security checks are
// disabled (so that we can modify the Subject and Policy
// stores)
SecurityCommonService.loginCodeSubject();

// Make Subject with Principal “pete”
Principal petePrincipal = new PrincipalImpl(“pete”);
Subject pete = new Subject(petePrincipal);

// Make password “petepw” for Subject “pete”
PasswordFactory pf = new PasswordFactory(“petepw”);
pete.getCredentialFactories().add(pf);

// Add new Subject to the Subject store
AuthenticationRepositoryService.addSubject(pete);

// Make a new Policy
Policy policy = new Policy();

// Make role “someRole”
Role someRole = new RoleImpl(“someRole”);

// Make a RolePermission for role “someRole”
Permission rolePermission = new RolePermission(someRole);

// Add the RolePermission for “someRole” to the Policy
policy.getRolePolicy().addPermission(
     rolePermission, new Object[] {petePrincipal}, false, false);

// Create a ResourcePermission for resource “rsc1” with actions
// “action1” and “action2”
Permission rscPermission =
new ResourcePermission(“rsc1”, “action1,action2”);

// Add the ResourcePermission to the Policy using
// context id “ctx1”
policy.getResourcePolicy(“ctx1”, true).addPermission(
     rscPermission, new Object[] {someRole}, false, false);

// Add the new Policy to the Policy store
AuthorizationRepositoryService.addPolicy(policy);

// Logout the CodeSubject so that security checks are
// enabled again
SecurityCommonService.logout();

// Make a Subject to be logged in
Subject pete2 = Subject.makeSubject(“pete”, “petepw”);

// Login Subject “pete” (should succeed since we added
// “pete” earlier)
SecurityCommonService.loginDefault(pete2);

// Check ResourcePermission “rsc1” for current Subject (“pete”)
// Should succeed since we added Policy for this above
SecurityCommonService.checkPermission(
     “ctx1”, new ResourcePermissin(“rsc1”, “action2”);

// Print the name of the current Subject (“pete”)
System.out.println(
SecurityCommonService.getCurrentSubject().getPrincipal().getName());

// Logout “pete”
SecurityCommonService.logout();