Implement the ControlAuthenticationHandler
interface to create a control authentication handler.
A control authentication handler can be implemented in any language where the
Diffusion™
Unified API includes the AuthenticationControl feature.
For more information, see .
This example demonstrates how to implement a control authentication
handler in Java™.
Note: Where c.p.d is used in package
names, it indicates
com.pushtechnology.diffusion.
-
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.
-
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 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() {
}
}
-
Ensure that you import Credentials from the
c.p.d.client.types package,
not the c.p.d.api package.
-
Implement the authenticate method.
-
Use the allow, deny, or
abstain method on the Callback
object to respond with the authentication decision.
-
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.
-
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());
}
}
-
Create a session.
Change the URL from that provided in
the example to the URL of the Diffusion server.
-
Use the session to get the AuthenticationControl
feature.
-
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.
-
Start your client.
It connects to the Diffusion server and registers the control
authentication handler with the name
before-system-handler.
When a client authenticates, the Diffusion server forwards the
authentication request to the authentication handler you have registered. Your
authentication handler can ALLOW, DENY, or ABSTAIN from the authentication decision. If
your authentication handler returns an ALLOW or DENY decision, this decision is used as
the response to the authenticating client. If your authentication handler returns an
ABSTAIN decision, the Diffusion server forwards the authentication request
to the next authentication handler. For more information, see Authentication.