Configuring authentication handlers

To configure authentication handlers for your server, edit the Server.xml configuration file to include the following elements:

	<security>
		<authentication-handlers>
			<authentication-handler class="com.example.LocalLDAPHandler" />
			<system-authentication-handler/>
			<control-authentication-handler handler-name="RemoteHandler" />
		</authentication-handlers>
	</security>

Ordering your configuration handlers

The order of handler elements within the <authentication-handlers> element defines the order in which the authentication handlers are called. In the preceding example, localLDAPHandler is called first. If localLDAPHandler returns an ABSTAIN result, the system authentication handler is called next. If the system authentication handler returns an ABSTAIN result, RemoteHandler is called next.

Order your authentication handlers from least to most restrictive and configure your handlers to abstain unless they are to explicitly allow or deny the authentication request.

For more information, see Authentication.

Configuring local authentication handlers

Configure local authentication handlers by using the <authentication-handler/> element. The value of the attribute class is the class name for the handler.

You can configure any number of distinct local authentication handlers in the Server.xml file.

Configuring the system authentication handler

You can configure Diffusion to use the system authentication handler by using the <system-authentication-handler/> element. The system authentication handler uses information in the system authentication store to make authentication decisions.

You can configure the system authentication handler to be called at most once. This restriction is not enforced by the XSD for the Server.xml file, but the Diffusion server does enforce this restriction on the configuration.

Configuring control authentication handlers

Configure control authentication handlers are configured by using the <control-authentication-handler/> element. The value of the attribute handler-name is the name by which the handler was registered by the control client. Control clients use the AuthenticationControl feature to register the handler and passing the binding name as a parameter.

If no control client has registered a control authentication handler with the name defined in the configuration file, the response for that handler is ABSTAIN.

If you are using a cluster of Diffusion servers and configuration replication is enabled, authentication requests will be routed to across the cluster, meaning it is only necessary for a handler to connect to one server in the cluster.

Multiple control clients can register a control authentication handler with the same name. Registering a control authentication handler from multiple clients gives the following advantages:

If one of the control clients becomes unavailable, another can handle the authentication request.
Control clients can be changed or updated without affecting the authentication behavior.
Authentication requests can be load balanced between the control clients.

You can configure any number of distinct control authentication handlers in the Server.xml file.

If you are using a cluster of servers, the security configuration must be the same on all the servers in the cluster.

Note: To register a control authentication handler, an authenticating client must first connect to and authenticate with the server. We recommend that you configure a local authentication handler or the system authentication handler in the Server.xml file to authenticate the control client.