26.2. Configure Node Security in Library Mode
In Library mode, node authentication is configured directly in the JGroups configuration. JGroups can be configured so that nodes must authenticate each other when joining or merging with a cluster. The authentication uses SASL and is enabled by adding the
SASL
protocol to your JGroups XML configuration.
SASL relies on JAAS notions, such as
CallbackHandlers
, to obtain certain information necessary for the authentication handshake. Users must supply their own CallbackHandlers
on both client and server sides.
Important
The
JAAS
API is only available when configuring user authentication and authorization, and is not available for node security.
Note
In the provided example,
CallbackHandler
classes are examples only, and not contained in the Red Hat JBoss Data Grid release. Users must provide the appropriate CallbackHandler
classes for their specific LDAP implementation.
Example 26.4. Setting Up SASL Authentication in JGroups
<SASL mech="DIGEST-MD5" client_name="node_user" client_password="node_password" server_callback_handler_class="org.example.infinispan.security.JGroupsSaslServerCallbackHandler" client_callback_handler_class="org.example.infinispan.security.JGroupsSaslClientCallbackHandler" sasl_props="com.sun.security.sasl.digest.realm=test_realm" />
The above example uses the
DIGEST-MD5
mechanism. Each node must declare the user and password it will use when joining the cluster.
Important
The SASL protocol must be placed before the GMS protocol in order for authentication to take effect.
26.2.1. Simple Authorizing Callback Handler
For instances where a more complex Kerberos or LDAP approach is not needed the
SimpleAuthorizingCallbackHandler
class may be used. To enable this set both the server_callback_handler
and the client_callback_handler
to org.jgroups.auth.sasl.SimpleAuthorizingCallbackHandler
, as seen in the below example:
<SASL mech="DIGEST-MD5" client_name="node_user" client_password="node_password" server_callback_handler_class="org.jgroups.auth.sasl.SimpleAuthorizingCallbackHandler" client_callback_handler_class="org.jgroups.auth.sasl.SimpleAuthorizingCallbackHandler" sasl_props="com.sun.security.sasl.digest.realm=test_realm" />
The
SimpleAuthorizingCallbackHandler
may be configured either programmatically, by passing the constructor an instance of of java.util.Properties
, or via standard Java system properties, set on the command line using the -DpropertyName=propertyValue
notation. The following properties are available:
sasl.credentials.properties
- the path to a property file which contains principal/credential mappings represented as principal=password .sasl.local.principal
- the name of the principal that is used to identify the local node. It must exist in the sasl.credentials.properties file.sasl.roles.properties
- (optional) the path to a property file which contains principal/roles mappings represented as principal=role1,role2,role3 .sasl.role
- (optional) if present, authorizes joining nodes only if their principal is.sasl.realm
- (optional) the name of the realm to use for the SASL mechanisms that require it
26.2.2. Configure Node Authentication for Library Mode (DIGEST-MD5)
The behavior of a node differs depending on whether it is the coordinator node or any other node. The coordinator acts as the SASL server, with the joining or merging nodes behaving as SASL clients. When using the DIGEST-MD5 mechanism in Library mode, the server and client callback must be specified so that the server and client are aware of how to obtain the credentials. Therefore, two
CallbackHandlers
are required:
- The
server_callback_handler_class
is used by the coordinator. - The
client_callback_handler_class
is used by other nodes.
The following example demonstrates these
CallbackHandlers
.
Example 26.5. Callback Handlers
<SASL mech="DIGEST-MD5" client_name="node_name" client_password="node_password" client_callback_handler_class="${CLIENT_CALLBACK_HANDLER_IN_CLASSPATH}" server_callback_handler_class="${SERVER_CALLBACK_HANDLER_IN_CLASSPATH}" sasl_props="com.sun.security.sasl.digest.realm=test_realm" />
JGroups is designed so that all nodes are able to act as coordinator or client depending on cluster behavior, so if the current coordinator node goes down, the next node in the succession chain will become the coordinator. Given this behavior, both server and client callback handlers must be identified within SASL for Red Hat JBoss Data Grid implementations.
26.2.3. Configure Node Authentication for Library Mode (GSSAPI)
When performing node authentication in Library mode using the GSSAPI mechanism, the
login_module_name
parameter must be specified instead of callback
.
This login module is used to obtain a valid Kerberos ticket, which is used to authenticate a client to the server. The
server_name
must also be specified, as the client principal is constructed as jgroups/$server_name@REALM
.
Example 26.6. Specifying the login module and server on the coordinator node
<SASL mech="GSSAPI" server_name="node0/clustered" login_module_name="krb-node0" server_callback_handler_class="org.infinispan.test.integration.security.utils.SaslPropCallbackHandler" />
On the coordinator node, the
server_callback_handler_class
must be specified for node authorization. This will determine if the authenticated joining node has permission to join the cluster.
Note
The server principal is always constructed as
jgroups/server_name
, therefore the server principal in Kerberos must also be jgroups/server_name
. For example, if the server name in Kerberos is jgroups/node1/mycache
, then the server name must be node1/mycache
.