JGroupsAUTH

Version 9

    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