Chapter 4. Programming with the Security System API

Table of Contents

4.1. Overview
4.2. Java SE Permission Configurations
4.3. Basic API
4.4. Resource API
4.5. SPI Class
4.6. Example

This chapter explains about programming with the security system API.

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 J2EE security model and the JEUS security services support the desired security features. Developing a program using the security API will decrease the compatibility between J2EE servers. It is recommended to use only the standard J2EE security interfaces to maintain the compatibility.

The security apish 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, EJB, etc) 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.

Refer to the following to learn how to configure each file

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

ClassDescription
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.PolicyRepresents a single principal-to-role mapping and several role-to-resource mappings. Contains PermissionMaps as a member variable.
jeus.security.base.PermissionMapThe 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.SecurityCommonServiceAuthenticates the subject and checks the permission for the Subject.
jeus.security.base.SecurityExceptionThe exception that occurs due to a security violation, such as failed login, failed authentication, and failed authorization.
jeus.security.base.ServiceExceptionThe exception that occurs due to a critical runtime error in the security system.

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.

ClassDescription
jeus.security.resource.PrincipalImplThe implementation class of the java.security.Principal interface.
jeus.security.resource.GroupPrincipalImplThe 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.PasswordA simple Password Credential instance. It is created by the PasswordFactory.
jeus.security.resource.PasswordFactoryThe 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.LockFactoryThe 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.ExpiryTimeFactoryThe CredentialFactory that creates the ExpiryTime.
jeus.security.resource.RoleImplThe class that implements the role interface.
jeus.security.resource.RolePermissionThe 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.TimeConstrainedRolePermissionA 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.

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

ClassDescription
jeus.security.spi.AuthenticationRepositoryServiceUsed 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.AuthorizationRepositoryServiceUsed to add, remove, and search for Policy data to/from a Policy repository. Permission can be added within the program using this class.

Note

Refer to Javadoc and References for more information. Refer to "Chapter 5. Developing Customized Security Services" for more information about these SPI classes.

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();