Extending security

For more information on the secure and authorize events, see the section on Request-processing events. The following sections of this article provide more information about how you can extend security:

Secure event processing

The following table summarizes the sub-events, in order, run by WebSphere sMash during security processing of the secure event:

Defining a preauthentication handler

1. Implement a handler for the event name preauthenticate.
2. Register the event name in the configuration file of your library or application as a handler for that event.

For example, you would implement a handler with the method onPreauthenticate and add the following stanza to the configuration file:

/config/handlers += [{
   "events" : "preauthenticate",
   "handler" : "com.myimpl.RequireSSLHandler.class",
   "conditions" : "/request/scheme != https"
}]

As the name implies, the example preauthenticate handler forbids http access to a resource based upon a set of conditions. The handler is registered with a condition based upon the request scheme. If the request scheme is considered forbidden, then the secure event will call this preauthenticate handler resulting in a HTTP Forbidden status code of 403 as shown in the following code example.

public void onPreauthenticate() {
	GlobalContext.zput(Request.status, HttpURLConnection.HTTP_FORBIDDEN);
	GlobalContext.zput(Request.view, "error");
	ViewEngine.render();
}

Defining a custom authentication handler

1. Implement a handler for the event name authenticate.
2. Register the event name in the configuration file of your library or application as a handler for that event.
3. Implement a handler for the event name retrieveCredentials.
4. Register the event name in the configuration file of your library or application as a handler for that event.

For example, you would implement a handler with the method onAuthenticate and add the following stanza to the configuration file:

/config/handlers += [{
   "events" : "authenticate",
   "handler" : "com.myimpl.DigestSecurityHandler.class",
   "conditions" : "/request/path =~ /(.*)?"
}]

Now that you have defined the authentication handler, the next step is define a handler that knows how to interpret digest authentication headers.

/config/handlers += [{
	"events" : "retrieveCredentials",
	"handler" : "com.myimpl.DigestUserInfoResolver.class",
	"conditions" : "/request/path =~ /(.*)?",
}]

In the retrieveCredentials event, the handler is required to populate the event zone's userName and password values prior to exiting the event for later use by the security runtime as shown in the code snippet below.

GlobalContext.zput(Event.userName, user);
GlobalContext.zput(Event.password, password);

These events are fired by the global security handler after firing the preauthenticate event handlers. This allows you to use your handler with the standard security rules.

Defining a custom authorization handler

To implement a custom authorization handler, create a handler with a method name of onAuthorize then define the appropriate application handler stanza. Note that whereas the authenticate event can only be associated with one handler, the authorization handler allows multiple handlers to be registered in addition to the default authorization handler that is provided as part of WebSphere sMash security. Depending on the rules that are matched for the request, one or more handlers could be run for the authorize event. Once a handler sets the value isAuthorized to true in the event zone, processing of additional handlers is terminated.

In the following example, the custom authorization handler checks to ensure that the custom event handler data myCustomSetOfRules matches ADMIN and is authorized to view this resource:

/config/handlers += [{
   "events" : "authorize",
   "handler" : "zero.core.security.auth.CustomAuthorizationHandler.class",
   "conditions" : "/request/path =~ /formauth/subject(/.*)?",
   "instanceData" : {
               "myCustomSetOfRoles" : "ADMIN"
            }
}]

Because there are no explicit definitions of user, group or role in the security constraint, the default authorization handler does not authorize this user.