ShowTable of Contents
Introduction
The IBM® Connections portlets render social data from IBM Connections in the WebSphere Portal environment, and IBM strategically promotes the integration of Connections with WebSphere Portal using IBM Connections portlets. Customers and Business Partners can download the IBM Connections 3.x Portlets for WebSphere Portal from the
Business Solution Catalog and customize them per their requirements.
The portlet application bundles portlets for nearly all services provided by the Connections server (Activities, Blogs, Bookmarks, Forums, Profiles, Wikis, and Tag Cloud), most of which have two flavors of portlets:
The details portlet, which provides full-fledged read, write, and edit capabilities and is used to perform all major functionalities offered by the service.
There are also the summary portlets, which provide a read-only snapshot of the service and redirect the user to the details portlets for any write, edit, or advanced functions.
Connections portlets consume the Representational State Transfer (REST) services from the Connections server for integration, and they use IBM Web Experience Factory (WEF) as a development environment.
This article describes the authentication mechanisms used with the Connections server that are supported by portlets. The article not only describes the use case of Connections portlets but also can serve as a reusable asset for technical developers for other similar implementation scenarios.
We begin with how SSO is used by the portlets with WebSphere Portal Ajax Proxy and also cover basic authentication and its use with AJAX proxy in WebSphere Portal. Since the Connections portlets use WEF as the tool for portlet application development, we also discuss implementation methods using WEF for both authentication mechanisms.
SSO with WebSphere Portal Ajax proxy
The Connections portlets interact with the Connections server by invoking REST APIs exposed by the latter. Since the portlets interact with personalized data on the Connections server, the REST calls have authentication information, as part of the request header, that needs to be provided by the portlets.
In this section we explain how to implement Single Sign-on (SSO) configured between WebSphere Portal and the Connections server, as well as how to use third-party authentication systems for more advanced configurations.
Configuring SSO
Once SSO is configured between WebSphere Portal and the Connections server and a user logs in to WebSphere Portal, the user is also authenticated to the Connections server; hence, the user is able to view personalized data from the Connections server within WebSphere Portal.
For SSO to work, both WebSphere Portal and the Connections server need to share a common LDAP. For more information on how to configure this, refer to the Help topic,
“Enabling single sign-on for the portlets using a stand-alone LDAP server."
To render Connections social data within the portlets, the portlet application code calls REST APIs exposed by the Connections server, using the REST Service Call Builder from WEF. The Builder has various inputs, the primary of which are the REST URL, HTTP method type, URL parameters, request body, request body schema, HTTP cookies, etc. In the Builder input for HTTP Cookies, we can mention the various cookies that need to be used by the builder.
Prior to the 3.0.1 release, the Connections portlets only supported SSO using LTPA tokens, which they did by providing the cookie name and value in the Rest Service builder under the HTTP Cookies section (see figure 1).
Figure 1. HTTP Cookies section of Rest Service Builder
This approach restricted the portlets from passing other third-party authentication cookies used by third authentication mechanisms like TAM and SiteMinder dynamically as the cookie name was not configurable.
To support all the third-party authentication cookies that are supported both by WebSphere Portal and Connections, it makes sense to provide them as part of the configuration that Portal Administrators can set up according to the authentication mechanism used.
To achieve this, we found that Portal Ajax proxy (application specific) was the best fit as it has an XML configuration file available that lets Administrators configure the cookie names that can be forwarded.
WebSphere Portal provides two types of Ajax Proxy mechanisms:
- Global proxy. This proxy setting applies at the Portal level and is applicable for every portlet on WebSphere Portal.
- Application-specific proxy. This is specifically designed for a particular portlet application and takes precedence over the Global proxy.
The Application-specific proxy mechanism was chosen for Connections portlets. Connections 3.0.1.1 portlets have the application-specific proxy defined in the proxy-config.xml file in the portlet .war file under the WEBINF folder. This proxy has the following settings:
- All the default names of the cookies that are used by the third-party authentication mechanisms and are supported by Portal and Connections.
- Supports both SSO and Basic authentication.
- The placeholder for the Connections server URL that can be provided in the Resource Environment provider (REP).
Figure 2 shows a code snippet of the proxy-config.xml file.
Figure 2. Code snippet of proxy-config.xml file
The proxy URL in the proxy-config.xml file is defined in the WebSphere Application Server admin console under Resource environment providers --- WP ConfigService --- Custom properties. The property named must be specified as:
Name: wp.proxy.config.urlreplacement.ibm_connections_policy.default.connections.server.https
and the value as the Connections server URL; for example,
https://www.connections.com/*. For more details on this mechanism, refer to Ajax Proxy documentation of WebSphere Portal.
The cookies provided in proxy-config.xml are the default cookies used by TAM (JSESSIONID), SiteMinder (SMSESSION,JSESSIONID), WebSEAL (PD-H-SESSION-ID, PD-S-SESSION-ID), and the regular LTPA cookies (LTPA, LTPA2, LtpaToken, LtpaToken2).
Before the WebSphere Portal Ajax proxy was introduced, any static resource like images was fetched to the client browser by providing the direct URL (
https:www.connections.com/profilephoto.do?userid=) of the resource of the Connections server.
Ajax-proxy-enabled portlets fetch resources from the Connections Server through the proxy rather than fetching them directly. To achieve this, an application-specific proxy URL is used to point to the resource. Here is the description of the URL that can be used for any static resource:
for example:
To fetch a resource on an anonymous page, "proxy" is used and is replaced by "myproxy" in cases where the page is authenticated.
Developing using WEF
The REST Service Call Builder in WEF doesn't use a proxy to connect to the REST service, so we’ve extended the REST Service Call Builder to make the REST call, using the Portal Ajax Proxy object.
A Java class, such as LCURLConnectionFactory, is written to locate and return the Portal Ajax Proxy object. This class implements the com.bowstreet.util.HttpURLConnectionFactory interface of the REST Service Call Builder.
In order for the REST Service Call Builder to use this class for connecting to the REST URL, we must add the property, wpf.httpURLConnectionFactory.class, with the value set to the name of the above class in the override.properties file, under the WEB-INF/config directory of the Web Experience Factory project, like this:
wpf.httpURLConnectionFactory.class=com.ibm.lconn.lcaccelerator.util.LCURLConnectionFactory
The LCURLConnectionFactory class overrides the createConnection and postProcessConnection methods defined in the com.bowstreet.util.HttpURLConnectionFactory interface. The overridden createConnection method is called every time a REST Service call is made to any URL through the REST Service Call Builder.
When an application-specific proxy configuration is used, the code snippet in listing 1 is used to locate the application's AJAX Proxy object.
Listing 1. Code to locate Ajax Proxy object
HttpURLConnection conn = null;
PortletAjaxProxyService _papsPortlet=null;
Context ctx = newInitialContext();
Name myjndiname = newCompositeName(PortletAjaxProxyServiceHome.JNDI_NAME);
Object obj = ctx.lookup(myjndiname);
if(obj instanceofcom.ibm.portal.resolver.proxy.service.PortletAjaxProxyServiceHome)
{
PortletAjaxProxyServiceHome papsh= (PortletAjaxProxyServiceHome)obj;
_papsPortlet= papsh.getAjaxProxyService((PortletRequest)webAppAccess.getHttpServletRequest().getAttribute(Constants.PORTLET_REQUEST),
(PortletResponse)(webAppAccess.getHttpServletRequest()).getAttribute(Constants.PORTLET_RESPONSE));
} else {
com.ibm.wps.resolver.proxy.service.PortletAjaxProxyServiceHomeImpl papsh = (com.ibm.wps.resolver.proxy.service.PortletAjaxProxyServiceHomeImpl)obj;
_papsPortlet= papsh.getAjaxProxyService((PortletRequest) webAppAccess.getHttpServletRequest().getAttribute(Constants.PORTLET_REQUEST)
, (PortletResponse) webAppAccess.getHttpServletRequest().getAttribute(Constants.PORTLET_RESPONSE));
}
conn =(HttpURLConnection)_papsPortlet.createConnection(baseURL);
If the Ajax Proxy Service object is not retrieved, that is, the application proxy config file is not available in the portlet .war file, it returns the default URL Connection object to the REST Service Call Builder:
HttpURLConnection conn = (HttpURLConnection)baseURL.openConnection();
Before returning the object to the REST call service, the available request headers should also be copied into the Connection object being returned.
Similarly, the postProcessconnection method defined in the com.bowstreet.util.HttpURLConnectionFactory interface can be overridden. This method is called every time after a REST Service call is made to any URL through the REST Service Call builder.
The purpose of this method is to do any additional processing required after the REST Service is made, and to attempt to disconnect the connection, if it is already connected. It can be used to see the logs to determine the response code, response message, and how long that request has taken to serve, etc.
Troubleshooting
- “HTTP Status 403.” This error message usually occurs when the proxy is not allowing access to the URL. Verify that the proxy is configured to allow access to the URL, and check the URL defined in the Resource environment provider in wpconfig service.
- “HTTP Status 504.” This occurs upon a timeout. You can increase the timeout value by changing the value of "socket-timeout" in the proxy-config.xml.
Basic authentication support for IBM Connections portlets
The Connections portlets aim to provide a user experience similar to that of the IBM Connections server within the Portal environment. In native IBM Connections, the user logs in only once to access all services provided by IBM Connections.
Since the portlets are individual application windows over Portal, we required a similar user experience whereby users enter their credentials for one service portlet, and all other service portlets share the credentials to show personalized data for various Connections services.
In earlier, pre-3.0.1.1 versions of Connections portlets, the user had to personalize every portlet with their credentials, which was a limitation since the user needed to put the same credentials repeatedly in every portlet.
In version 3.0.1.1, users need to enter their credentials only the first time in any of the portlets, and these credentials are used by other portlets subsequently. The WebSphere Portal Credential Vault infrastructure (described below) is used to store and retrieve the credentials for this scenario.
Using WebSphere Portal Credential Vault infrastructure
As of version 3.0.1.1, the Connections portlets offer two flavors of Credential Vault usage:
(1) Shared user slot
This enables every user to set their own credentials and see their personalized social content in the Connections portlets. A separate Credential Vault slot is created for every user, and the credentials are shared across all the Connections portlets accessed by that user.
The user must set the credentials by accessing the personalize mode of any one service portlet, after which all other service portlets retrieve the credentials stored in the shared user slot. In this way, we are able to provide a Portal user experience whereby users can access all services of IBM Connections by setting credentials for a particular service.
By default, the personalization user interfaces (for instance, the personalization form) are not enabled. To enable this feature, administrators must set the "authenticationMethod" value in the lcaccelerator.properties file to "basicAuth". The file is in "WEB-INF\lcaccelerator\properties" of the installed portlet application.
To change the credentials, simply enter the new credentials in the personalize window (see figure 3) on any portlet, and the new credentials will be applied to all the Connections portlets. To delete the credentials, simply clear the credentials and save.
Figure 3. Personalize window
(2) System slot
This enables the Portal administrator to configure a particular portlet with a credential that is valid for all users. The administrator must configure the portlet with a system slot, which is created through the Portal administration console. To use this feature, the administrator performs the following steps:
- Set the "authenticationMethod" value in the lcaccelerator.properties file to "basicAuth". The file is found in "WEB-INF\lcaccelerator\properties" of the installed portlet application.
- Create a system slot with the credentials through the Portal administration console. Details are provided in the Infocenter topic, “Enabling basic authentication.”
Thereafter, the configuration mode of the portlet would show the system slot created above, and Administrator needs to select the system slot from the drop-down menu (see figure 4). Note that, in this scenario, all portlet instances for the particular portlet would be configured for using the credentials from the system slot.
Figure 4. Select a system slot
Administrators must perform similar steps in the config window for other portlets. For example, if the Blogs portlet is configured with a particular System slot, then all Blogs portlet instances across the portal will use the same slot to render the personalized data for all users.
Also note that, in cases in which credentials are set through both the shared user slot (using personalize mode) and system slot (using configure mode), the shared user slot is given precedence over the system slot.
Developing using WEF
Connections portlets use the REST Service Call Builder to make HTTP requests to the Connections REST API for publishing and retrieving data. There are no direct Builder inputs in this Builder that reference any Credential Vault resources. To use the Portal Credential vault with the REST service Builder, we implemented a Linked Java Object (LJO) for creating and extracting passive Vault slots.
Adding Credential Vault slot to the proxy URL
We set the Credential Vault to the proxy URL by adding the parameter, hpaa.slotid, set to the value of “slotid”. After this parameter is set in the URL, the following entry is required in the proxy-config.xml file to pass the slot id for authentication:
<proxy:meta-data>
<proxy:name>forward-credentials-from-vault</proxy:name>
<proxy:value>true</proxy:value>
</proxy:meta-data>
In the absence of this metadata in the proxy config definition, the specified hpaa.slotid parameter will not be processed. In addition, basic-auth-support should also be set to "true" for the proxy policy definition of the specific Connections server in proxy-config.xml (see figure 5).
Figure 5. basic-auth-support set to "true"
To verify that the portal proxy is configured to pick the credentials from the Credential Vault slot id and use it to authenticate to an external server URL, use the test URL for the form:
We should get an authenticated response after credentials are selected from the credential slot. Note that we need to log in to WebSphere Portal with the user to whom the slot id belongs and map the security role, "AllAuthenticatedUsers", to appropriate users/groups of the application.
Obtaining the slot ID
Connections portlets supports shared user slots (per user, all resource) and System slots (all users, per resource) as described in Section 3.1 above. A shared user slot is created when a user specifies the credentials in the Personalize mode of the portlet, using Credential Vault APIs.
If the user changes the credentials, then the credential slot is updated for all the resources. If the user deletes the credentials from the Personalize mode and a slot exists for that user, then the slot is also deleted.
When a user enters the credentials from the Personalize mode and clicks the Save button, the slot for that user is searched by use of the code snippet in listing 2.
Listing 2. Code for searching for slott
Context ctx = new InitialContext();
PortletServiceHome cvsHome = (PortletServiceHome)ctx.lookup("portletservice/com.ibm.portal.portlet.service.credentialvault.CredentialVaultService");
if (cvsHome != null) {
CredentialVaultService service = (CredentialVaultService)cvsHome.getPortletService(CredentialVaultService.class);
for(Iterator it = service.getAccessibleSlots(request); it.hasNext();)
{
CredentialSlotConfig config = (CredentialSlotConfig)it.next();
if(config.getResourceName().startsWith(slotResourceName))
{
slotIdTemp = config.getSlotId();
}
}
In the above snippet the resource name for the Connections portlet is set to “lcPortlets_CredentialVaultResourceName” (though it can be changed). One resource name suffices here since the shared user slot means per user all Connections services.
If the user is entering the credentials for the first time, then no slot will be found, and the new slot is then created using code snippet in listing 3.
Listing 3. Code for creating new slot
CredentialSlotConfig slot = null;
Context ctx = new InitialContext();
PortletServiceHome cvsHome = (PortletServiceHome)ctx.lookup("portletservice/com.ibm.portal.portlet.service.credentialvault.CredentialVaultService");
if (cvsHome != null) {
CredentialVaultService service = (CredentialVaultService)cvsHome.getPortletService(CredentialVaultService.class);
ObjectID segmentID = service.getDefaultUserCredentialSegmentId();
HashMap descriptionsMap = new HashMap();
HashMap keywordsMap = new HashMap();
int secretType = CredentialVaultService.SECRET_TYPE_USERID_STRING_PASSWORD_STRING;
//boolean bActive = true;
boolean bActive = false;
boolean bPrivate = false;
//Creating slot
slot= service.createCredentialSlot(slotResourceName, segmentID,descriptionsMap,keywordsMap, secretType, bActive, bPrivate, request);
slot.getSlotId();
service.setCredentialSecretUserPassword(slot, usedId, password.toCharArray(), request);
Now, the next time a user goes into the Personalize mode and updates the credentials, the above snippet can again be used to update the credentials to a new value. However, if the user deletes the credentials now, then the slot must be deleted, using this snippet:
service.deleteCredentialSlot(slotId);
3.4.1 Working with system slots
System slots are defined for all users and all resources, so the configure mode of the portlet is best suited to selecting the system slot. We create system slots by using the Credentials Vault admin portlet, per the product documentation topic, “Enabling basic authentication.” After the slots are created, we can load them by using this snippet:
ArrayList systemSlotList = CredentialVault.getSystemSlotsName(request, vaultService);
After a user selects the system slot in configure mode and saves it, the slot id is saved in the Portlet Preferences.
Conclusion
This article covered SSO using Portal Ajax proxy, Basic authentication using Credential vault, and working with REST services with Portal Ajax proxy and credential vault in WEF, along with the usage pattern and implementation as applied to IC portlets.
Tell us what you think
Please visit this link to take a one-question survey about this article:
Resources
developerWorks IBM Connections product page:
http://www.ibm.com/developerworks/lotus/products/connections/
developerWorks IBM Web Experience Factory product page:
http://www.ibm.com/developerworks/websphere/zones/portal/portletfactory/
About the authors
Projjwal Saha is based at IBM's India Software Labs, working in the domain of Collaboration Solutions (ICS) for the past seven years. His technical expertise lies in WebSphere Portal platform and application development on WebSphere Portal using Web Experience Factory. You can reach him at projsaha@in.ibm.com.
Jyoti Rani is based at IBM's India Software Labs, working in the domain of ICS for the past 7.5 years. Her areas of expertise include WebSphere Portal, Web Experience Factory, Industry Templates for WebSphere Portal, and Lotus Mashups. You can reach her at jyotirani10@in.ibm.com.
Chitresh Sirohi is based at IBM's India Software Labs, working in the domain of ICS for the past 8.5 years. His technical expertise lies in WebSphere Portal platform and application development on WebSphere Portal using Web Experience Factory. You can reach him at Chitresh.Sirohi@in.ibm.com.