The server calls the authentication handlers one after another in the order that
they are listed in the Server.xml file. It passes the
following parameters to each authentication handler's
A string that contains the name of the principal or identity that is
connecting to the server or performing the action. This can have a
value of Session.ANONYMOUS.
The Credentials object contains an array of bytes
that holds a piece of information that authenticates the principal.
This can be empty or contain a password, a cryptographic key, an
image, or any other piece of information. The authentication handler
is responsible for interpreting the bytes.
This contains information about the client. The available properties
depend on what information the server holds about the client
This information can be used in the authentication decision. For
example, an authentication handler can allow connection only
from clients that connect from a specific country.
When it registers with the server, a control authentication
handler can specify what properties it requires, so only these
properties are sent by the server (if available). This reduces the
amount of data sent across the control client
The authentication handler is passed two property maps.
The sessionProperties map contains the fixed properties for the session,
and if re-authenticating, can also contain the user-defined properties of the current session.
The proposedProperties map contains any user-defined properties proposed by the client when opening the session.
This map is empty when re-authenticating.
Client-proposed session properties can provide additional information
about the client that can be used later to select or filter sessions. They can also provide
credential information for use in the authentication decision.
A callback that the authentication handler can use to respond to the
authentication request by using the callback's
allow(), deny(), or
If the authentication handler is a local authentication handler, the
authentication logic is done on the server. If the authentication handler is
a control authentication handler, the parameters are passed to a control
client and the control client handles the authentication logic and returns a
Each authentication handler can return a response of ALLOW,
DENY, or ABSTAIN.
If the authentication handler returns DENY, the
client operation is rejected.
If the authentication handler returns ALLOW, the
decision is passed to the authorization handlers. The authentication
handler can also provide a list of roles to assign to the client
If the authentication handler returns ABSTAIN, the
decision is passed to the next authentication handler listed in the
Server.xml configuration file.
If all authentication handlers respond with an ABSTAIN
decision, the response defaults to DENY.
Client operations that require authentication
The following client operations require authentication with the server:
Table 1. Client operations that require authentication
Behavior if operation is allowed
Behavior if operation is denied
Connect to server
The client connection to the server is accepted.
The client connection to the server is rejected and is
Change the principal associated with a client session
The principal is changed.
The principal is not changed, but the client session is not