Just a second...

Authentication

You can implement and register handlers to authenticate clients when the clients try to perform operations that require authentication.

The handlers you can implement and register are the following:
  • Any number of local authentication handlers
  • Any number of control authentication handlers
  • At most one authorization handler
Note: Using authorization handlers for authentication is deprecated.

The server calls the authentication handlers (local and control) in the order that they are defined in the Server.xml file. Then, if required, the server calls the authorization handler.

If no handlers are defined, the server allows the client operation by default.

Authentication process

Figure 1. Authentication process for clients A connection request comes in from the client. Authentication handlers are called one after another. Principal, credentials, and session are passed as arguments to the handler's authenticate() method. If any handler returns a DENY response, that is used as the decision. If a handler returns an ABSTAIN response the decision passes to the next handler in the list. If all authentication handlers return an ABSTAIN response, the server returns a DENY response. If any handler returns an ALLOW response, the decision is passed to the authorization handler. The authorization handler is called, passing a client object to the onConnect() method. If the authorization handler returns a DENY response, the server denies the client operation. If the authorization handler returns an ALLOW response, the server allows the client operation.
  1. A client tries to perform an operation that requires authentication. For more information, see Client operations that require authentication.
  2. 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 authenticate() method:
    Principal
    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.
    Credentials
    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.
    SessionDetails

    This contains information about the client. The available details depend on what information the server holds about the client session. Some session information might not be available on initial connection.

    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 details it requires, so only these details are sent by the server (if available). This reduces the amount of data sent across the control client connection.

    Callback
    A callback that the authentication handler can use to respond to the authentication request by using the callback's allow(), deny(), or abstain() method.

    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 response.

  3. 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 session.
    • If the authentication handler returns ABSTAIN, the decision is passed to the next authentication handler listed in the Server.xml configuration file.
  4. If all authentication handlers respond with an ABSTAIN decision, the response defaults to DENY.
  5. If an authorization handler is configured in the Server.xml file, the server calls it. It passes the following parameter to the authorization handler's onConnect() method:
    Client
    The Client object has an associated Credentials object. This Credentials object is part of the Classic API and is different to the Credentials object used by the authentication handlers. The Classic API Credentials object contains two strings: username and password. The username string is equivalent to the Principal string used by the Unified API.
  6. The authorization handler can return a response of ALLOW or DENY.
    • If the authorization handler returns DENY, the client operation is rejected.
    • If the authorization handler returns ALLOW, the client operation is allowed.

Client operations that require authentication

The following client operations require authentication with the server:
Table 1. Client operations that require authentication
Client operation API version Behavior if operation is allowed Behavior if operation is denied
Connect to server Unified API The client connection to the server is accepted. The client connection to the server is rejected and is dropped.
Connect to server Classic API The client connection to the server is accepted. The client connection to the server is rejected and is dropped.
Change the principal associated with a client session Unified API The principal is changed. The principal is not changed, but the client session is not dropped.
Change the principal associated with a client session Classic API The principal is changed. In the Classic API, the principal is the username string inside the Credentials object. The principal is not changed, but the client session is not dropped.