Prerequisites

Install and Configure JOSSO

You should first setup JOSSO for one of the supported platforms such as Tomcat and JBoss. Check the specific Setup HOW-TO corresponding to the platform where JOSSO is going to be installed.

Once you're done with the initial setup make sure that the JOSSO web application is accessible.

To be able to use some of the management features available, you will need to build and deploy JOSSO with the exclude.config option set to true. See the Configuring or Deploying section of your platform specific Setup guide for details.

If using Tomcat 5.5 with JDK 1.5 you must install Apache Xalan-J. Some APIs used by the management infrastructure are not compatible with the Xalan part of the JDK 1.5 . Simply copy all jars found in Xalan-J distribution root directory to $CATALINA_HOME/common/endorsed. Xalan-J is already included in the JOSSO bundle for the Tomcat Container.

Introduction

Monitoring and Managing are very important features. Inspecting the SSO server, reconfiguring any component and collecting statistical information about SSO activity are part of everyday administration tasks. JOSSO allows you to mange and monitor the SSO Gateway and SSO Agents based on the Java Management Extension (JMX) standard. JMX is a specification for monitoring and managing Java applications. It enables a generic management system to monitor an application, raise notifications when the application needs attention, and change the state of the application to remedy problems. JMX is a public specification and is being used as the standard management mechanism by all platforms supported by JOSSO. In addition, JOSSO can persist modifications made to component properties through JMX in JOSSO configuration files. This ensures that no update made to SSO settings will be lost on server restart.

This How-To will explain how to perform basic monitoring and managing tasks using MC4J (Management Console for Java) JMX console. MC4J is an open source project to create management software for J2EE application servers and other Java applications

Note
MC4J is not mandatory, you could use any other JMX console you prefer.

Setup the JMX layer

Configure JMX for your selected platform

Refer to the specific JMX documentation corresponding to the platform where JOSSO is installed to setup the JMX layer. You can configure security, preferred implementation, etc. JOSSO was tested using server specific and JDK 1.5 JMX implementations.

Install MC4J

Refer to MC4J documentation for installing and configuring the console to work with your selected platform. MC4J supports all servers where JOSSO can be deployed.

Once you're done with the MC4J setup, you can install JOSSO specific dashboards which provide custom views of JOSSO activity as console reports. Dashboards are distributed with JOSSO and can be found at $JOSSO_HOME/src/samples/jmx/

To execute the following commands, you need to define JOSSO_HOME and MC4J_HOME environment variables or replace them with the specific path where you have installed each product.

For Unix systems you can use :

$ cd $MC4J_HOME/dashboards
$ mkdir josso
$ cp $JOSSO_HOME/src/samples/jmx/*.xml ./josso

For Win32 systems you can use :

cd %MC4J_HOME%\dashboards
mkdir josso
copy %JOSSO_HOME%\src\samples\jmx\*.xml .\josso

MC4J allows you to build your own dashboards, you can create specific layouts and views, including those metrics that are more relevant for your installation. Take a look at MC4J documentation on dashboards for details.

JOSSO Managed Beans

Every JOSSO component exposes a manageable interface as an MBean. Some MBeans have a set of operations that can be invoked directly from the console, for example you could invalidate a specific session using the invalidate operation provided by the SSOSessionManager MBean or you could configure a new partner application using the SSOAgent MBean. MBeans contain also a collection of attributes which provide for instance information about SSO activity, like the open sessions count. Others attributes represent component settings that could be modified, like the session maximum inactive interval.

When you modify an MBean attribute, JOSSO will update the corresponding configuration file with the new value, creating a backup copy with the original content.

Changes to attributes will take effect immediately altering JOSSO behavior, for example you could deploy a new web application and invoke the SSOAgent MBean addPartnerApplication operation to configure it as a JOSSO partner application without having to stop the server. The new application will be automatically protected by the SSO and the application definition will be automatically stored in the josso-agent-config.xml file.

Let's take a look at JOSSO MBeans using MC4J :

The following image shows SSOSessionManager MBean attributes and operations :

This image shows the maxSessionsPerUser attribute properties. We can see the attribute name, type, description, editable flag and current value. Because this attribute is marked as 'Editable' its values can be updated. In this case, with MC4J we just modify the value displayed in the window.

Monitor and manage the Gateway

The SSOGateway MBean provides access to basic SSO information and operations. Through this MBean you can verify JOSSO version, the total number of open sessions and perform basic session management activities such as listing, verifying and invalidating. This is the set of attributes and operations provided by the SSOGateway MBean :

• sessionCount (attribute) : Total number of open sessions
• name (attribute) : Product name
• fullName (attribute) : Product full name
• version (attribute) : Product version
• listSessions (operation) : List all SSO sessions
• listUserSessions (operation) : Lists all SSO sessions related to a user
• invalidateUserSessions (operation) : Invalidate all open SSO sessions related to the given user
• invalidateAll (operation) : Invalidate all open SSO sessions
• invalidate (opertaion) : Invalidate SSO session whose id is specified
• checkValidSessions (operatino) : Force a check in order to detect expired SSO sessions
• userExists (operation) : Validates that the received username matches an existing user

More specific attributes and operations can be obtained by accessing the MBeans exposing different JOSSO components.

JOSSO provides statistical information about the SSO Gateway activity. You can monitor the total number of open sessions, the number of authorizations processed since server startup, the authorization failures count and other metrics.

This information is available through several MBeans such as the SSOGateway MBean and specific MBeans like the SSOSessionManager MBean.

When using MC4J, JOSSO Dashboards can be used for obtaining different views of the Gateway activity . Take a look at JOSSO Screen shots for details.

JOSSO exposes most component configuration properties as MBean attribute sets. When browsing these attributes using your preferred JMX console, you can select and modify them for changing for instance the hast algorithm or encoding used for validating user credentials.

Managing SSO Sessions

Basic SSO session management can be achieved through the SSOSessionManager MBean. Bellow is the list of operations that allows you to obtain, invalidate and verify SSO sessions :

• getUserSessions : Lists all SSO sessions related to a given user.
• invalidateAll : Invalidate all open SSO sessions
• invalidate : Invalidate SSO session for the supplied session identifier
• checkValidSessions : Force a check in order to detect expired SSO sessions

Monitor and manage the Agent

JOSSO SSO Agent provides several MBeans that allows you to monitor agent activity, view and modify its configuration and partner applications.

Statistical information provided by the agent includes : total requests processed by the agent, total request process error count, SOAP requests sent to gateway managers and agent cache hits. If you're using MC4J, you can use Agent Statistics dashboard to view this information.

Managing partner applications

JOSSO Agent MBean provides operations to manage partner application settings by adding, removing and listing configured SSO applications. This is useful when a new web application has to be deployed without stopping the server. The addPartnerApplication operation could be invoked before the new deploy, leaving the web context automatically protected by JOSSO. All changes made to agent settings will be updated accordingly in JOSSO configuration files.

This is the list of operations provided by the SSOAgent MBean used to manage partner applications :

• addPartnerApp : Adds a new partner application to be handled by this agent.
• removePartnerApp : Removes a partner application from being handled by this agent.
• listPartnerApps : Lists all configured partner applications.

For Developers

JOSSO uses Apache Jakarta Commons Modeler to transparently expose JOSSO components as MBeans. If you want to use your own components just add or modify the mbeans-descriptor.xml for your component class. Take a look at existing descriptors or refer to commons-modeler for details.

Comments

Care to comment on this How-To? Help keep this document relevant by passing along any constructive feedback to the josso-docs