The Akula security mechanism requires that you connect an app scope to an authentication realm, where the realm contains a collection of users and groups. To function as a security realm, the realm must contain at least one user group, and there must be a class implementing the  AKRealm interface that defines the connection between the realm and the Akula Server. 

For example, you can use Active Directory as your realm. To define the connection to an Active Directory server, Akula includes the com.verivo.security.realms.activedirectory.AKActiveDirectoryRealm class to define the connection. 

Alternatively, you might have your own mechanism for defining a security realm. It could be a database, an authentication server, or some other mechanism. If so, you can create your own custom class that defines the connection between your realm and the Akula Server.

This document describes how to create a custom class to connect to your realm, and contains the following sections:

Implementing AKRealm to define the connection to a security realm

The AKRealm interface defines the methods that a class must implement to connect a realm to the Akula Server. You do not call these methods directly; the Akula Server calls them as necessary to communicate with your realm.

The following table describes the methods of the AKRealm interface that you must implement:

Types of information required by the custom realm class

Along with the five methods of the AKRealm interface that you must implement, your custom class might also require other information to connect to your realm, including:

• Location of the realm, such as a URL.
• Connection credentials, such as username and password, required to access the realm.
• Location in the realm of user information, such as first name, last name, full name, and user name.
• Whether passwords stored in your realm use a salt to encrypt the passwords. The realm classes provided by Verivo all allow for the use of a salt to encrypt passwords. While it is not required, you typically use a salt to encode the password in your realm.

As an example, you can review the information required by the Active Directory realm described here Using Active Directory Server as an Authentication Realm.

Returning user information in the AKAuthInfo object

The Akula Server calls the getAuthenticationInfo() method of your custom class to validate a user. This method has the following signature:

If the credentials in the AKAuthToken object are invalid, then the method throws one of the possible exceptions describing the error. The Akula Server then returns that information to the client.

If the credentials in the AKAuthToken object are valid, the getAuthenticationInfo() method returns an AKAuthInfo object to the Akula Server. The Akula Server then validates the information returned in the AKAuthInfo object to make sure that it represents the same user as did the AKAuthToken object passed to the getAuthenticationInfo() method.

The AKAuthInfo object defines the following getter methods that the Akula Server uses for this validation:

If the Akula Server validates the AKAuthInfo object, the server then uses the AKAuthInfo object to construct the response sent back to the client app. On a successful log in, as described in Authenticating Users, the Akula Server returns a session token, log-in timeout value, and other information. The client app automatically writes that information to AKSession, AKUser, and AKPermissions objects (Android and iOS) and AK.Session, AK.User, and AK.Permissions objects (JavaScript) on the client.

Information written to the AKUser and AK.User objects includes any information returned by the AKUserPrincipal.getInfo() method, such as first name, last name, full name, and user name. However, information returned by the the AKUserPrincipal.getServerInfo() method is not returned to the client. That information is for use on the server only. The information in the AKUserPrincipal object is not required to be returned by your realm. If the AKAuthInfo object does not include that information, then the client response omits those values.

Referencing your realm in a security manager definition

The AKULA_HOME/global/security-template.xml file defines the security managers available to an app scope, where each security manager includes a definition of a realm. For more information, see Defining a Security Manager.

For example, you define a class named my.company.com.MyCustomDirectoryRealm that implements the AKRealm interface. You can then use the following definition in security-template.xml file to reference your custom realm:

In this example, the <realm> tag specifies the id of the realm and the class defining the connection to your realm. The <realm-ref> in the <security-manager> tag references your custom realm by its id to include it in the security manager definition.

Accessing information in the security-template.xml file

In the example above where you add your custom realm to the security-template.xml file, the <realm> tag  only specified the name of your class. Therefore, all configuration information about the realm must be hard coded in the class. The downside of this implementation is that your custom class is not reusable across different configurations of your custom realm.

To make your custom realm class more flexible, your custom class can read configuration information from the security-template.xml file at run time. This configuration information can be any type of information required by your class, such as the location of the realm, information about the realm, or any other information required to connect to the realm.

The following example adds <property> and <object> tags to the <realm> tag for your custom class:

To pass the value from the security-template.xml file to your class, the Akula security mechanism automatically calls a public setter method in my.company.com.MyCustomDirectoryRealm for every <property> tag in security-template.xml. The setter method has the form:

setKeyname()

where Keyname is the name of the key attribute with an initial capital letter. In your custom class, you specify the data type of the argument to the setter to match the value of the key.

For every setter method, you must also include the corresponding public getter method, as shown below:

getKeyname()

For example, for the following <property> tag:

<property key="name">MyCustomRealm</property>

You define the following setter and getter methods in your class that are called automatically by the Akula Server:

public void setName(String val)
public String getName()


For the dataSource key, the data type of the object is my.co.com.DataSource. Therefore, your custom class would define a setter and getter in the form:

public void setDataSource(my.co.com.DataSource obj)
public my.co.com.DataSource getDataSource()


Example implementation of AKRealm

Akula ships with the com.verivo.akula.security.realms.jdbc.AKJdbcRealm class that defines a connection to a JDBC database for use as the realm. Example databases that you can use as a realm include Microsoft SQL Server 2012, Oracle, and MySQL. However, any database that supports JDBC should work. Download the AKJdbcRealm class source code from here.

To help you get stated implementing your own class to connect to a security realm, Akula ships the source code for the AKJdbcRealm class. This class includes the implementation of the AKRealm methods, and also includes setter methods for properties that you can set in the security-template.xml file. These setter methods include:

The following example shows a security-template.xml file that configures a realm using the AKJdbcRealm class:

In the <object> tag that defines the ds key value, you can use the AKULA_HOME environment variable to define the URL, as the following example shows:

Notice that the AKULA_HOME environment variable is must be enclosed in braces, "{}".

Compiling and deploying your custom class

Compile your custom class into a JAR file and deploy the JAR file in the AKULA_HOME\global\lib directory. That makes the JAR file available to all app scopes.