Documentation

The Akula authentication mechanism relies on an external realm, where the realm contains the collection of users and groups that can connect to an app scope running on the Akula Server. For example, you can use Active Directory as your realm. For more information on defining realms, including setting realm properties in security-template.xml, see Connecting to an Authentication Realm.

When a user logs in to an app scope, the Akula Server creates a session to manage the user. You can specify an idle duration where the Akula Server automatically expires a session if the user is idle for the specified duration. Akula also supports distributed caching of session data that lets you share session information across multiple Akula Servers. For more information on distributed caching, see Configuring Session Caching.

A security manager defines the following information:

  • A realm
  • The session timeout duration
  • Optionally, a session caching strategy

You can create a single security manager, or you can create different security managers with different property values.

An app scope deployed on the Akula Server requires a security manager. Each app scope can use a different security manager, or you can share a security manager across multiple app scopes.

This page contains the following sections:

Defining a security manager

Define security managers in the AKULA_HOME\global\security-template.xml file. After editing the security-template.xml file, restart the Akula Server.

The following code shows an example security-template.xml file:

The example defines two security managers, named MyCompanyProduction and MyCompanyDevelopment, for production and for development. It also defines two Active Directory realms, ActiveDirectory1 and ActiveDirectory2, and one session caching configuration, MyMemCache.

For more information about configuring an Active Directory realm, see Using Active Directory Server as an Authentication Realm.

Syntax for the security-template.xml file

The security-template.xml file contains three main areas defined by the following top-level tags:

  • <security-managers>

  • <realms>

  • <cache-managers>

The following table describes the tags and tag attributes for the <security-managers> tag:

TagDescription

<security-manager>

Defines a security manager. A security manager contains:

  • A realm
  • The session timeout duration
  • Optionally, a session caching strategy

This tag takes the following attributes:

  • key specifies the identifier of the security manager.
  • description a string describing the security manager.
<realms>Specifies the security realm used by the security manager by using the <realms-ref> tag child tag.
<cache-manager-ref>Optionally specifies the session cache manager used by the security manager. By default, sessions are managed locally on the Akula Server. Use this option to store them externally so that they can be shared across multiple Akula Servers.
<session-manager>

Optionally specifies the session timeout, in milliseconds. 

This tag takes the following attribute:

  • timeout specifies the idle session timeout value in milliseconds. The default value is 1800000 milliseconds, or 30 minutes. Every successful request resets the session timeout.

The following table describes the tags and tag attributes for the <realms> tag:

TagDescription

<realm>

Defines a realm. Each type of realm, such as Active Directory, has its own set of configuration parameters that you set by using the <property> tag or the <object> tag. For more information on configuring realms, see Connecting to an Authentication Realm.

This tag takes the following attributes:

  • key specifies the identifier of the realm. Pass this value to the <realms-ref> tag in the <security-managers> tag.
  • class specifies the class that represents the connection to the realm. Each type of realm uses its own class to define the connection.
<property>

Sets a simple property such as a String or integer value. 

This tag takes the following attribute:

  • key specifies the identifier of the property. 
<object>

Sets the value of an object.

This tag takes the following attributes:

  • key specifies the identifier of the object. 
  • class specifies the class that represents the object.

This tag contains one or more <value> tags, as the following example shows:

<object key="ds" class="my.co.com.DataSource">
    <property key="driverClassName">org.sqlite.JDBC</property>
    <property key="url">http://server.myCo.com/datasource</property>
</object>
<property key="dataSource">$ds</property>

In this example, the <object> tag corresponds to an object of type my.co.com.DataSource that contains two properties named driverClassName and url. Use the <property> tag to set those properties.

The last <property> tag in the example refers to the ds object by using the syntax $ds. The "$" prefix to the key name lets you reference an object in a <property> tag. Therefore, you cannot use "$" as a literal character in the file.

Note that forward referencing is not allowed in security-template.xml. Therefore the ds object must be defined before you can reference it by using the $ds syntax.

The following table describes the tags and tag attributes for the <cache-managers> tag:

Tag                   Description

<cache-manager>

Defines a cache manager. For more information on defining a cache manager, see Configuring Session Caching.

This tag takes the following attributes:

  • key specifies the identifier of the cache manager.
  • class specifies the class that represents the cache manager. Because the Akula Server supports only Memcached as the caching manager, the value is always com.verivo.akula.security.cache.memcached.MemcachedCacheManager.
<property>

Use this tag to set the following properties of the cache manager:

  • baseURIs attribute specifies the locations of the servers running Memcached.
  • name specifies a unique name for the caching server.

Setting the security manager for an app scope

Each app scope deployed on the Akula Server requires a security manager, including the built-in server app scope. By default, the Akula Server defines a single security manager used by all app scopes.

To select the desired security manager, an app scope uses its properties.xml file to reference a security manager. Alternatively, a system administrator can use the Akula Command-line Management Utility to set the security manager for the app scope.

The built-in server app scope always uses the default security manager. 

Using the default security manager

The Akula Server defines app properties in the AKULA_HOME\global\properties.xml file. By default, the AKULA_HOME\global\properties.xml file defines an app property named akula_security_manager that sets the default security manager for all app scopes, including the built-in server app scope. Shown below is the definition of the akula_security_manager app property:

Therefore, if you do not explicitly set the security manager for an app scope, it uses the default security manager. The built-in server app scope always uses the default security manager. To change the security manager used by the built-in server app scope, edit the AKULA_HOME\global\properties.xml to set the akula_security_manager app property, and the restart the Akula server.

For more information on working with app properties, see Using App Properties.

Using properties.xml in the app scope to set the security manager

Each app scope optionally contains a properties.xml file in the /AKZ-INF/config/scope directory under the root directory of an AKZ file that represents the app scope. The app scope can then use its properties.xml file to override app properties defined by the AKULA_HOME\global\properties.xml file for the Akula Server.

To override the akula_security_manager app property defined by the Akula Server, edit the properties.xml file in the app scope as the following example shows:

In this example, you override the akula_security_manager app property to configure the app scope to use the "MyCompanyProduction" security manager.

Using the Akula Command-line to set the security manager for an app scope

To use the Akula Command-line to change the value of an app property for an app scope, use the updateproperty command. Changing the security manager at run time does not require a server restart. For more information on the Akula Command-line, see Using the Akula Command-line Management Utility.

For example, use the following command to change the value of the akula_security_manager app property for an app scope named App1:

> updateproperty App1 akula_security_manager MyCompanyProduction  

The Akula Command-line prompts you to make sure that you want to make this change.

This prompt occurs only when changing the akula_security_manager app property by using the updateproperty, resetproperty, or resetproperties command. You can bypass the prompt by appending -Y to the command, as shown below:

> updateproperty App1 akula_security_manager MyCompanyProduction -Y

For more information on the Akula Command-line, see Using the Akula Command-line Management Utility.