Extending security

IBM® WebSphere® sMash security leverages the flexible event-based system to make it easy to add your own security implementations. With this enhanced flexibility, you can implement your own request processing event handler for secure, authenticate and authorize events as well as registering preauthenticate handlers for security related tasks that do not fit neatly with the authenticate and authorize events.

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:

Event name	Description	Maximum number of handlers invoked	Early termination criteria	Reaction to Exceptions
`preauthenticate`	Perform security related checks that should be fired prior to invoking the authenticate check, for instance requireSSL.	No limit	`/request/status` is set	Return status code 500; skip to the `log` event
`authenticate`	This is a dual purpose event handler. The first purpose of this event handler is to process login credentials when necessary for authTypes such as Form and OpenID. The second purpose is to perform authentication check based on `authType`	1	`/request/status` is set	Return status code 500; skip to the `log` event
`authorize`	Perform authorization checks	No limit	`/event/isAuthorized` is set to true	Return status code 500; skip to the `log` event

Extending authentication

To implement authentication, use the following steps:

Choose a name for your authentication scheme to be specified in the security rules as authType.
Implement a handler for the event name authenticate.
Register the event name in the configuration file of your library or application as a handler for that event.
Implement a handler for the event name retrieveCredentials.
Register the event name in the configuration file of your library or application as a handler for that event.

For example, if your authType is digest, you would implement a handler with the method authenticate and add the following stanza to the configuration file:

/config/handlers += [{
   "events" : "authenticate",
   "handler" : "com.myimpl.DigestSecurityHandler.class",
   "conditions": "/request/authType == digest"
}]

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

/config/handlers += [{
	"events" : "retrieveCredentials",
	"handler" : "com.myimpl.DigestUserInfoResolver.class",
	"conditions": "/request/authType == digest"
}]

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);

The method by which users extend authentication was rewritten after WebSphere sMash 1.0 was released. If by chance, you were an early adopter for extending security, please refer to the Deprecated security functions section of the Developer's Guide. Currently, the previously documented way for extending authentication will continue to work but we suggest migrating to the latest method detailed above.

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.

To make sure that CSRF credentials are added and to prevent certain attacks, consult the article Cross Site Request Forgery in the section regarding adding authentication mechanisms of the cross-site request forgery protection for some simple rules to follow.

Extending authorization

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.

To guarantee security against cross-site request forgery attacks, it is crucial that you also follow some simple rules as outlined in the section on adding authorization mechanisms of the CSRF protection document

Defining a custom authorization handler

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.