Expand Collapse
Just a second...

Authentication

You can implement and register handlers (known as authenticators) to authenticate clients when the clients try to perform operations that require authentication.

The authenticators you can implement and register are the following:
  • Any number of local authenticators
  • Any number of control authenticators

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

If no authenticators 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. Authenticators are called one after another. Principal, credentials, and session properties are passed as arguments to the authenticator's authenticate() method. If any authenticator returns a DENY response, that is used as the decision. If an authenticator returns an ABSTAIN response the decision passes to the next authenticator in the list. If all authenticators return an ABSTAIN response, the server returns a DENY response. If any authenticator 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 authenticators one after another in the order that they are listed in the Server.xml file. It passes the following parameters to each authenticator'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 authenticator 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 authenticator can allow connection only from clients that connect from a specific country.

    When it registers with the server, a control authenticator 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 authenticator 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, or re-authenticating the session.

    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 authenticator can use to respond to the authentication request by using the callback's allow(), deny(), or abstain() method.

    If the authenticator is a local authenticator, the authentication logic is done on the server. If the authenticator is a control authenticator, the parameters are passed to a control client and the control client handles the authentication logic and returns a response.

  3. Each authenticator can return a response of ALLOW, DENY, or ABSTAIN.
    • If the authenticator returns DENY, the client operation is rejected.
    • If the authenticator returns ALLOW, the decision is passed to the authorisation handlers. The authenticator can also provide a list of roles to assign to the client session.
    • If the authenticator returns ABSTAIN, the decision is passed to the next authenticator listed in the Server.xml configuration file.
  4. If all authenticators 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 Behaviour if operation is allowed Behaviour if operation is denied
Initial connection to server The client connection to the server is accepted. The client connection to the server is rejected and is dropped.
Re-authenticate a client session The session is re-authenticated, possibly with a different principal, and different session properties, including a different expiry time. The session is not re-authenticated, but the client session is not dropped. This means that the session may still expire if it previously had an expiry time set.

Session Expiry

There is a fixed session property called $ExpiryTime which can be set by an authenticator to indicate that a session's authentication should expire at a given time. The property may be set to an absolute time specified as milliseconds since the epoch.

By default, this property is not set by the server and so the session will not expire. If the authenticator sets the value the session will automatically be closed when the expiry time is reached. If the authenticator sets the value incorrectly (an invalid number or a time in the past) an error will be logged and the authentication will fail (as if the authenticator had denied access).

The client session may obtain the value of this property (using the getSessionProperties method on the Session) and re-authenticate (using the reauthenticate method on the Security feature) at any time before the session expires. The authenticator may then set a new expiry time, or reject the re-authentication request.

A suitably privileged user can revoke the authentication at any time (using the revokeAuthentication method on the AuthenticationControl feature), and the session will be closed immediately.