Configuring authentication handlers

Authentication handlers (authenticators) and the order that the Diffusion™ Cloud server calls them in are configured in the Server.xml configuration file.

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 authenticators

Configure local authenticators 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 authenticators in the Server.xml file.

Configuring the system authentication handler

You can configure Diffusion Cloud 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 Diffusion Cloud does enforce this restriction on the configuration.

Configuring control authenticators

Control authenticators 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 authenticator and passing the binding name as a parameter.

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

Multiple control clients can register a control authenticator with the same name. Registering a control authenticator 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 behaviour.
Authentication requests can be load balanced between the control clients.

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

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