Expand Collapse
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

The server calls the authentication handlers (local and control) in the order that they are defined in the Server.xml file.

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 connection is allowed.
  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.
    SessionProperties

    This contains information about the client. The available properties depend on what information the server holds about the client session.

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

    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.

    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.

Client operations that require authentication

The following client operations require authentication with the server:
Table 1. Client operations that require authentication
Client operation 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 dropped.
Change the principal associated with a client session The principal is changed. The principal is not changed, but the client session is not dropped.