The API presented in this section is subject to change

Introduction

This section introduces the architecture and customizable API that can be leveraged to implement your own security requirements, or integrate with already existing standards (i.e. Spring Security}.

Before you start, consider the extensions of our default file-based implementation which allow you to replace the encoding and to reference a security file on an HTTP server.
This section assumes that you are familiar with the configuration concepts presented in Default Security - File-Based Directory.

Getting Started

The SecurityManager is the main interface from which your customization begins. It includes an authentication manager running at the server-side and an optional DirectoryManager for tooling.

In order to specify the custom implementation, you would need to provide the security configuration properties (as described in the Configuration section under "The Security Properties File". These properties should indicate the security-manager.class to instantiate, and other properties that may be used to initialize your custom implementation, accessed via the init method.

The Security Manager

A SecurityManager is constructed using the SecurityFactory#createSecurityManager(Properties securityProperties) method, based on the security-manager.class property key:

com.gs.security.security-manager.class = eg.mySecurityManager

The SecurityManager Interface has the following methods:

public interface SecurityManager {
    void init(Properties properties) throws SecurityException;
    Authentication authenticate(UserDetails userDetails) throws AuthenticationException;
    DirectoryManager createDirectoryManager(UserDetails userDetails) throws AuthenticationException, AccessDeniedException;
    void close();
}

The SecurityManager can be configured by custom properties supplied as part of the security properties file.

The authentication process

The authentication process of a principal is done at the server side. The SecurityManager#authenticate method is responsible for authenticating the UserDetails supplied as part of the authentication request.

Authentication authenticate(UserDetails userDetails) throws AuthenticationException;

The UserDetails are encrypted at the proxy and decrypted at the server. This encryption is internal to GigaSpaces. This should not be confused with the encryption used by your custom implementation to encrypt the user details/password. For example, our default file-based security implementation hashes the user password, and encrypts the file contents.

The Authentication object

The Authentication object returned by the authenticate method receives a UserDetails from which it extracts the authorities. After confirming the authenticity, the implementation must populate the UserDetails with the authorities extracted from some storage. The Authority can be constructed using an AuthorityFactory if it has been kept in its String representation.

Populating with authorities

The authorities returned are a flat representation of all the authorities this user has been granted. This means that if the user has been granted a role then the flat representation would be all the authorities this role represents.

You may find it convenient using our constructs. GigaSpaces security represents roles as an Authority. The RoleAuthority is a place holder for the role name. When populating a UserDetails a PopulatedRoleAuthority can be used to store the role-name and all the authorities it represents.

You can implement roles as you wish. As long as the authorities returned by UserDetails#getAuthorities() are a flat representation of all the authorities granted to this user.

User/Role management

The DirectoryManager interface provides an API for managing users and roles. Implementing this interface is optional - and is usually the case if you have an external tool that manages it for you.

From the DirectoryManager you can gain a UserManager interface and a RoleManager interface. Use the UserManager interface to create, delete, update UserDetails and the RoleManager interface to create, delete, update RoleDetails. This is just a logical separation - in reality you can choose how you want your users to be stored, and how you structure the one-to-many role to user relationship.

GigaSpaces security is not aware of the directory at all. As long as the authentication process manages to access the user storage, authenticate the user and return all its authorities.

Example usage of the DirectoryManager API

Securing the HelloWorld example

In the Hello World example, we presented a way to declare the users using the UI. It can also be done using the DirectoryManager API.

Using the API we would like to declare the following:

The "helloProcessor" user will be granted Take access for HelloObject and Write access for ProcessedHelloObject.
The "helloFeeder" user will be granted Write access for HelloObject and Read access for ProcessedHelloObject.

The GigaSpaces User is the default implementation of UserDetails. It accepts an array or a sequence of Authority-ies (varargs). Here we added the ClassFilter to restrict access to this specific class.

Properties securityProperties = new Properties();
SecurityManager securityManager = SecurityFactory.createSecurityManager(securityProperties);

DirectoryManager directoryManager = securityManager.createDirectoryManager(new User("admin", "admin"));
UserManager userManager = directoryManager.getUserManager();

userManager.createUser(new User("helloProcessor", "helloWorld",
        new SpaceAuthority(SpacePrivilege.TAKE, new ClassFilter("org.openspaces.example.helloworld.common.HelloObject")),
        new SpaceAuthority(SpacePrivilege.WRITE, new ClassFilter("org.openspaces.example.helloworld.common.HelloObject"))
));

userManager.createUser(new User("helloFeeder", "feedTheWorld",
        new SpaceAuthority(SpacePrivilege.WRITE, new ClassFilter("org.openspaces.example.helloworld.common.HelloObject")),
        new SpaceAuthority(SpacePrivilege.READ, new ClassFilter("org.openspaces.example.helloworld.common.HelloObject"))
));

directoryManager.close();
securityManager.close();

Custom UserDetails

The UserDetails interface provides core user information. The username and password are accessed by the default security implementation, but can otherwise be ignored.

The only requirement is for the SecurityManager.authenticate method to return an Authentication object, which is fully populated with authorities extracted from the UserDetails.

public interface com.gigaspaces.security.directory.UserDetails extends java.io.Serializable {
  public abstract com.gigaspaces.security.Authority[] getAuthorities();
  public abstract java.lang.String getPassword();
  public abstract java.lang.String getUsername();
}

At this time, the only way to provide your own custom UserDetails instance is using the API. The UI and CLI currently do not provide means for instantiating your custom UserDetails.

Examples:

UrlSpaceConfigurer urlSpaceConfigurer = new UrlSpaceConfigurer("/./space").userDetails( new MyUserDetails() );
GigaSpace gigaSpace = new GigaSpaceConfigurer(urlSpaceConfigurer).gigaSpace();

UrlSpaceConfigurer urlSpaceConfigurer = new UrlSpaceConfigurer("jini://*/*/space").userDetails( new MyUserDetails() );
GigaSpace gigaSpace = new GigaSpaceConfigurer(urlSpaceConfigurer).gigaSpace();

Admin admin = new AdminFactory().userDetails( new MyUserDetails() ).createAdmin();

...
admin.getGridServiceManagers().deploy(new SpaceDeployment("mySpace").userDetails( new MyUserDetails() ));

...
admin.getGridServiceManagers().deploy(new ProcessingUnitDeployment("myPu").userDetails( new MyUserDetails() ));