com.sonicsw.security.pass.broker
Interface IAuthentication

public interface IAuthentication

Authentication SPI for delegation mode authentication

The Authentication SPI implementation is used by the SonicMQ broker for delegation mode authentication of JMS clients connecting to the Broker.

The implementation of this functionality requires implementing following interface:

com.sonicsw.security.pass.broker.IAuthentication

To take the advantage of this functionality, users must implement the core interface � IAuthentication.

com.sonicsw.security.pass.broker.IBrokerSecurityCache

The interface IBrokerSecurityCache is used to performing callback operations on the broker to find the external users being cached on the Broker.

The external users having an ACL associated with them or having the Durable subscription are cached on the Broker.

The external users which are currently connected are also cached on the broker, but are removed from the cache as soon as they are disconnected � with exception to the above.

It uses following two classes for exception

com.sonicsw.security.pass.broker.ConnectionException

com.sonicsw.security.pass.broker.UnauthenticatedException

How are the SPI implementations used by the Sonic runtime?

The Broker is configured with an �external� Authentication Domain with an Authentication SPI.

The Authentication SPI configuration contains the Authentication SPI name, its classname and its classpath. The Authentication Domain configuration uses this preconfigured Authentication SPI and here, users can provide attribute � which are to be added as name-value pair using Attribute Setting group box while configuring the Authentication Domain. These attributes are passed to the SPI implementation as a HashMap.

When the Broker starts, it instantiates the Authentication SPI and passes the attributes by calling it's #setConfigInfo(HashMap) method. It then calls init() on the implementation and calls #setSecurityCache(IBrokerSecurityCache) to set the Broker cache instance to the SPI implementation for callback operations. Now, the Authentication SPI in the �external� Authentication Domain is ready for use.

As a user tries to establish a JMS connection with a secured Broker, the broker checks for the user�s credential under its cache. If the user is an �internal user�, regular challenge and response based authentication is used.

If the user was not found in the internal user cache (and an Authentication SPI has been configured on the broker), then the Broker sends a request to the client JMS application to send the credentials. At this stage, the Login SPI is used by the SonicMQ client runtime to provide the byte[] of the credential. This byte[] is transmitted on the wire to the Broker.

The Broker then passes the user name with the byte[] to the IAuthentication SPI implementation. If the SPI throws an exception, the user is considered unauthenticated.

Upon successful authentication, the SPI returns a group array; these are the groups to which the user belongs to. These groups are groups defined in the External store, they are not SonicMQ groups.

For example, a user �Bob� might belong to three groups, namely, employee, HR Manager and Directory Administrator. Therefore, the returned String[] should contain employee, HR Manager and Directory Administrator as three items in the array.

These returned groups are used to add the user to appropriate ACL entry. A mapping of Internal Groups with External Groups is used.

By default, the user is added to internal PUBLIC group, as user must belong to this internal group to perform JMS messaging.

See Also:

IBrokerSecurityCache, ConnectionException,

Method Summary

boolean	aquireClientCredentials() By default, the implementation of this method must return true to be backward compatible with SonicMQ 6.0 release.
IPasswordUser	authenticate(java.lang.String username, byte[] credentials, java.security.cert.X509Certificate[] clientCert) This method is called by the SonicMQ Broker to authenticate a user with an external store.
void	init() Every time appropriate Authentication SPI or appropriate Authentication domain configuration information gets changed, SonicMQ runtime calls this method.
void	setConfigInfo(java.util.HashMap configuration) While configuring an �external� Authentication Domain, users have to select a preconfigured Authentication SPI name and provide attribute � which are to be added as name-value pair using Attribute Setting group box.
void	setSecurityCache(IBrokerSecurityCache cache) This method is called after successful completion of init() call.
IPasswordUser[]	updateUserInfo(java.lang.String[] users) The Broker, based on certain internal rules/conditions, will use this method to update credential of external users.

Method Detail

aquireClientCredentials

boolean aquireClientCredentials()

By default, the implementation of this method must return true to be backward compatible with SonicMQ 6.0 release.

When true is returned in this method, SonicMQ runtime sends additional request to the client for additional credentials (transformed password). This transformed password is created by using Login SPI on the client side.

When false is returned in this method, SonicMQ runtime dose not request the client for additional credentials (transformed password).

Returns:

true if the credentials are to be acquired by the client side.

authenticate

IPasswordUser authenticate(java.lang.String username,
                           byte[] credentials,
                           java.security.cert.X509Certificate[] clientCert)
                           throws ConnectionException,
                                  UnauthenticatedException

This method is called by the SonicMQ Broker to authenticate a user with an external store.

Parameters:

username - the user trying to connect.

credentials - an opaque object containing client credential (e.g., a user certificate etc.)

Returns:

IPasswordUser[]. This object contains the username used for the JMS connection. The groups contained in this object indicate the external groups the user belongs. The password in IPasswordUser is required as it is used to generate some part of the master secret for secured communication. If the user is invalid, the SPI implementer must throw UnauthenticatedException.

Throws:

ConnectionException

UnauthenticatedException -

See Also:

ILogin.getCredential(), IPasswordUser

init

void init()
          throws ConnectionException

Every time appropriate Authentication SPI or appropriate Authentication domain configuration information gets changed, SonicMQ runtime calls this method. Implementer can use this method to recreate their connection with changed configuration etc.

Note Users must not call IBrokerSecurityCache#updateExternalUsers(String[]) in this method as the IBrokerSecurityCache instance is set after this call.

Throws:

ConnectionException -

See Also:

IBrokerSecurityCache.updateExternalUsers(String[])

setConfigInfo

void setConfigInfo(java.util.HashMap configuration)

While configuring an �external� Authentication Domain, users have to select a preconfigured Authentication SPI name and provide attribute � which are to be added as name-value pair using Attribute Setting group box.

These attributes are passed to the SPI implementation as a HashMap.

Parameters:

configuration -

setSecurityCache

void setSecurityCache(IBrokerSecurityCache cache)

This method is called after successful completion of init() call.

The Security Cache responsible to manage the external users is supplied to the SPI implementation so that callback operations can be performed on the external users.

Parameters:

cache - Security Cache responsible to manage the external users

updateUserInfo

IPasswordUser[] updateUserInfo(java.lang.String[] users)
                               throws ConnectionException

The Broker, based on certain internal rules/conditions, will use this method to update credential of external users.

For example, while reading a durable subscription upon startup, the broker will call this method to update the credential of the users connected to the disconnected subscription.

The Broker also invokes this method when a callback operation on the IBrokerSecurityCache is performed.

Parameters:

users - external user names to be updated

Returns:

the updated credentials for the users

Throws:

ConnectionException -

See Also:

IBrokerSecurityCache.updateExternalUsers(String[])