6 Securing Extend Client Connections

Configure transport, explicit identity assertion, operation authorization, and executable policy for Extend services.

Define an SSL socket provider on the proxy TCP acceptor and the matching client initiator. Verify CA trust and the server name, and supply a client identity when mTLS is required. The retained TLS topics show placement; Configuring TLS with Protected Password Sources supplies the reusable provider recipe.

Configure the proxy identity asserter and client identity transformer as a deliberate pair. The token must be safely materialized and then authenticated. Receiving a raw subject is not proof that its principals were authenticated. Overview of Using Identity Tokens describes the default-profile contract and the explicit chain.

Apply storage/service authorization to protected operations and classify application processors, aggregators, filters, extractors, comparators, triggers, and invocables. The same payload can pass decoding and still be rejected by execution or caller policy; use Classifying Remote Executable Objects.

Remote invocation exposure

The shipped hardened posture disables the Extend InvocationService proxy unless explicitly enabled. Set coherence.invocation.enabled=true or the operational proxy setting only when remote invocation is intended. Explicit property configuration takes precedence as documented. Enabling the proxy does not bypass executable classification or caller authorization.

The Concurrent proxy has its own autostart control, coherence.concurrent.extend.enabled. Inventory it separately. Cache service access, remote invocation, and distributed task execution need their own allowed-operation tests.

Verification

Test trusted and untrusted certificates, missing/invalid tokens, a valid identity with denied permissions, and an unclassified executable. Establish the subject on the actual remote channel, including reconnection and failover. Keep clients with different identities from accidentally sharing subject-scoped handles or credentials.

Using Identity Tokens to Restrict Client Connections

Identity tokens are used to control which clients can access a cluster. The token is sent between extend clients and extend proxies whenever a connection is attempted. Only extend clients that pass a valid identity token are allowed to access the cluster.

This section includes the following topics:

Parent topic: Securing Extend Client Connections

Overview of Using Identity Tokens

Pair a client token transformer with a proxy asserter that verifies identity before authorizing operations.

An IdentityTransformer produces the token associated with a client subject/service. An IdentityAsserter validates the received token and returns the subject that downstream policy can use. Token decoding and authentication are distinct steps; a safe data object may still contain forged identity claims.

The default transformer returns the subject. Only an explicitly selected coherence.security.mode=compatibility retains the default asserter's raw-Subject pass-through. The hardened profile, which is the default starting with Coherence 26.1.0.0 when the property is unset, rejects non-null tokens, including a raw subject. Null-token behavior remains available for deliberately unauthenticated clients; require an explicit trusted chain when anonymous access is inappropriate.

Use the provided JAAS credential asserter or a reviewed custom identity integration. Validate token type, issuer/credential, intended service/audience, validity, and required identity properties according to the selected token system. Do not accept a subject merely because it contains a role name.

Transformers and asserters run at the documented connection/channel creation points. Deploy the transformer on the client and asserter on the proxy, and configure authentication on any different protocol independently. Propagate the verified subject to storage authorization through the supported routes. Cluster members themselves remain a separate trust boundary; stronger subject proof is described in Securing Cluster Peers and Federation.

Parent topic: Using Identity Tokens to Restrict Client Connections

Creating a Custom Identity Transformer

Transform a deliberately established local credential into the token contract accepted by the proxy.

Choose the transformer to match the proxy's asserter. For a JAAS username/password chain, an application may place a short-lived UsernameAndPassword in the local subject's private credentials and use the following Java 21+ transformer. The subject must be created by trusted application login/credential code and used only for the intended remote session. 

package com.example.security;

import com.tangosol.net.Service;
import com.tangosol.net.security.IdentityTransformer;
import com.tangosol.net.security.UsernameAndPassword;
import javax.security.auth.Subject;

public final class CredentialIdentityTransformer implements IdentityTransformer {
    @Override
    public Object transformIdentity(Subject subject, Service service) {
        if (subject == null) {
            throw new SecurityException("Credentials required");
        }
        var credentials = subject.getPrivateCredentials(UsernameAndPassword.class);
        if (credentials.size() != 1) {
            throw new SecurityException("Exactly one credential is required");
        }
        return credentials.iterator().next();
    }
}

Configure this class under the client operational <security-config><identity-transformer>. The caller owns the source password and subject lifetime: keep credentials available through required channel creation/reconnection, remove them and clear owned arrays after the session is closed, and avoid sharing the subject across unrelated users. Never clear an array immediately on returning a token while the transport still needs to serialize it.

This example defines a username/password service credential flow. For a signed token or external identity provider, use that provider's verified contract and refresh/audience rules rather than inventing claims in the transformer. The proxy must independently validate the token through its configured asserter.

Parent topic: Using Identity Tokens to Restrict Client Connections

Enabling a Custom Identity Transformer

To enable a custom identity transformer implementation, edit the client-side tangosol-coherence-override.xml file and add an <identity-transformer> element within the <security-config> node. The element must include the full name of the implementation class. For example: 

<?xml version='1.0'?>

<coherence xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns="http://xmlns.oracle.com/coherence/coherence-operational-config"
   xsi:schemaLocation="http://xmlns.oracle.com/coherence/coherence-operational-config
   coherence-operational-config.xsd">
   <security-config>
      <identity-transformer>
        <class-name>com.my.PasswordIdentityTransformer</class-name>
      </identity-transformer>
   </security-config>
</coherence>

Parent topic: Using Identity Tokens to Restrict Client Connections

Creating a Custom Identity Asserter

Prefer the provided JAAS adapter where suitable and customize assertion only for a defined trusted token contract.

For username/password tokens, com.tangosol.net.security.JAASIdentityAsserter adapts the token to a named JAAS login entry. Configure its constructor with the intended entry name. Authenticating Credentials with JAAS includes both that configuration path and an example of a custom adapter when additional subject validation is needed.

A custom IdentityAsserter must reject unsupported token types, failed verification, and unusable identities. Return the verified subject needed by downstream authorization; returning null after a shared-password comparison does not establish a user or business role. Use transport encryption and bounded credential failure handling.

Do not use a password system property as an identity directory, accept an unverified raw subject as proof, or expose secrets in messages/logs. Define credential rotation, token expiry, audience/service binding, and the lifecycle of any retained subject resources. Package custom application token types with the required serialization policy before they can reach the asserter.

Parent topic: Using Identity Tokens to Restrict Client Connections

Enabling a Custom Identity Asserter

To enable a custom identity asserter implementation, edit the cluster-side tangosol-coherence-override.xml file and add an <identity-asserter> element within the <security-config> node. The element must include the full name of the implementation class. For example: 

<?xml version='1.0'?>

<coherence xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns="http://xmlns.oracle.com/coherence/coherence-operational-config"
   xsi:schemaLocation="http://xmlns.oracle.com/coherence/coherence-operational-config
   coherence-operational-config.xsd">
   <security-config>
      <identity-asserter>
        <class-name>com.my.PasswordIdentityAsserter</class-name>
      </identity-asserter>
   </security-config>
</coherence>

Parent topic: Using Identity Tokens to Restrict Client Connections

Using Custom Security Types

Security objects are automatically serialized and deserialized using Portable Object Format (POF) when they are passed between extend clients and extend proxies. Security objects that are predefined in POF require no configuration or programming changes. However, security objects that are not predefined in POF (for example, when an application uses Kerberos authentication) cause an error. For custom security types, an application must convert the custom type or define the type in POF. There are two approaches for using unsupported types.

Converting the Type

The custom identity transformer implementation converts a custom security object type to a type that is predefined for POF, such as a character array or string, before returning it as an object token. On the proxy server, the custom identity asserter implementation converts the object back (after validation) to a Subject.

For example, a subject may contain credentials that are not serialized. The identity transformer implementation extracts the credential and converts it to a character array, returning that array as the token. On the proxy server, the identity asserter converts the character array to the proper credential type, validates it, and then constructs a Subject to return.

Defining the Custom Type in POF

You can define the custom security types in both the client's and the proxy's POF configuration file. For detailed information about using POF with Java, see Using Portable Object Format in Developing Applications with Oracle Coherence. For more information about using POF with C++ and C#, see Building Integration Objects (C++) and Building Integration Objects (.NET), respectively in Developing Remote Clients for Oracle Coherence.

Parent topic: Using Identity Tokens to Restrict Client Connections

Understanding Custom Identity Token Interoperability

Solutions that use a custom identity token must always consider what tokens may be sent by an extend client and what tokens may be received by an extend proxy. This is particularly important during rolling upgrades and when a new custom identity token solution is implemented.

Oracle Coherence Upgrades

Interoperability issues may occur during the process of upgrading. In this scenario, different client versions may interoperate with different proxy server versions. Ensure that a custom identity asserter can handle identity tokens sent by an extend client. Conversely, ensure that a custom identity transformer sends a token that the extend proxy can handle.

Custom Identity Token Rollout

Interoperability issues may occur between extend clients and extend proxies during the roll out a custom identity token solution. In this scenario, as extend proxies are migrated to use a custom identity asserter, some proxies continue to use the default asserter until the rollout operation is completed. Likewise, as extend clients are migrated to use a custom identity transformer, clients continue to use the default transformer until the rollout operation is completed. In both cases, the extend clients and extend proxies must be able to handle the default token type until the rollout operation is complete.

One strategy for such a scenario is to have a custom identity asserter that accepts the default token types temporarily as clients are updated. The identity asserter checks an external source for a policy that indicates whether those tokens are accepted. After all clients have been updated to use a custom token, change the policy to accept the custom tokens.

Parent topic: Using Identity Tokens to Restrict Client Connections

Associating Identities with Extend Services

Create and use subject-scoped remote handles under the intended authenticated context.

An Extend connection/channel can associate an identity token with the service context. Configure the client transformer and proxy asserter to agree on a verified token contract, and configure subject scoping as required by the application. A locally authenticated subject still needs that explicit remote assertion path.

Use current subject-context APIs and acquire the session/map handles within the intended identity context. See Using Authenticated Subjects with Modern Java and Creating a Custom Identity Transformer. Keep the Coherence instance/session lifetime deliberate and avoid sharing one identity's handles across unrelated users.

Verify identity propagation with a real protected operation, reconnection, and failover. Do not assume all asynchronous callbacks or arbitrary executors inherit context. Use the protocol's supported propagation and test the specific path rather than relying on a thread-local assumption.

Parent topic: Securing Extend Client Connections

Implementing Extend Client Authorization

Oracle Coherence*Extend authorization controls which operations can be performed on a cluster based on an extend client's access rights. Authorization logic is implementation-specific and is enabled on a cluster proxy. The code samples in this section are based on the Java authorization example, which is included in the examples that are delivered as part of the distribution. The example demonstrates a basic authorization implementation that uses the Principal obtained from a client request and a role-based policy to determine whether to allow operations on the requested service. Download the examples for the complete implementation.

This section includes the following topics:

Parent topic: Securing Extend Client Connections

Overview of Extend Client Authorization

Interceptor classes provide the ability to implement client authorization. An extend proxy calls the interceptor classes before a client accesses a proxied resource (cache, cache service, or invocation service). Interceptor classes are implementation-specific. They must provide the necessary authorization logic before passing the request to the proxied resources.

Figure 6-1 shows a conceptual view of extend client authorization.

Figure 6-1 Conceptual View of Extend Client Authorization

Description of Figure 6-1 follows
Description of "Figure 6-1 Conceptual View of Extend Client Authorization"

Parent topic: Implementing Extend Client Authorization

Create Authorization Interceptor Classes

To create interceptor classes for both a proxied cache service and a proxied invocation service, implement the CacheService and InvocationService interfaces, respectively. Or, as is more common, extend a set of wrapper classes: com.tangosol.net.WrapperCacheService (with com.tangosol.net.cache.WrapperNamedCache) and com.tangosol.net.WrapperInvocationService. The wrapper classes delegate to their respective interfaces and provide a convenient way to create interceptor classes that apply access control to the wrapped interface methods.

Example 6-1 is taken from the Oracle Coherence examples. The example demonstrates creating an authorization interceptor class for a proxied invocation service by extending WrapperInvocationService. It wraps all InvocationService methods on the proxy and applies access controls based on the Subject passed from an extend client. The implementation allows only a Principal with a specified role name to access the InvocationService methods.

Example 6-1 Extending the WrapperCacheService Class for Authorization

public class EntitledCacheService
   extends WrapperCacheService
   {
   public EntitledCacheService(CacheService service)
       {
       super(service);
       }

   public NamedCache ensureCache(String sName, ClassLoader loader)
      {
      SecurityExampleHelper.checkAccess(SecurityExampleHelper.ROLE_READER);
      return new EntitledNamedCache(super.ensureCache(sName, loader));
      }

   public void releaseCache(NamedCache map)
      {
      if (map instanceof EntitledNamedCache)
         {
         EntitledNamedCache cache =  (EntitledNamedCache) map;
         SecurityExampleHelper.checkAccess(SecurityExampleHelper.ROLE_READER);
         map = cache.getNamedCache();
         }
      super.releaseCache(map);
      }

   public void destroyCache(NamedCache map)
      {
      if (map instanceof EntitledNamedCache)
         {
         EntitledNamedCache cache =  (EntitledNamedCache) map;
         SecurityExampleHelper.checkAccess(SecurityExampleHelper.ROLE_ADMIN);
         map = cache.getNamedCache();
         }
      super.destroyCache(map);
      }
}

Notice that the EntitledCacheService class requires a named cache implementation. The WrapperNamedCache class is extended and wraps each method of the NamedCache instance. This allows access controls to be applied to different cache operations.

Note:

Much of the functionality that is provided by the WrapperNamedCache class is also covered by the StorageAccessAuthorizer interface, which provides a better and simplified way to authorize cluster operations. See Authorizing Access to Server-Side Operations.

Example 6-2 is a code excerpt taken from the Oracle Coherence examples. The example demonstrates overriding the NamedCache methods and applying access checks before allowing the method to be executed. See the examples for the complete class.

Example 6-2 Extending the WrapperNamedCache Class for Authorization

public class EntitledNamedCache
   extends WrapperNamedCache
   {
   public EntitledNamedCache(NamedCache cache)
      {
       super(cache, cache.getCacheName());
      }

   public Object put(Object oKey, Object oValue, long cMillis)
      {
      SecurityExampleHelper.checkAccess(SecurityExampleHelper.ROLE_WRITER);
      return super.put(oKey, oValue, cMillis);
      }

   public Object get(Object oKey)
      {
      SecurityExampleHelper.checkAccess(SecurityExampleHelper.ROLE_READER);
      return super.get(oKey);
      }

   public void destroy()
      {
      SecurityExampleHelper.checkAccess(SecurityExampleHelper.ROLE_ADMIN);
      super.destroy();
      }
...

Example 6-3 is taken from the Oracle Coherence examples. The example demonstrates creating an authorization interceptor class for a proxied cache service by extending the WrapperCacheService class. It wraps all CacheService methods on the proxy and applies access controls based on the Subject passed from an extend client. The implementation allows only a Principal with the specified role to access the CacheService methods

Example 6-3 Extending the WrapperInvocationService Class for Authorization

public class EntitledInvocationService
   extends WrapperInvocationService
   {
   public EntitledInvocationService(InvocationService service)
      {
      super(service);
      }

   public void execute(Invocable task, Set setMembers, InvocationObserver 
      observer)
      {
      SecurityExampleHelper.checkAccess(SecurityExampleHelper.ROLE_WRITER)
      super.execute(task, setMembers, observer);
      }

   public Map query(Invocable task, Set setMembers)
      {
      SecurityExampleHelper.checkAccess(SecurityExampleHelper.ROLE_WRITER)
      return super.query(task, setMembers);
      }
}

When a client attempts to use a remote invocation service, the proxy calls the query() method on the EntitledInvocationService class, rather than on the proxied InvocationService instance. The EntitledInvocationService class decides to allow or deny the call. If the call is allowed, the proxy then calls the query() method on the proxied InvocationService instance.

Parent topic: Implementing Extend Client Authorization

Enable Authorization Interceptor Classes

To enable interceptor classes for a proxied cache service and a proxied invocation service, edit a proxy scheme definition and add a <cache-service-proxy> element and <invocation-service-proxy> element, respectively. Use the <class-name> element to enter the fully qualified name of the interceptor class. Specify initialization parameters using the <init-params> element. See cache-service-proxy and invocation-service-proxy in Developing Applications with Oracle Coherence for detailed information about using these elements.

The following example demonstrates enabling interceptor classes for both a proxied cache service and a proxied invocation service. The example uses the interceptor classes from Example 6-1 and Example 6-3. 

<proxy-scheme>
   ...
   <proxy-config>
      <cache-service-proxy>
         <class-name>
            com.tangosol.examples.security.EntitledCacheService
         </class-name>
         <init-params>
            <init-param>
               <param-type>com.tangosol.net.CacheService</param-type>
               <param-value>{service}</param-value>
            </init-param>
         </init-params>
      </cache-service-proxy>
      <invocation-service-proxy>
         <class-name>
            com.tangosol.examples.security.EntitledInvocationService
         </class-name>
         <init-params>
            <init-param>
               <param-type>com.tangosol.net.InvocationService</param-type>
               <param-value>{service}</param-value>
            </init-param>
         </init-params>
      </invocation-service-proxy>
</proxy-config>

Parent topic: Implementing Extend Client Authorization