ShowTable of Contents
Understanding the Lotus Workforce Management Authentication Framework, A technical deep dive by Dr. Esmond Walshe. This paper provides a detailed description of the Lotus Workforce Management authentication framework. This paper was written by Dr. Esmond Walshe, who is a Software Engineer at IBM and has worked on multiple projects including IBM Lotus Workforce Management and the IBM Industry Templates for WebSphere Portal.
Performing single sign on between your IBM® WebSphere® Portal based ‘HR’ application and your backend data storage system is a necessary component of a self service solution. The IBM Lotus® Workforce Management 6.1 authentication framework can be used to perform this functionality. It currently facilitates single sign-on between your WebSphere Portal application and a SAP backend storage system. However, to use this solution effectively it is necessary to have an understanding of each component and how they interact with one another and with the software stack to facilitate single sign-on. This paper will describe in detail the different components of the Lotus Workforce Management authentication framework. It will also detail how they integrate with WebSphere Portal, WebSphere Portlet Factory and a SAP backend data storage system to seamlessly provide a single sign on solution.
Glossary of terms
JNDI: Java™ Naming and Directory Interface
JVM: Java Virtual Machine
PUMA: Portal User Management Architecture
SPI: System programming interface
You have already built or are in the process of building an hr application using the Lotus Workforce Management 6.1 builders and wish to include the Lotus Workforce Management authentication framework to perform single sign on between WebSphere Portal and SAP. Before adding authentication framework components to your application, follow the information on setting up and configuring the Lotus Workforce Management authentication framework in the Lotus Workforce Management 6.1 information centre. This paper gives a detailed outline of how the framework works and does not go into detail on its configuration.
One of the main premises behind the self service architecture is the ability for an employee/manager to seamlessly update details across applications using a single user interface. To facilitate interaction with such applications a single sign on system is devised to ensure that the user need not be aware of the use of multiple backend applications. The user experience is of one single user interface. The Lotus Workforce Management authentication framework provides a single sign on framework to allow WebSphere Portal to connect to multiple backend systems. The current implementation facilitates single sign-on between WebSphere Portal and a SAP back end system. It currently supports username-password authentication, but can be extended to use other forms of authentication and a different credential store .
In this document the different components of the Lotus Workforce Management architecture will be outlined. You will learn how these components interact together to produce a single sign on solution. Information on the mechanisms used to integrate the framework with WebSphere Portlet Factory at design time is supplied. Also it is shown how to ensure the framework is picked up at runtime by WebSphere Portal applications. In addition some of the design decisions for configuring the application are provided.
The Lotus Workforce Management authentication framework provides a flexible extensible approach to performing single sign on between WebSphere Portal and a SAP back end system. It acts as a broker service between your application, the credential store and the SAP backend. When a request for a connection to the SAP system is passed to the broker service, it in turn retrieves the users SAP credentials from the credential store and creates a connection to the data store. A JCO client wrapped in a generic connection client is then returned to the calling method. Wrapping the JCO client in this manner allows for different client connections to be passed, allowing support for other data stores to be provided in the future.
The current implementation uses a username-password form of authentication module that retrieves user credential information stored in the WebSphere Portal credential vault. Both n-to-1 (many portal users using a single SAP account) and 1-to-1 (many WebSphere Portal user accounts with each mapped to their own SAP account) credential scenarios are supported. More information on these scenarios can be found in a later section of this document.
The Eclipse extension point framework is used to allow for different authentication modules to be plugged into the system. This allows additional authentication methods to be seamlessly added. For further reading on the extension point approach see the WebSphere Portal Information centre .
Figure 1 shows a UML diagram detailing the different components of the Lotus Workforce Management authentication framework.
Figure 1. UML diagram
Figure 2 is a diagram showing how the Lotus Workforce Management authentication framework interacts with the software stack. E.g. its interaction points with WebSphere Portal, the runtime self service application and the SAP backend storage system.
Figure 2. Diagram of the authentication framework in the software stack
The framework is structured in the following manner. The lwm.security.service is the central access point for the Lotus Workforce Management framework. It functions as the broker between any calling components such as the administration portlet or the custom JCO provider used by WebSphere Portlet Factory generated code to invoke the Lotus Workforce Management authentication framework. This broker service handles the look up of the current settings (stored in cosnaming variables and handles interaction with the chosen extension point class.
The extension point class, currently ‘com.ibm.lwm.security.PasswordAuthImpl.class’ performs interactions with the credential store, in this case the WebSphere Portal credential vault and initiates connections with the SAP backend. All required settings are passed into the extension point class methods from the broker service. The broker retrieves these settings from the cos naming variables detailed in the Lotus Workforce Management information centre. These include sap connection details and the type of credential mapping to use. That is, all settings apart from the user login credentials which are retrieved from the credential vault. Once a connection to sap is established, a Jco.Client object wrapped in a GenericConnection object is returned to the controlling program, e.g. the Custom JCO provider, Lotus Workforce ManagementCredential builder or the Administration portlet. In general, when used with WebSphere Portlet Factory, the developers do not need to work with this object directly, for it is handled by the SAP feature set.
Components of the Lotus Workforce Management authentication framework
The following list describes the components of the authentication framework:
WebSphere Portlet Factory builders:
The Lotus Workforce ManagementCredential and Lotus Workforce Management.base builders
COS naming variables:
used to store configuration information for the framework e.g. sap connection information etc.
Custom JCO provider:
a JCO provider class to be used at runtime by WebSphere Portlet Factory generated code to access the framework
The Lotus Workforce Management portlet service which acts as a broker to facilitate the connection between the underlying authentication framework and either the administration portlet or the custom JCO provider.
Configuration tool for changing extension points used by the application and for setting system wide credentials, see section on n-to-1 mapping.
Implementation classes that facilitate retrieving the Jco.client connection from the SAPJCO classes. It also invokes code to retrieve credential information for the current portal user to access the back end system.
There are two different types of authentication scenario supported by the Lotus Workforce Management authentication framework. 1-to-1 mapping allows for each user to have their own SAP account. The second type is n-to-1 where there are many WebSphere Portal users all using a single SAP account. There are differences in how each scenario is handled by the framework. That is, both types of credential are stored in the credential vault; however the difference lies in how they are stored and updated by components of the Lotus Workforce Management authentication framework.
To enable the authentication framework to store and read credentials in the credential vault, the type of credential mapping scenario to be used and the resource string information necessary to asingle sign-onciate the correct credential vault slot with the relevant backend system must be set in the Lotus Workforce Management related cos naming variables.
For n-to-1 mapping a system wide credential is used to share the credential information across users. This information cannot be updated by users that are not members of the ‘WebSphere Portals’ ‘wpsadmins’ user group. This is to prevent users changing the credentials without the permission of an administrator. Instead, this must be set by an administrator through the authentication framework administration portlet, or through the WebSphere Portal integrated administration console. Alternatively this information can be set using an XmlAccess script. See the Lotus Workforce Management information centre for more details on how such credentials can be set.
When retrieving credentials from the vault, the Lotus Workforce Management authentication framework credential mapping code uses the ‘resourceName’ of the slot in the credential vault to perform the lookup. Therefore, for Lotus Workforce Management to be able to access the users’ credentials, the resource name of the system wide credential slot must be stored in the cosnaming variables. See the Lotus Workforce Management information centre for details on how to do this (3). The format of the resourceName string and the restrictions placed on its construction are also detailed in the Information centre.
The main advantage of using the Lotus Workforce Management authentication framework is the facility to allow the management of one to one account asingle sign-onciations between a portal user and their SAP account. Each user having their own SAP account allows for greater transparency as it is easier to track the changes that were made by a specific user in the data store.
With 1-to-1 credential mapping, users do not need to rely on an administrator to create credential information for them in the credential vault. Instead the Lotus Workforce ManagementCredential builder performs this task for the user. The Lotus Workforce ManagementCredential builder code checks if there is credential information in the vault for the current user, if this doesn’t exist, then the builder will pose a challenge to the user to enter their credential information and then will store it in a newly created slot in the vault. The resource name of the credential slot is also used for storing and retrieving credentials in this scenario. As with n-to-1 resource names there are some restrictions on the resourceName that can be used, see the Lotus Workforce Management information centre for more details.
SAP employee number
Although this is a general Lotus Workforce Management issue and not one unique to the authentication framework, there needs to be a mechanism to asingle sign-onciate records in SAP with the current WebSphere Portal user. To do this the SAP employee number is used. The Lotus Workforce Management.base builder looks up the employeeNumber for the current user in the WebSphere profile using the PUMA SPI. Therefore a mapping between the employeeNumber attribute and the users SAP employee number must be created before the user can successfully access their records in SAP. To do this you can edit the WebSphere Portal user profile directly. The employee number attribute isn’t displayed by default when the user goes to edit their profile so an administrator would need to ensure that this attribute is shown. However, if you do not wish the employee to be able to edit this information, it can also be submitted to portal through an xmlAccess script. A sample xmlAccess script demonstrating how this can be done is supplied with Lotus Workforce Management 6.1, see the information centre for more details.
When building an application using the Lotus Workforce Management WebSphere Portlet Factory builders, the employee number can be read from the portal user profile using the Lotus Workforce Management.base builder. This builder needs to be added to any models that require SAP connections otherwise records from the user cannot be retrieved. Lotus Workforce Management.base uses the PUMA SPI to look up the employee number for the current user and makes it available to other components accessing SAP.
As the Lotus Workforce Management authentication framework was built as a stand alone component outside of WebSphere Portlet Factory, a mechanism to store configuration details was required. That is instead of providing this information in the properties files supplied in a WebSphere Portlet Factory project. Cos naming namespace binding variables were chosen to store the relevant data. The facility to create such variables is provided as part of WebSphere application server on which Portal operates. The data stored in those variables required by the authentication framework includes SAP connection information plus some additional fields necessary to allow smooth interaction with the credential vault, e.g. the resource name of the slot to use for credential storage, or the type of credential storage scenario in force.
Before the Lotus Workforce Management authentication framework can be used by an application, it is important that these variables are created and configured with correct values. This can be done through the WebSphere integrated administration console of the Application server being used by portal or through a configuration script passed to wsadmin.bat. A jython script to perform this task is provided as part of the Lotus Workforce Management 6.1 release. However this script must be edited to reflect the settings of the new system. For more information on how to edit the script, or details of the expected values for the cos naming variables, see the Lotus Workforce Management 6.1 information centre.
As previously mentioned, the Lotus Workforce Management authentication framework was designed as a stand alone component inside of WebSphere Portal. The primary way to interface with the framework is through the portlet service. Both the custom JCO provider (used to interface with WebSphere Portlet Factory SAP feature set) and the administration console connect to this service. It acts as a broker between the extension point class, the credential vault and SAP data store.
To ensure that WebSphere Portal is aware of the lwmSecurityService (portlet service) it must be registered as a custom property of the 'WP PortletServiceRegistryService' resource environment provider. A wsadmin jython script to perform this task is supplied with Lotus Workforce Management 6.1.
Integration with WebSphere Portlet Factory
As the portlet service component of the authentication framework exists outside of the WebSphere Portlet Factory project, a mechanism to allow WebSphere Portlet Factory based components use this functionality was necessary. In this section the different components that are used by WebSphere Portlet Factory to interact with the Lotus Workforce Management authentication framework are discussed.
The Lotus Workforce Management Credential Builder
The Lotus Workforce ManagementCredential builder is necessary to ensure that valid credentials are stored for a user in the credential store. When invoked it first checks to see if there are already credentials in the vault for the current user. To do this it calls on functionality provided in the LWMSecurityService i.e. broker service to retrieve credentials. As it interacts purely with the broker and not the extension point class directly, different extension points can be used without affecting the functionality of the Lotus Workforce ManagementCredential builder. If credentials do not exist, then a challenge is posed to the user to fill out the correct credential information. Once credentials exist, they are then tested against the SAP backend system to ensure that they are valid. If this is the case, credentials are then stored in the vault. Otherwise a challenge is again posed to the user.
The current challenge is an html page requesting the user to enter a user name and password for access to SAP. However, it is possible to extend the builder and substitute in a different form of credential challenge such as a request for a SAP logon ticket etc. It can also be extended to retrieve the information from another system, however this is not part of the default functionality supplied by the Lotus Workforce Management authentication framework and would need to be provided by the application developer.
There is also no need for the Lotus Workforce ManagementCredential builder to be added to each WebSphere Portlet Factory model of the application. As a connection to both SAP and interaction with the credential vault is required each time the code is run, this would be quite expensive on resources. Instead it is recommended that the Lotus Workforce ManagementCredential builder is only added to one model in the application. This could be the model for the main access portlet of the application or an additional model that the user accesses only once to ensure that credentials have been validated. In this way, user credentials will be checked when the user accesses the application before any connection to SAP is made.
Custom JCO provider
The final piece of the jigsaw requires a way to overwrite the default WebSphere Portlet Factory SAP feature set to employ the Lotus Workforce ManagementSecurityService to retrieve the jco.client object instead of its own implementation. Otherwise the application will continue to look in the WebSphere WebSphere Portlet Factory ‘default_sap_server.properties’ file for SAP connection details instead of invoking the Lotus Workforce ManagementSecurityService. To achieve this, a customized JCO provider class is supplied as part of Lotus Workforce Management 6.1. The relevant code can be found in the lwm.security.sap.jar file that must be placed in the /WebContent/WEB-INF/work/lib directory of your WebSphere Portlet Factory project. This is to ensure that the class is loaded at the correct time.
As well as including the jar file in your project you will need to tell WebSphere Portlet Factory that it should deviate from its default behavior and use the new class. However, it is required that you only do this for connections at runtime and use the default class at design time. As the custom JCO provider needs access to a portlet service (the Lotus Workforce ManagementSecurityService) which is not available to WebSphere Portlet Factory projects at design time. You will need to ensure that the class is only overwritten at runtime. For details on how to override the JCO class, see the Lotus Workforce management Information centre .
Usage path example
The following is an example of the program flow of information for the authentication framework to impress on the user an understanding of how it processes a single sign-on request. Figure 3 shows a flow chart demonstrating this information.
Figure 3. Flow chart for processing single sign-on
The first time the user accesses the landing page, or front page of the application the Lotus Workforce ManagementCredential builder should be called into action to test if there are credentials available for the user in the credential vault. If these already exist, they are tested against the sap system to ensure that the credentials are correct. If this is the case, the sap connection is closed and the user may continue with their tasks. However if the credentials do not exist, or are found to be no longer valid a challenge is posed to the user requesting that they re-submit their new credential information. This is useful when using 1-to-1 mapping for each user has a separate SAP account. However, if there is n-to-1 mapping e.g. each user is using the same SAP account then this does not make so much sense, because the users are not able to edit a system wide credential, instead this must be done by someone with administration rights through either the Lotus Workforce Management authentication Framework administration portlet or through the integrated administration console of WebSphere Portal.
Code generated by the Lotus Workforce ManagementCredential builder uses the Lotus Workforce ManagementSecurityService to interact with the extension point class to retrieve and to set credentials in a similar manner as would be done using WebSphere Portlet Factory and the custom JCO provider, see below for more details. When setting new credential information the details are stored by the credential builder and retrieved by the extension point class and are tested against SAP. If the test connection was successful the credential information is submitted to the credential vault.
When a request is made for access to a SAP connection through WebSphere Portlet Factory, the SAP feature set will first check the bowstreet.sap.session.pool.clientProviderClass property to see if it has been overwritten in the override.properties file. This property points to the JCO provider class to use.
Once it is established that the Lotus Workforce Management custom JCO provider is to be used, the provider class is loaded and a request is made to retrieve a sap jco.client object.
When the JCO provider class is loaded, it retrieves a reference to the Lotus Workforce ManagementSecurityService. A call is made on initialization of the Lotus Workforce ManagementSecurityService to retrieve the settings in the Lotus Workforce Management cos naming variables. It is important to note that there is only one version of the Lotus Workforce ManagementSecurityService object running in the JVM at any given time. It is shared between many calls to SAP. As it is only created once, the overheads are reduced because the creation of the Lotus Workforce ManagementSecurityService is done using a JNDI lookup that can be expensive on resources if it is performed for each SAP access request. However on the down side, the cosnaming variables are only read on start up of the service therefore to refresh their details would require a server restart to be sure that the new settings are reflected in the system. That is if you make changes through the integrated administration console of WebSphere Portal. Any changes in the cos Naming variables made through the Lotus Workforce Management authentication administration portlet are propagated into the system settings directly.
The next step is for the broker to contact the extension point object to generate the connection to SAP. It first checks that there are credentials in the credential vault for the current user. These credentials are then used to create a connection to SAP. If the connection is successful, the jco.client object is passed back to the Lotus Workforce ManagementSecurityService and is propagated back up the tree to be used by the WebSphere Portlet factory SAP feature set.
The Lotus Workforce Management Authentication Framework is a powerful, flexible and extensible tool to facilitate single sign on between WebSphere Portal and a SAP data storage system. This paper described the different components of the solution and provided some guidance on how to integrate these components into your application.
1. IBM Lotus Workforce Management Version 6.1 Information Center at: http://publib.boulder.ibm.com/infocenter/lwm/v6r1/index.jspWebSphere Portal Information Centre
2. WebSphere Portal 6.1 Information Center at: http://publib.boulder.ibm.com/infocenter/wpdoc/v6r1/index.jsp