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 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 |
|---|---|---|---|---|
| <authType>Secure | 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
Complete the following steps to implement authentication:- Choose a name for your authentication scheme to be specified in the security rules as
authType. - Implement a handler for the event name <authType>Secure.
- 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 more information on how events are processed please refer to the Event processing section of the Developer's Guide.
For example, if your authType is digest, you would implement a handler with the method onDigestSecure and add the following stanza to the configuration file:
/config/handlers += [{
"events" : "digestSecure",
"handler" : "com.myimpl.DigestSecurityHandler.class"
}]
Now that you have defined the authentication handler, the next step is define a handler that knows how to interpet 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);
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 <authType>Secure 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.
