Developing a composite control authentication handler

Extend the CompositeControlAuthenticationHandler class to combine the decisions from multiple control authentication handlers.

Using a composite control authentication handler reduces the number of messages that are sent between the Diffusion™ server and the client to perform authentication.

This example describes how to use a composite control authentication handler as part of a client remote from the Diffusion server.

Edit the etc/Server.xml configuration file to point to your composite control authentication handler.
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 composite 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 composite control authentication handler -->
    <control-authentication-handler handler-name="example-composite-control-authentication-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.
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.
Create the individual control authentication handlers that your composite control authentication handler calls.
You can follow steps in the task Developing a control authentication handler.

In this example, the individual control authentication handlers are referred to as HandlerOne, HandlerTwo, and HandlerThree.

Extend the CompositeControlAuthenticationHandler class.

package com.example.client;

import com.example.client.HandlerOne;
import com.example.client.HandlerTwo;
import com.example.client.HandlerThree;

import com.pushtechnology.diffusion.client.features.control.clients.CompositeControlAuthenticationHandler;

public class ExampleHandler extends CompositeControlAuthenticationHandler {

    public ExampleHandler() {
        super(new HandlerOne(), new HandlerTwo(), new HandlerThree());
    }
    
}

Import your individual control authentication handlers.
Create a no-argument constructor that calls the super class constructor with a list of your individual handlers.

Create a simple client that registers your composite control authentication handler with the Diffusion server.
You can follow steps in the task Developing a control authentication handler.

Ensure that you register your composite control authentication handler, ExampleHandler, using the name that you configured in the etc/Server.xml configuration file, example-composite-control-authentication-handler.
Start your client.
It connects to the Diffusion server and registers the composite control authentication handler.

When the client session starts, the composite control authentication handler calls the onActive methods of the individual control authentication handlers in the order in which they are passed in to the composite handler.

When the composite control authentication handler is called, it calls the individual control authentication handlers that are passed to it as parameters in the order they are passed in.

If an individual handler responds with ALLOW, the composite handler responds with that decision to the Diffusion server and a list of any roles to assign to the authenticated principal.
If an individual handler responds with DENY, the composite handler responds with that decision to the Diffusion server.
If an individual handler responds with ABSTAIN, the composite handler calls the next individual handler in the list.
If all individual handlers respond with ABSTAIN, the composite handler responds to the Diffusion server with an ABSTAIN decision.

When the client session closes, the composite control authentication handler calls the onClose methods of the individual control authentication handlers in the order in which they are passed in to the composite handler.