Outdated: document lives in the JGroups repo: JGroups/AUTH.md at master · belaban/JGroups · GitHub

Definition

AUTH is used to provide a layer of authentication to JGroups.  This allows you to define pluggable security that defines if a node should be allowed to join a group.  AUTH sits below the GMS protocol and listens for JOIN REQUEST messages.  When a JOIN REQUEST is received it tries to find an AuthHeader object, inside of which should be an implementation of the AuthToken object.

AuthToken is an abstract class, implementations of which are responsible for providing the actual authentication mechanism.  Some basic implementations of AuthToken are provide in the org.jgroups.auth package (SimpleToken, MD5Token and X509Token).  Effectivly all these implementations do is encrypt a string (found in the jgroups config) and pass that on the JOIN REQUEST.

When authentication is successful, the message is simply passed up the stack to the GMS protocol.  When it fails, the AUTH protocol creates a JOIN RESPONSE message with a failure string and passes it back down the stack.  This failure string informs the client of the reason for failure.  Clients will then fail to join the group and will throw a SecurityException.  If this error string is null then authentication is considered to have passed.

Check out JGroups and authentication - or how AUTH came to be

Example Configuration

  <AUTH auth_class="org.jgroups.auth.X509Token"         auth_value="chris_mills_110"              keystore_path="C\:\Documents and Settings\spare1\.keystore"         keystore_password="changeit"         cert_alias="test"         cipher_type="RSA"></AUTH>

In the above example the AUTH protocol delegates authentication to an instance of the

org.jgroups.auth.X509Token

class.  The only parameter that AUTH requires is the

auth_class

attribute which defines the authentication mechanism.  All other parameters defined in the configuration are passed in to the instance of the

auth_class

.

This allows pluggable authentication mechanisms, abstracted from the core of JGroups, to be configured to secure and lock down who can join a group.

Creating an AUTH module

1. Create a class that extends

   org.jgroups.auth.AuthToken

    

2. You must have an empty constructor

3. Implement the

   public void setValue(Properties properties)

   method to recieve properties from the JGroups config.

4. Implement the

   public String getName()

   method to return the package and class name

5. Implement the

   public boolean authenticate(AuthToken token)

   method to provide the actual authentication mechanism of clients.

6. In the jgroups config XML for AUTH set the

   auth_class

   attribute to your new authentication class.  Remember to include anyother properties your class may require.

Example Failure

When authentication fails a SecurityException is thrown on the client trying to join the group.  Below is an example stack trace:

org.jboss.jgroups.fileshare.exception.FileShareException: org.jgroups.ChannelException: connect() failed      at org.jboss.jgroups.fileshare.FileShare.<init>(FileShare.java:28)      at org.jboss.jgroups.fileshare.FileShare.main(FileShare.java:55)      at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)      at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39)      at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25)      at java.lang.reflect.Method.invoke(Method.java:585)      at com.intellij.rt.execution.application.AppMain.main(AppMain.java:78) Caused by: org.jgroups.ChannelException: connect() failed      at org.jgroups.JChannel.connect(JChannel.java:425)      at org.jboss.jgroups.fileshare.FileShare.<init>(FileShare.java:21)      ... 6 more Caused by: java.lang.SecurityException: Authentication failed      at org.jgroups.protocols.pbcast.ClientGmsImpl.join(ClientGmsImpl.java:132)      at org.jgroups.protocols.pbcast.GMS.down(GMS.java:738)      at org.jgroups.stack.DownHandler.run(Protocol.java:120)

On the coordinator the following is displayed for every failed membership join event:

21125 [WARN] X509Token.authenticate(): - X509 authentication failed 21125 [WARN] AUTH.up(): - AUTH failed to validate AuthHeader token

Configuration Parameters

TODO: add docs of AUTH-specific parameters.

See also Protocol Configuration Common Parameters.

Back to JGroups