Readme for the sample demonstrating
the Advanced Security feature
Pluggable Authentication Security Service (PASS)
Simple Login SPI implementation
JAAS based Login SPI implementation
External Authentication Domain sample
Security
Store
Authentication
SPI implementation
Management SPI
implementation
Management SPI events
Prerequisite: testing existing
sample
Testing Authentication SPI
implementation
Testing Management SPI implementation
Configuration
Configuring Authentication SPI
Configuring Management SPI
Creating External Authentication Domain
Creating Authorization policy for the External Authentication Domain
Associating the broker with new Authentication domain and Authorization policy
Reloading the broker component
Viewing external users and groups via SMC
Using management operation to refresh Broker's security cache
Using management operation to update the external Authentication Domain
Using SMC to
update the external Authentication Domain
Using management events to update the external Authentication Domain
This document explains how to configure and run the samples implementing the Pluggable Authentication Security Service (PASS) feature - an advanced security feature. This sample requires a secured SonicMQ broker installation.
There are three components in the PASS feature. They are
Login SPI – this is SonicMQ Client side plug-in
Authentication SPI – this is SonicMQ Broker side plug-in
Management SPI – this is SonicMQ Management Framework plug-in for Sonic Management Console
Various levels of details regarding the PASS feature can be found in
SonicMQ Configuration and Management Guide
SonicMQ Administrative Programming Guide
SonicMQ Deployment Guide
If you want the SonicMQ JMS client to authenticate to any third party security store before establishing a JMS session, then you must implement the Login SPI on the client side. The classes that implement this functionality are located under <SonicMQ_Install_Dir>\samples\AdvancedSecurity
Simple Login SPI implementation
Everything under the package com.sonicsw.samples.pass.loginSPI.simple demonstrates how to configure a Login SPI on the SonicMQ client side. There are three Java classes in this package
- Chat.java is a sample JMS client.
- SimpleLoginSPI.java is the implementation of interface com.sonicsw.security.pass.client.ILogin.
- SimplePasswordUser.java is the implementation of the interface com.sonicsw.security.pass.client.IPasswordUser
Running the sample
You will have to create a user named 'testUser'. Use password 'testPassword' on the SonicMQ Broker. This sample uses this user to demonstrate the feature. To run this sample, go to <SonicMQ_Install_Dir>\samples\AdvancedSecurity\scripts. Run the script RunSimpleLoginSPIClient.bat. (This script assumes that the broker is running at tcp://localhost:2506. To change, call the script with param '-h' to get help, which shows parameters for the script as well as for the underlying Chat sample being used).
JAAS Login SPI implementation
Everything under the package com.sonicsw.samples.pass.loginSPI.jaas demonstrates how to use the JAAS on the SonicMQ client side. This package contains two key classes – Chat.java and Talk.java. They are used for demonstrating a sample SonicMQ JMS client. The package com.sonicsw.samples.pass.loginSPI.jaas.impl contains one key class – BasicLogin.java. This class implements com.sonicsw.security.pass.client.ILogin interface. Its login() method uses JAAS CallbackHandler. The package com.sonicsw.samples.pass.loginSPI.jaas.module contains an implementaion of JAAS Login Module. It has a hardcoded valid user 'testUser' with the user's password as 'testPassword'. The package com.sonicsw.samples.pass.loginSPI.jaas.principal contains a JAAS principal. The JAAS Login Module is configured in the file BasicLogin.config under <SonicMQ_Install_Dir>\samples\AdvancedSecurity\scripts.
Running this sample
1. Run the script TestJAASLogin.bat to test the JAAS implementation. This test does not use any SonicMQ runtime dependencies.
2. You will have to create a user named 'testUser'. Use password 'testPassword' on the SonicMQ Broker. This sample uses this user to demonstrate the feature. This sample uses connection factory to configure Login SPI implementation.
3. To run this sample, go to <SonicMQ_Install_Dir>\samples\AdvancedSecurity\scripts. Run the script RunJAASLoginSPIClient.bat.
(This script assumes that the broker is running at tcp://localhost:2506. To change, call the script with param '-h' to get help, which shows parameters for the script).
If you want to extend the SonicMQ’s functionality to the users from any existing third party security store (like SunOne Directory Server), you will have to implement all three of these SPI. The classes used to demonstrate this feature are located in the package com.sonicsw.samples.pass.extAuthDomain.
Security Store
The third party security store is mimicked by using a set of XML files located at
<SonicMQ_Install_Dir>\samples\AdvancedSecurity\com\sonicsw\samples\pass\extAuthDomain\securityStore. The basic requirement in any authentication system is username (identity) and password (secret). The file Users.xml contains the users initially residing in the external security store. The file Groups.xml contains the groups and the group members initially residing in the external security store. Rest of the xml files are used for testing Management SPI events, explained later in the text.
The class XMLFileReader.java in the package com.sonicsw.samples.pass.extAuthDomain.util is used to parse the XML file. This package is also used by the Authentication SPI and Management SPI implementation. The class Group.java and IConstant.java is commonly used in by both the SPI implementations. Group.java is an implementation of com.sonicsw.security.pass.mf.IGroup interface.
Authentication SPI implementation
The package com.sonicsw.samples.pass.extAuthDomain.authspi contains the implementation com.sonicsw.security.pass.broker.IAuthentication interface, which is implemented by the class Authentication.java.
The class UpdateCache.java demonstrates how a callback can be implemented to update/refresh the Broker's security cache.
The class RefreshSecurity.java demonstrates how to use a management operation to trigger a update/refresh on the Broker's security cache administratively.
Management SPI implementation
The package com.sonicsw.samples.pass.extAuthDomain.mgmtspi contains the implementation com.sonicsw.security.pass.mf.IManagement interface, which is implemented by the class Management.java.
The class ReloadExternalDomain.java demonstrates how to use a management operation to reload/refresh the Management SPI implementation via the Sonic Management Console (SMC). This operation is performed on the Sonic Directory Service. It results in fetching the data from the external security store and caching the same on the Sonic Directory Server. This cached data is used by the SMC for configuration purposes only.
Management SPI events
The package com.sonicsw.samples.pass.extAuthDomain.mgmtspi.event contains a sample implementation demonstrating how to use the Management SPI events to continuously refresh the Sonic Directory Service's cached external security store data. Its implementation uses JMS as event transport. The overall result is similar to the class ReloadExternalDomain.java.
- EventGenerator.java is used to generate the events.
- EventTransport.java is a thread that listens for the events using JMS as transport
- EventLauncher.java is used to generate events, which are scoped to the following classes:- EventUsersAdded.java
- EventUsersDeleted.java
- EventUsersModified.java- EventGroupsAdded.java
- EventGroupsDeleted.java
- EventGroupsModified.javaLogin SPI implementation
The package com.sonicsw.samples.pass.extAuthDomain.loginspi contains the implementation of com.sonicsw.security.pass.client.ILogin interface, which is implemented by the class LoginSpiImpl.java.
The class PasswordUser.java implements the com.sonicsw.security.pass.client.IPasswordUser interface. This is also the class where a password transformation logic can be implemented.
The class Chat.java and Talk.java are used to simulate a SonicMQ JMS client. The class JMSClient.java is a class used by both the SonicMQ JMS client.
Prerequisite: testing existing sample
In this section, we will try to test the implementation without deploying the implementation to the SonicMQ runtime. The directory <SonicMQ_Install_Dir>\samples\AdvancedSecurity\scripts contains the scripts, the properties file, and the configuration file
Testing Authentication SPI implementation
Open the file AuthenticationSPI.properties. This file contains the information required for configuring and running a Authentication SPI implementation successfully. Change the value of SonicMQ install directory. This will make the property USERS_XML and GROUPS_XML point to the right xml file. Review the following so that the values are pointing to the right Sonic Directory Service with valid url, username and password.
SONIC_DS_DOMAIN_NAME=Domain1
SONIC_DS_DOMAIN_CONTAINER_NAME=DomainManager
SONIC_DS_BROKER_NAME=MgmtBroker
SONIC_DS_BROKER_URL=tcp://localhost:2506
SONIC_DS_BROKER_USERNAME=Administrator
SONIC_DS_BROKER_PASSWORD=Administrator
Make appropriate changes and save the file. Start the SonicMQ Broker. Run the script TestAuthenticationSPI.bat to test the implementation. Fix errors, if any, before continuing to run this PASS sample. Note that the Update Cache thread will run for some time before exiting.Testing Management SPI implementation
Open the file ManagementSPI.properties. This file contains the information required for configuring and running a Management SPI implementation successfully. Change the value of SonicMQ install directory. This will make the property USERS_XML and GROUPS_XML point to the right xml file. Review the following so that the values are pointing to the right Sonic Directory Service with valid url, username and password.
SONIC_DS_ID=Domain1.DomainManager:ID=DIRECTORY SERVICE
SONIC_DS_BROKER_URL=tcp://localhost:2506
SONIC_DS_BROKER_USERNAME=Administrator
SONIC_DS_BROKER_PASSWORD=AdministratorMake appropriate changes and save the file. Start the SonicMQ Broker. Run the script TestManagementSPI.bat to test the implementation. Fix errors, if any, before continuing to run this PASS sample. Note that event transport thread will create a TopicConnection and wait for any events. This program will not exit automatically; therefore, use ctrl-C to kill the java session.
Configuration
In this section, we will create an external authentication domain. If you have installed the SonicMQ product, you will, by default, get a DomainManager container with a MgmtBroker and Directory Service. Start the DomainManager container and the Management Console. Go to the 'Configure' tab in the Sonic Management Console (SMC). Here, you will find a broker under the Brokers node called MgmtBroker. Open the MgmtBroker's properties. Observe that the broker is configured with one Authentication Domain and one Authorization Policy, namely Default Authentication and Default Policies. Our goal is to create an 'external' authentication domain and associate MgmtBroker with the newly created authentication domain.
Configuring Authentication SPI
We will create a configuration based on file AuthenticationSPI.properties. Using the SMC, go to the Security node. Right click to select New --> Configuration... popup-menu. This will launch the 'Create Configuration' window. Create a new configuration for the 'Authentication SPI'. Under Sonic Security node, select the 'Authentication SPI' and click the ok button. This will launch the 'New Authentication SPI' window. Type-in the desired SPI Name. Open the AuthenticationSPI.properties. The classname is mentioned within the section 'Configuration information'. The required classpaths are also mentioned in the same file. Fill in the values for the new Authentication SPI configuration. Click Ok button to save the changes. Check if the newly added Authentication SPI is visible in the SMC.
Configuring Management SPI
We will create a configuration based on file ManagementSPI.properties. Using the SMC, go to the Security node. Right click to select New --> Configuration... popup-menu. This will launch the 'Create Configuration' window. Create a new configuration for the 'Management SPI'. Under Sonic Security node, select the 'Management SPI' and click the ok button. This will launch the 'New Management SPI' window. Type-in the desired SPI Name. Open the ManagementSPI.properties. The classname is mentioned within the section 'Configuration information'. The required classpaths are also mentioned in the same file. Fill in the values for the new Management SPI configuration. Click Ok button to save the changes. Check if the newly added Management SPI is visible in the SMC.
Creating External Authentication Domain
Using the SMC, go to the Security node. Right click to select New --> Configuration... popup-menu. This will launch the 'Create Configuration' window. Create a new configuration for the 'Authentication Domain'. Select the 'Authentication Domain' and click the ok button. This will launch the 'New Authentication Domain' window. Type-in the desired Domain Name. Check the 'Use External Domain' checkbox. This will enable the access to the three tabs, which are AuthSPI, MgmtSPI and Group Maps.
Go to the AuthSPI tab. Select the newly configured Authentication SPI configuration under the 'Authentication SPI Name' dropdown. The attributes for this SPI are located in the file AuthenticationSPI.properties. You can type the values or use import button to import the properties file.
Go to the MgmtSPI tab. Select the newly configured Management SPI configuration under the 'Management SPI Name' dropdown. The attributes for this SPI are located in the file ManagementSPI.properties. You can type the values or use import button to import the properties file.
Go to the Groups Map tab. This is the mapping used by the SonicMQ broker. Here, the internal groups are mapped to external groups. The valid values are mentioned in the file AuthenticationSPI.properties. They are
PUBLIC=Accounting Managers,PD Managers,HR Managers
Administrators=Directory Administrators
TxnAdministrators=Directory Administrators
Click Ok to create the external Authentication Domain. The 'Default Authentication' has a user that has the name 'MgmtBroker'. This is an internal user you will have to create in the newly create external Authentication Domain. Using the SMC, find the newly created external Authentication Domain. Expand and find the node 'Users'. Here, create a user MgmtBroker with password SonicMQ.
Creating Authorization policy for the External Authentication Domain
Using the SMC, go to the Security node. Right click to select New --> Configuration... popup-menu. This will launch the 'Create Configuration' window. Create a new configuration for the 'Authorization Policy'. Select the 'Authorization Policy' and click the ok button. This will launch the window to create a new Authorization Policy. Type-in a name and associate the policy with the newly created external authentication domain.
Associating the broker with new Authentication domain and Authorization policy
Go to the Brokers node in the SMC and find the broker MgmtBroker. Right click to launch the popup-menu and select Properties to view the broker's properties. Change the Authentication Domain and Authorization Policy to point to the newly created Authentication Domain and Authorization Policy.
Reloading the broker component
Right click the MgmtBroker to launch the popup-menu and select goto 'Manage'. This will make you reach the Manage tab of the SMC. Here, reload the broker. Once the broker is successfully reloaded, you are ready to run the JMS client implementation, use the management operation to refresh Broker's security cache, use the management operation to update the external Authentication Domain, use the SMC to update the external Authentication Domain and use the management events to update the external Authentication Domain.
Viewing external users and groups via SMC
If you have just created the external Authentication Domain with Management SPI, they you have to reload the external Authentication Domain into the Sonic Directory Service. Automatic reloading occurs only if the checkbox to reload at startup is checked (in the external Authentication Domain configuration for the Management SPI) and the Sonic Directory Service container is restarting. See Using management operation to update the external Authentication Domain Using management operation to update the external Authentication Domain and Using SMC to update the external Authentication Domain.
Running the Client
Use the script RunExtAuthDomainClient.bat to run a Chat or Talk or DurableChat client that uses Login SPI and communicates with a broker using external Authentication Domain.
Using management operation to refresh Broker's security cache
If a JMS client is connected to the Broker or its credentials are cached by the Broker's security cache, administrators can used a management operations to refresh the desired broker's security cache.
Use the script RunExtAuthDomainClient.bat to launch a DurableChat client. This will cache the credential of the user till the durable subscription exists on the Broker. Use command like - RunExtAuthDomainClient.bat DurableChat - which will launch and use a durable JMS session for chatting. Once the connection is made, close/kill the client session. Next, use the script RefreshSecurity.bat to refresh the Broker's security cache.
Using management operation to update the external Authentication Domain
The Sonic Directory Service caches the external users and the groups for every configured Management SPI implementation on an external Authentication Domain. As the time passes, such cache can get stale. Administrators can use a script to update the cache. Use the script ReloadExtAuthDomain.bat to refresh the configured implementation.
Using SMC to update the external Authentication Domain
The above functionality can also be achieved using SMC. Go to the 'Manage' tab and locate the node 'DIRECTORY SERVICE'. This node will exist on the container managing the Sonic Directory Service. Right-click to launch the popup-menu and select Operartions ---> Reload External Authentication Domain. Select the desired external Authentication Domain and click the reload button.
Using management events to update the external Authentication Domain
Using SMC, you can view the external users and groups. They will be found at the 'External Groups' and 'External Users' node under the external Authentication Domain. Using the script MgmtEventLauncher.bat, you can execute six events. They are GroupsAdded, GroupsModified, GroupsDeleted, UsersAdded, UsersModified and UsersDeleted. Use the SMC to check if such changes are taking place. Click refresh icon to refresh the SMC, if the SMC has not refreshed.
Copyright (c) 2015. Aurea Software, Inc. All Rights Reserved.