4 Using an Access Controller

Authenticate subjects and apply Coherence service permissions with an access controller appropriate to the deployment.

The Coherence security framework can authenticate a member/user subject and apply configured permissions to clustered services and caches. It is an opt-in control, separate from the security profile, TLS, and per-operation storage authorization. Retain the distinction between service access and permission to read or mutate individual cache data.

Use a suitable JAAS login module and configure the default or custom access controller. The default controller needs the expected principals and private/public signing material in the subject. An application-specific identity module must satisfy that contract if the default controller is used.

Authenticating Credentials with JAAS supplies a credential-assertion example and Using Authenticated Subjects with Modern Java shows subject context with current Java and Coherence APIs. The retained framework topics describe keystores, permissions, default/custom controllers, and audit logging.

Signing policy

In the hardened profile, which is the default starting with Coherence 26.1.0.0, the default controller selects SHA256withRSA and rejects weak signing algorithms. Explicit compatibility mode retains the historical SHA1withDSA default with a bounded warning. Migrate signing keys and explicit algorithm configuration together; an RSA algorithm cannot use incompatible DSA keys.

Signer/principal binding is enforced according to the current profile. Hardened authorization binds to the verified signer and rejects unsafe additional/unbound principals. Fresh per-operation signature state and rejection of an unverified certificate/principal mismatch apply in both profiles. Keep permission subjects consistent with the actual verified certificate identity.

Subject validation cache

coherence.security.subject.validation.ttl controls the Standard implementation's successful-validation cache. The default is 10s; unitless values are milliseconds. Accepted durations range from one through Integer.MAX_VALUE milliseconds. Invalid, nonpositive, overflowing, or out-of-range values use the default with a warning. This setting is independent of both runtime mode and security profile and is read during initialization.

A longer TTL reduces repeated validation work but retains a successful decision longer. Select it with credential/key retirement and workload cost in mind. It does not make an unvalidated wire-created subject trustworthy or establish a revocation system by itself.

• Authenticating Credentials with JAAS
  Convert validated username/password tokens into authenticated subjects using a configured JAAS login module.
• Using Authenticated Subjects with Modern Java
  Bind a verified subject to application work using current Java subject-context and Coherence lifecycle APIs.
• Overview of Using an Access Controller
  Coherence uses an access controller to secure access to cluster resources and operations. It uses a JAAS LoginModule to authenticate a caller, and an access controller on one or more cluster nodes verifies the access rights of the caller’s Subject.
• Proof of Identity
  Use authenticated subjects and verified signing material for Coherence access-controller decisions.
• Configuring the JAAS LoginModule
  The LoginModule used by JAAS is configured in a JAAS configuration file. If using the Coherence security APIs to perform the JAAS login, Coherence uses a LoginModule configured with the name “Coherence”.
• Configuring a JAAS Callback Handler
  If Coherence needs to authorize permissions but the calling thread is not running inside the context of a Subject, then Coherence performs a JAAS login call. Depending on the specific LoginModule JAAS is configured to use, it may require an instance of a javax.security.auth.callback.CallbackHandler interface that can provide various parameters to the configured LoginModule.
• Using a Custom JAAS LoginModule
  Any custom JAAS LoginModule can be used that produces a Subject containing a principal and private/public keys. For example, you can use Java’s built-in com.sun.security.auth.module.KeyStoreLoginModule class.
• Enable the Access Controller
  Before enabling an access controller, you must configure the controller in the Coherence operational configuration file. The default configuration uses Coherence’s default access controller, but you can override it to use a custom controller implementation if desired.
• Using the Default Access Controller Implementation
  Coherence includes a default access controller implementation that uses a Java keystore for authentication. The implementation class is the com.tangosol.net.security.DefaultController class. The access controller is configured within the <security-config> element in the operational configuration file.
• Using a Custom Access Controller Implementation
  You can create a custom access controller implementation if you have specific security requirements that are not addressed by the default implementation.

Authenticating Credentials with JAAS

Convert validated username/password tokens into authenticated subjects using a configured JAAS login module.

Use a JAAS module that actually validates the presented credentials and returns the identity required by downstream authorization. The module may integrate an enterprise identity system through its supported implementation; configuring an extension point does not itself provide LDAP, Active Directory, or cloud IAM validation.

For the ordinary credential path, prefer the provided com.tangosol.net.security.JAASIdentityAsserter. Configure its constructor with the JAAS entry name. The custom adapter below is an optional extension example for applications needing additional subject/error validation.

<identity-asserter>
  <class-name>com.tangosol.net.security.JAASIdentityAsserter</class-name>
  <init-params>
    <init-param><param-type>java.lang.String</param-type><param-value>Coherence</param-value></init-param>
  </init-params>
</identity-asserter>

The complete Java 21+ asserter below accepts UsernameAndPassword, used by explicit gRPC Basic authentication and by an appropriately configured Extend transformer. It does not accept a raw subject as proof. Configure a Coherence JAAS entry and include the login module on the runtime classpath.

package com.example.security;

import com.tangosol.net.Service;
import com.tangosol.net.security.IdentityAsserter;
import com.tangosol.net.security.SimpleHandler;
import com.tangosol.net.security.UsernameAndPassword;
import java.util.Arrays;
import javax.security.auth.Subject;
import javax.security.auth.login.LoginContext;
import javax.security.auth.login.LoginException;

public final class JaasIdentityAsserter implements IdentityAsserter {
    @Override
    public Subject assertIdentity(Object token, Service service) {
        if (!(token instanceof UsernameAndPassword credentials)
                || credentials.getUsername() == null
                || credentials.getUsername().isBlank()
                || credentials.getPassword() == null
                || credentials.getPassword().length == 0) {
            throw new SecurityException("Authentication failed");
        }
        char[] password = credentials.getPassword().clone();
        try {
            var login = new LoginContext("Coherence",
                    new SimpleHandler(credentials.getUsername(), password, false));
            login.login();
            var subject = login.getSubject();
            if (subject == null || subject.getPrincipals().isEmpty()) {
                throw new SecurityException("Authentication failed");
            }
            return subject;
        } catch (LoginException failure) {
            throw new SecurityException("Authentication failed");
        } finally {
            Arrays.fill(password, '\0');
        }
    }
}

The returned subject is used by the caller, so this minimal asserter does not immediately log it out and invalidate its credentials. A production module that owns refreshable credentials or session resources needs an appropriate lifecycle integration. Avoid caching unbounded subjects inside the asserter. Log bounded failure metadata without credentials or an externally visible detailed login cause.

For a keystore-based identity, the existing coherence-login module provides com.tangosol.security.KeystoreLogin. A JAAS entry can select an explicitly provisioned PKCS12 store:

Coherence {
  com.tangosol.security.KeystoreLogin required
    keyStorePath="/run/coherence/users.p12"
    keyStoreType="PKCS12";
};

Set java.security.auth.login.config to the protected JAAS configuration file. Provision aliases, certificate principals, and passwords according to the login module's callback contract. This is a keystore identity example, not a general role-directory implementation.

Place the following in the server operational override; merge it with the TLS and application settings, preserving schema order:

<security-config>
  <identity-asserter>
    <class-name>com.example.security.JaasIdentityAsserter</class-name>
  </identity-asserter>
  <subject-scope>true</subject-scope>
</security-config>

Enable the Coherence security framework separately when its access-controller permissions are required. For HTTP acceptors, configure their JAAS entry names as documented for that endpoint rather than assuming the gRPC/Extend asserter configures HTTP login. Verify a real successful login, missing/invalid credentials, the exact resulting principal, and a denied operation with valid credentials.

Using Authenticated Subjects with Modern Java

Bind a verified subject to application work using current Java subject-context and Coherence lifecycle APIs.

JAAS authentication remains useful on current JDKs. The Java Security Manager's former policy-based authorization model does not: the Security Manager is permanently disabled beginning with JDK 24. Coherence's service/storage access checks remain separate application controls.

The example below uses Java 21 or later, Subject.callAs, the Coherence bootstrap API, a typed NamedMap, and try-with-resources. It illustrates a member application using a configured login module and Coherence access-controller deployment. Start with an isolated configured cluster and the intended service identity; the example does not provision users, keys, roles, or permissions.

package com.example.security;

import com.tangosol.net.Coherence;
import com.tangosol.net.NamedMap;
import com.tangosol.net.security.SimpleHandler;
import java.util.Arrays;
import javax.security.auth.Subject;
import javax.security.auth.login.LoginContext;

public final class JaasSession {
    public static void main(String[] args) throws Exception {
        var console = System.console();
        if (console == null) {
            throw new IllegalStateException("An interactive console is required");
        }
        var username = console.readLine("User: ");
        char[] password = console.readPassword("Password: ");
        if (password == null) {
            throw new IllegalStateException("No password was supplied");
        }
        var login = new LoginContext("Coherence",
                new SimpleHandler(username, password, false));
        boolean authenticated = false;
        try {
            login.login();
            authenticated = true;
            var subject = login.getSubject();
            Subject.callAs(subject, () -> {
                try (var coherence = Coherence.clusterMember().start().join()) {
                    var session = coherence.getSession();
                    NamedMap<String, String> accounts = session.getMap("accounts");
                    System.out.println(accounts.get("account-1"));
                }
                return null;
            });
        } finally {
            Arrays.fill(password, '\0');
            if (authenticated) {
                login.logout();
            }
        }
    }
}

Obtain and use subject-scoped handles within the intended subject context. Do not share a handle carrying one identity across unrelated users. Do not assume asynchronous callbacks or newly created execution contexts inherit an identity in the same way; use the supported context propagation and test the actual route.

An Extend client also needs a transformer producing the token accepted by its proxy. A locally authenticated subject passed through the default transformer is still a raw subject on the wire and is rejected by the hardened default asserter. Configure the explicit trusted token chain described in Securing Extend Client Connections.

Overview of Using an Access Controller

Coherence uses an access controller to secure access to cluster resources and operations. It uses a JAAS LoginModule to authenticate a caller, and an access controller on one or more cluster nodes verifies the access rights of the caller’s Subject.

See LoginModule in Java Authentication and Authorization Service (JAAS) Reference Guide.

An access controller:

• Verifies proof of the caller’s identity.

• Grants or denies access to a protected clustered resource based on the caller's permissions.

• Encrypts outgoing communications based on the caller's private credentials.

• Decrypts incoming communications based on the caller's public credentials.

Coherence provides a default access controller implementation. The default access controller implementation is based on the key management infrastructure that ships as a standard part of the JDK. See Using the Default Access Controller Implementation.

Figure 4-1 shows a conceptual view of securing two cluster members using access controllers.

Figure 4-1 Conceptual View of Access Controller Security

Description of "Figure 4-1 Conceptual View of Access Controller Security"

Understanding the Security Context

Each clustered service maintains the concept of a senior service member that serves as a controlling agent for a particular service. The senior member does not consult with other members when accessing a clustered resource. However, junior member that want to join a service must request and receive a confirmation from the senior member. The senior member notifies all other cluster members about the joining member.

Any cluster member may be the senior member, or may become the senior member when the current senior member dies, so it is important that all cluster members are configured to be able to properly authenticate and authorize all other members.

The security subsystem is designed to operate in a partially hostile environment because data is distributed among cluster members. Every member is considered to be a malicious member. That is, members are assumed to lack sufficient credentials to join a clustered service or obtain access to a clustered resource.

File system mechanisms and standard Java security policies guarantee the trustworthiness of a single node. However, there are two scenarios to consider with member communication:

• A malicious node surpasses the local access check and attempts to join a clustered service or to gain access to a clustered resource that a trusted node controls.

• A malicious node creates a clustered service or clustered resource and becomes its controller.

The security subsystem uses a two-way encryption algorithm to prevent either of these two scenarios from occurring. All client requests must establish proof of identity, and all service responses must establish proof of trustworthiness.

Proof of Identity

Use authenticated subjects and verified signing material for Coherence access-controller decisions.

The Coherence security framework obtains a subject through the configured JAAS login module. The default controller expects the required principals and matching private/public signing material, then verifies the signer before applying permissions. A subject constructed from wire-supplied principal names is not that proof.

Use Using Authenticated Subjects with Modern Java for a current bootstrap/session example and Using an Access Controller for signing and validation-cache behavior. For Extend, use the explicitly configured transformer/asserter chain; the default raw-subject compatibility path is not an authentication mechanism for a hardened deployment.

Preserve trusted key, principal, and permission mappings across cluster members. Additional principals must meet the controller's current binding rules. For stronger propagated subject authority at cluster peer boundaries, use the supported proof configuration and readiness prerequisites in Securing Cluster Peers and Federation.

Configuring the JAAS LoginModule

The LoginModule used by JAAS is configured in a JAAS configuration file. If using the Coherence security APIs to perform the JAAS login, Coherence uses a LoginModule configured with the name “Coherence”.

For example, the JAAS login configuration file below uses the com.sun.security.auth.module.KeyStoreLoginModule.

Coherence {
    com.sun.security.auth.module.KeyStoreLoginModule required
      keyStoreURL="keystore.jks";
};

You can use any suitable LoginModule that produces a Subject with the content required by the access controller. When using the default access controller, the Subject must have at least one Principal, a private key and public certificate pair.

Although not commonly required, you can change the name of the LoginModule used by Coherence by using the <login-module-name> element within the <security-config> element in the operational configuration file.

<security-config>
   <enabled system-property="coherence.security">true</enabled>
   <login-module-name>MyLoginModule</login-module-name> 
</security-config>

Then, update the JAAS configuration to include a LoginModule configured with that name:

MyLoginModule {
    com.sun.security.auth.module.KeyStoreLoginModule required
      keyStoreURL="keystore.jks";
};

The Coherence KeystoreLogin Class

Coherence includes coherence-login.jar which contains a LoginModule class named com.tangosol.security.KeystoreLogin. This LoginModule can use a Java keystore to obtain a Subject with a principal and a private/public key pair.

You can configure the KeystoreLogin LoginModule in the JAAS login configuration file.

Coherence {
    com.tangosol.security.KeystoreLogin required
      keyStorePath="keystore.jks";
};

A LoginModule configuration contains the LoginModule class name and optionally, a number of key/value pairs that are passed to the LoginModule when it is initialized. At a minimum, the KeystoreLogin configuration should include the fully qualified path of the keystore containing the keys and certificates.

The KeystoreLogin class supports the following configuration keys and values:

Key	Value
keyStorePath	The path to the keystore to use to load the Subject principal, keys, and certificates. The keyStorePath value may include property names that are expanded at runtime. For example, if you specify keyStorePath="${coherence.security.jaas.keystore}", the configuration pulls the location of the keystore from the coherence.security.jaas.keystore system property.
keyStoreType	The keystore type. For backward compatibility, the default is JKS, but PKCS12 is also supported.
keyStorePass	The password to use to access the keystore

Configuring a JAAS Callback Handler

If Coherence needs to authorize permissions but the calling thread is not running inside the context of a Subject, then Coherence performs a JAAS login call. Depending on the specific LoginModule JAAS is configured to use, it may require an instance of a javax.security.auth.callback.CallbackHandler interface that can provide various parameters to the configured LoginModule.

An access controller will attempt a JAAS login when all other authentication methods have been unsuccessful.

A custom callback handler is configured within the <security-config> element in the operational configuration override file. Add a <callback-handler> element that includes the fully qualified name of the implementation class. The following example configures a callback handler named package.MyCallbackHandler.

<security-config>
   <callback-handler>
      <class-name>package.MyCallbackHandler</class-name>
   </callback-handler>
</security-config>

Like other class instance XML configurations in Coherence, the <callback-handler> element can also be configured with <init-params> which will be passed to the class constructor.

<security-config>
   <callback-handler>
      <class-name>package.MyCallbackHandler</class-name>
      <init-params>
        <init-param>
          <param-type>String</param-type>
          <param-value>foo</param-value>
        </init-param>
      </init-params>
   </callback-handler>
</security-config>

As the callback handler supplies properties required by the JAAS LoginModule, these two classes are typically written and configured to work together.

The Coherence KeystoreLogin class passes a NameCallback and a PasswordCallback to the callback handler. The callback handler should set the NameCallback value to be the alias to use to retrieve the private key from the keystore. If the private key and/or keystore are password protected, the callback handler should set the password of the keystore and private key into the PasswordCallback value. The restriction here is that both the keystore and private key must use the same password.

Using a Custom JAAS LoginModule

Any custom JAAS LoginModule can be used that produces a Subject containing a principal and private/public keys. For example, you can use Java’s built-in com.sun.security.auth.module.KeyStoreLoginModule class.

The class should be configured in the JAAS login configuration file:

// LoginModule Configuration for Oracle Coherence
Coherence {
    com.sun.security.auth.module.KeyStoreLoginModule required
      keyStoreURL="file://keystore.jks"
      keyStoreAlias="admin"
      keyStorePasswordURL="file://keystore-pass.txt";
};

If the LoginModule will require a callback handler, then a suitable callback handler should be configured as described in Configuring a JAAS Callback Handler.

Enable the Access Controller

Before enabling an access controller, you must configure the controller in the Coherence operational configuration file. The default configuration uses Coherence’s default access controller, but you can override it to use a custom controller implementation if desired.

Enable the use of an access controller within the <security-config> element of the Coherence operational configuration. Add an <enabled> element set to true. For example:

<security-config>
   <enabled system-property="coherence.security">true</enabled>
</security-config>

The coherence.security system property or COHERENCE_SECURITY environment variable can also be used to enable the access controller. For example:

-Dcoherence.security=true

Note:

When access controller security is enabled, every call to the CacheFactory.getCache() or ConfigurableCacheFactory.ensureCache() API causes a security check. This negatively affects an application's performance if these calls are made frequently. The best practice is for the application to hold on to the cache reference and reuse it so that the security check is performed only on the initial call. With this approach, ensure that your application only uses the references in an authorized way.

Using the Default Access Controller Implementation

Coherence includes a default access controller implementation that uses a Java keystore for authentication. The implementation class is the com.tangosol.net.security.DefaultController class. The access controller is configured within the <security-config> element in the operational configuration file.

The default access controller uses private and public keys to both authenticate and authorize a caller and to perform encryption. The default controller makes some assumptions about the sort of JAAS Subject that is being used and how it has been configured.

The default access controller encrypts outgoing permission requests using the private key from the caller’s subject. This means that the subject must contain both a principal and a private key. The JAAS LoginModule used must produce a subject containing a principal and corresponding private key.

When authenticating a caller, the default controller expects to find a public key in its keystore using the caller’s principal name as the alias. This means that the keystore used by the default controller must contain the correctly aliased public keys for all the possible callers. If each cluster member uses a different principal and private/public key, then the default controller’s keystore must contain all of the matching public keys correctly aliased. As any cluster member could become the senior member, all cluster members must have access to all the public keys in their keystore.

This section includes the following topics:

• The Key Store Type and Encryption Algorithm
  Choose compatible key material and a supported signing algorithm for the access controller.
• The Default Access Controller Keystore
  The default access controller requires a keystore used to obtain the caller's public keys. This could be the same keystore as was used by the JAAS LoginModule, or it could be a different keystore specifically for access control.
• Create a Permissions File
  The default access controller requires a permissions file that declares access rights for principals. See the COHERENCE_HOME/lib/security/permissions.xsd schema for the syntax of the permissions file.
• Enable Security Audit Logs
  Security audit logs are used to track the cluster operations that are being performed by each user.
• Configure the Default Access Controller
  The default access controller is configured within the <security-config> element in the operational configuration file.

The Key Store Type and Encryption Algorithm

Choose compatible key material and a supported signing algorithm for the access controller.

The default access controller's signing algorithm is selected independently of a TLS protocol/cipher. The hardened profile is the default starting with Coherence 26.1.0.0; it selects SHA256withRSA and rejects weak algorithms. Explicit compatibility mode retains historical SHA1withDSA with a warning. Algorithm configuration must match the actual signing keys and supported provider.

Use provisioned modern key/certificate material and the intended keystore type, such as PKCS12 where supported by the selected login/controller configuration. Do not describe JKS/DSA as the universal requirement for current deployments. Preserve a legacy store only for the supported compatibility path that actually needs it.

Coordinate key, certificate principal, permissions, JAAS, and controller configuration before rollout. Verify signer/principal binding and a denied permission. A new algorithm name with an old incompatible key is not a successful migration. See Using an Access Controller and Verifying and Rotating TLS Identities.

The Default Access Controller Keystore

The default access controller requires a keystore used to obtain the caller's public keys. This could be the same keystore as was used by the JAAS LoginModule, or it could be a different keystore specifically for access control.

When a cluster member uses the default access controller to authorize a request, it tries to load the public key from the keystore using the caller’s principal name as the alias. If different cluster members are using different principals, then the access controller key store must contain the public keys for every cluster member. The keystore does not need to contain the private keys as it is only used for decryption to verify a caller.

The keystore may be password protected, in which case the default access controller must be configured with the password.

Create a Permissions File

The default access controller requires a permissions file that declares access rights for principals. See the COHERENCE_HOME/lib/security/permissions.xsd schema for the syntax of the permissions file.

The following example assigns all rights to the Manager principal, only join rights to the Worker principal for caches that have names prefixed by common, and all rights to the Worker principal for the invocation service named invocation.

<?xml version='1.0'?>
<permissions>
   <grant>
      <principal>
         <class>javax.security.auth.x500.X500Principal</class>
         <name>CN=Manager,OU=MyUnit</name>
      </principal>
      <permission>
         <target>*</target>
         <action>all</action>
      </permission>
   </grant>
   <grant>
      <principal>
         <class>javax.security.auth.x500.X500Principal</class>
         <name>CN=Worker,OU=MyUnit</name>
      </principal>
      <permission>
         <target>cache=common*</target>
         <action>join</action>
      </permission>
      <permission>
         <target>service=invocation</target>
         <action>all</action>
      </permission>
   </grant>
</permissions>

Enable Security Audit Logs

Security audit logs are used to track the cluster operations that are being performed by each user.

Each operation results in a log message being emitted. The messages will be written using the configured Coherence logger. For example:

"Destroy" action for cache "Accounts" has been permitted for the user "CN=Bob, OU=Accounting".

Security audit logs are disabled by default but can be enabled in the default access controller configuration.

Configure the Default Access Controller

The default access controller is configured within the <security-config> element in the operational configuration file.

See security-config in Developing Applications with Oracle Coherence.

The default operational configuration file already contains all the required configuration for the default access controller. This means that the default controller can be configured by just setting various system properties or environment variables.

The default configuration looks like this:

<access-controller>
  <class-name>com.tangosol.net.security.DefaultController</class-name>
  <init-params>
    <init-param id="1">
      <param-type>java.io.File</param-type>
      <param-value system-property="coherence.security.keystore"/>
    </init-param>
    <init-param id="2">
      <param-type>java.io.File</param-type>
      <param-value system-property="coherence.security.permissions"/>
    </init-param>
    <init-param id="3">
      <param-type>boolean</param-type>
      <param-value system-property="coherence.security.log">false</param-value>
    </init-param>
    <init-param id="4">
      <param-type>String</param-type>
      <param-value system-property="coherence.security.keystore.password"/>
    </init-param>
  </init-params>
</access-controller>

The <class-name> element is used to set the access controller class name to be the default access controller. This is followed by an <init-params> element containing the four <init-param> elements that configure the access controller. Each <init-param> corresponds to a constructor parameter in the DefaultController class constructor.

Table 4-1 init-param elements for configuring the access controller

Init Param	System Property or Environment Variable	Description
1	coherence.security.keystore	The fully qualified file name of the keystore that the default controller should use. See The Default Access Controller Keystore.
2	coherence.security.permissions	The fully qualified file name of the permissions XML file. See Create a Permissions File.
3	coherence.security.log	A boolean value that is true to enable audit logging or false to disable audit logging. See Enable Security Audit Logs.
4	coherence.security.keystore.password	An optional password for the keystore.

Note:

The Coherence default operational configuration file re-uses some system property names in multiple places. For example, both the default access controller and the default SSL socket provider use the same property names for the keystore and credentials. When using both TLS and an access controller, this will work if the application is supposed to use the same keystore for both TLS and for the access controller, but when this is not the case the only way to override these names it to use a custom operational configuration override file.

Configuring a Password Protected Keystore

When using a password protected keystore the password must be provided to the default access controller. This can be done as shown above either in the XML configuration or using a system property or environment variable. As passing credentials using a system property or environment variable is not always the most secure method, it is possible to configure a custom com.tangosol.net.PasswordProvider implementation that will be called at runtime to supply the password.

A password provider can be configured for the access controller by adding a <password-provider> element to the <access-controller> element of the security configuration. The <password-provider> element comes after the <init-prams> element.

For example, the Coherence com.tangosol.net.URLPasswordProvider password provider class, which reads a password from a URL, can be configured in an override XML file like this:

<access-controller> <password-provider id="trust-pass"> <class-name>com.tangosol.net.URLPasswordProvider</class-name> <init-params> <init-param> <param-type>String</param-type> <param-value>file://store-pass.txt</param-value> </init-param> </init-params> </password-provider> </access-controller>

In the example above, the password would be read from the file at the URL file://store-pass.txt.

Using a Custom Access Controller Implementation

You can create a custom access controller implementation if you have specific security requirements that are not addressed by the default implementation. Custom access controllers must implement the com.tangosol.net.security.AccessController interface.

To configure a custom access controller within the <security-config> element, add an <access-controller> element that includes the fully qualified name of the implementation class. The following example configures a custom access controller called MyAccessController.

<security-config>
   <enabled system-property="coherence.security">true</enabled>
   <access-controller>
      <class-name>package.MyAccessController</class-name>
   </access-controller>
</security-config>

Specify any required initialization parameters by using the <init-params> element. The following example includes parameters to pass the MyAccessController class a keystore and a permissions file.

<security-config>
   <enabled system-property="coherence.security">true</enabled>
   <access-controller>
      <class-name>package.MyAccessController</class-name>
      <init-params>
         <init-param>
            <param-type>java.io.File</param-type>
            <param-value>./keystore.jks</param-value>
         </init-param>
         <init-param>
            <param-type>java.io.File</param-type>
            <param-value>./permissions.xml</param-value>
         </init-param>
      </init-params>
   </access-controller>
</security-config>

Writing a custom access controller is not a trivial task as the controller must work how Coherence security internals expect it to. An incorrectly written access controller could inadvertently allow access to that should be blocked.

An access controller has to implement three methods from the com.tangosol.net.security.AccessController interface.

void checkPermission(ClusterPermission permission, Subject subject);

SignedObject encrypt(Object o, Subject subject)
        throws IOException, GeneralSecurityException;

Object decrypt(SignedObject so, Subject subjectRemote, Subject subjectThis)
        throws ClassNotFoundException, IOException, GeneralSecurityException;

• • The checkPermission method is used to verify that the passed in Subject has the specified permission.
• • The encrypt method encrypts a token for the specified Subject. This encrypted token will be used to authenticate and authorize the Subject by Coherence. Depending on the Coherence APIs being called, this authentication and authorization may happen on locally in the same access controller, or the token may be serialized and sent to a remote cluster member where its access controller will use it to authenticate and authorize the Subject.
• • The decrypt method decrypts the specified token using the specified Subjects. Whilst not obvious from the name, this method also verifies trust for the subjectRemote Subject, which is the calling Subject that will be requesting permissions. The default controller does this by obtaining a public key from its keystore using the principal name from the subjectRemote and using that key to decrypt the token. If no key is present in the local keystore for the subjectRemote principal the permissions will be rejected. Any custom access controller must also perform authentication and authorization in the decrypt method to verify trust in the subjectRemote Subject. It should then return the decrypted token.

The encrypt and decrypt methods should obviously work to properly encrypt or decrypt the values. For example, an encrypted token should decrypt to the same value that was encrypted. Coherence typically passes permission instances to the encrypt method, so the decrypt method must return the same value or Coherence will not work.

See Oracle Coherence Community Edition for an example of how to write a custom access controller.