Readme for the sample demonstrating

 

the Advanced Security feature

 

Pluggable Authentication Security Service (PASS)

 


 

 

Introduction

 

 

Login SPI samples

   Simple Login SPI implementation

        Running the sample

   JAAS based Login SPI implementation

        Running the sample

 

 

External Authentication Domain sample

    Security Store
    Authentication SPI implementation
    Management SPI implementation
       
Management SPI events

    Login SPI implementation

   

    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

 

    Running the Client

    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
 

Introduction

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

Various levels of details regarding the PASS feature can be found in

SonicMQ Configuration and Management Guide

SonicMQ Administrative Programming Guide

SonicMQ Deployment Guide

 

top

Login SPI samples

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

top

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

top

External Authentication Domain sample

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.

top

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.

top

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.

top

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.java

top

Login 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.

top

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.

top

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=Administrator

Make 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.

top

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.

top

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.

top

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.

top

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.

top

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.

top

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.

top

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.

top

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.

top

 

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.

top

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.

top

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.

top

 

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.

top


Copyright (c) 2015. Aurea Software, Inc. All Rights Reserved.