Role-based authorization

An authorization handler is a user-written Java™ class that must implement the AuthorisationHandler interface in the .

Such a handler can be used to restrict access of clients according to any criteria that is appropriate. One capability within Diffusion is for a client to be able to specify Credentials when they connect that can be checked by the authorization handler.

The handler can either be specified in etc/Server.xml in which case it is loaded when the server starts or can be set programmatically within a publisher using the Publishers.setAuthorisationHandler method.

There can only be one handler and it is system wide across all publishers, although you can have authorization at the publisher level.

If an authorization handler is not specified, credentials sent by a client are assumed to be valid. A publisher has access to the credentials to perform finer-grained authorization, if required.

The authorization handler interface has the following methods:

Authentication

When a client connects to Diffusion it has the option of supplying user credentials. These credentials are basically tokens called username and password. These tokens can be used for any purpose. When canConnect is called, you can get the credentials from the Client object.

An example of this is:

    public boolean canConnect(Client client) {
	Credentials creds = client.getCredentials();

	// No creds supplied, so reject the connection
	if (creds == null) {
	    return false;
	}
	
	String username = creds.getUsername().toLowerCase();

If the credentials are null, none were supplied, which is different from empty credentials. If you set the username as an empty string (that is, an anonymous user) the password is not stored and you cannot retrieve it with getCredentials.

Clients can connect without credentials and submit them later or replace the credentials at any time whilst connected. The authorization handler is notified when new credentials are submitted and can choose to set the new credentials on the client.

The Credentials class has username and password attributes, but also allows for an attachment. It is here that a user normally sets any security object required. Returning true will allow the user to connect, returning false will result in the client connection being refused.

Subscription authorization

Subscription authorization is the allowing of a client to subscribe to a topic. In this case the canSubscribe is called. Returning true here allows the publisher to have any topic loaders and subscription methods called. Returning false will not notify the client that the subscription was invalid.

public boolean canSubscribe(Client client, Topic topic) {

    // Everyone has access to the top level topic
    if (topic.getName().equals(CHAT_TOPIC)) {
        return true;
    }

    User user = (User) client.getCredentials().attachment();

    return user.isAllowedRoom(topic.getNodeName());
}

Authorization handler

Authorization at the publisher level can also be achieved. This is required if there are many publishers running within the same Diffusion Server and they have different security settings. The following code example works if the publishers all implement AuthorisationHandler

public boolean canSubscribe(Client client, Topic topic) {

    AuthorisationHandler handler = 
            (AuthorisationHandler)Publishers.getPublisherForTopic(topic);

    // Call the publisher in question
    return handler.canSubscribe(client, topic);
}

Permissions

The permissions process governs whether a client is able to send messages to a publisher, or in other words, is the topic read only. This is handled by the canWrite method. Again a good pattern might be to look at the credentials attachment object to see if this is permissible.

public boolean canWrite(Client client, Topic topic) {
	User user = (User) client.getClientCredentials().attachment();
	return user.canWriteMessages(topic);
}