Authentication
You can implement and register handlers to authenticate clients when the clients try to perform operations that require authentication.
- Any number of local authentication handlers
- Any number of control authentication handlers
- At most one authorization handler
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
- A client tries to perform an operation that requires authentication. For more information, see Client operations that require authentication.
- 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.
- 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.
- If all authentication handlers respond with an ABSTAIN decision, the response defaults to DENY.
- 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.
- 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
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. |
This page last modified: 2017/05/24