Implement the ControlAuthenticationHandler interface to create a control authentication handler.

1. Edit the etc/Server.xml configuration file to include a name that the control authentication handler can register with.
   Include the control-authentication-handler element in the list of authentication handlers. The order of the list defines the order in which the authentication handlers are called. The value of the handler-name attribute is the name that your control authentication handler registers as. For example:

   <security>
     <authentication-handlers>
       <-- Include a local authentication handler that can authenticate the control client -->
       <authentication-handler class="com.example.LocalHandler" />
                  
       <-- Register your control authentication handler -->
       <control-authentication-handler handler-name="before-system-handler" />
   
     </authentication-handlers>
   </security>

   The client that registers your control authentication handler must first authenticate with the Diffusion server. Configure a local authentication handler that allows the client to connect.

2. Start the Diffusion server.
   • On UNIX^®-based systems, run the diffusion.sh command in the diffusion_installation_dir/bin directory.
   • On Windows™ systems, run the diffusion.bat command in the diffusion_installation_dir\bin directory.
3. Create a Java class that implements ControlAuthenticationHandler.

   package com.example.client;
                       
   import com.pushtechnology.diffusion.client.details.SessionDetails;
   import com.pushtechnology.diffusion.client.features.control.clients.AuthenticationControl.ControlAuthenticationHandler;
   import com.pushtechnology.diffusion.client.types.Credentials;
                   
   public class ExampleControlAuthenticationHandler implements ControlAuthenticationHandler{
   
       public void authenticate(String principal, Credentials credentials,
               SessionDetails sessionDetails, Callback callback) {
               
           // Logic to make the authentication decision.
           
           // Authentication decision
           callback.abstain();
          
           // callback.deny();
           // callback.allow();
        
       }
       
       @Override
       public void onActive(RegisteredHandler handler) {
           
       }
   
       @Override
       public void onClose() {
           
       }
       
   
   }

   1. Implement the authenticate method.
   2. Use the allow, deny, or abstain method on the Callback object to respond with the authentication decision.
   3. You can override the onActive and onClose to include actions the control authentication handler performs when the client opens its connection to the Diffusion server and when the client closes its session with the Diffusion server.
      For example, when the client session becomes active, the control authentication handler uses the onActive method to open a connection to a database. When the client session is closed, the control authentication handler uses the onClose method to close the connection to the database.
4. Create a simple client that registers your control authentication handler with the Diffusion server.

   package com.example.client;
   
   import com.example.client.ExampleControlAuthenticationHandler;
   import com.pushtechnology.diffusion.client.Diffusion;
   import com.pushtechnology.diffusion.client.details.SessionDetails.DetailType;
   import com.pushtechnology.diffusion.client.features.control.clients.AuthenticationControl;
   import com.pushtechnology.diffusion.client.session.Session;
   import com.pushtechnology.diffusion.client.session.SessionFactory;
   
   import java.util.EnumSet;
   
   public class ExampleControlClient {
   
       public static void main(String[] args) {
           
           final Session session;
           
           // Create the client session
           SessionFactory sf = Diffusion.sessions();
           session = sf.principal("ControlClient1")
                       .passwordCredentials("Passw0rd")
                       .open("ws://diffusion.example.com:80");
   
           // Get the AuthenticationControl feature
           AuthenticationControl authControl = session.feature(AuthenticationControl.class);
           
           // Use the AuthenticationControl feature to register your control authentication 
           // handler with the name that you configured in Server.xml  
           authControl.setAuthenticationHandler("before-system-handler",
                   EnumSet.allOf(DetailType.class), new ExampleControlAuthenticationHandler());
   
       }
   }

   1. Create a session.
      Change the URL from that provided in the example to the URL of the Diffusion server.
   2. Use the session to get the AuthenticationControl feature.
   3. Use the AuthenticationControl feature to register your control authentication handler, ExampleControlAuthenticationHandler, using the name that you configured in the etc/Server.xml configuration file, before-system-handler.
5. Start your client.
   It connects to the Diffusion server and registers the control authentication handler with the name before-system-handler.