Portlet authentication

For resources protected by the portal, WebSphere Portal uses CORBA credentials and an encrypted LTPA cookie to authenticate users. However, for backend systems that require their own authentication, portlets need to provide some form of authentication to access these remote applications.

In order to provide a single sign-on user experience, portlets must be able to store and retrieve user credentials for their particular associated application and use those credentials to log in on behalf of the user. WebSphere Portal supports the use of a credential vault where users and administrators can safely store credentials for authentication. Portlets written to extract the user's credentials from the vault can hide the login challenge from the user.

Credential vault organization

Vault segments

A vault segment is flagged to be either administrator-managed or user-managed. While portlets (on behalf of a portal user) can set and retrieve credentials in both types of segments, they are permitted to create vault slots only in user-managed vault segments.

Vault slots

The credential vault provided by WebSphere Portal distinguishes between four different types of vault slots:

Credential objects

The CredentialVault PortletService returns credentials in form of credential objects. WebSphere Portal differentiates between passive and active credential objects.

The second case allows portlets to trigger authentication to remote servers using standard mechanisms such as basic authentication, HTTP form-based authentication, or POP3 authentication, without even knowing the credential secrets. They can ask the portal to authenticate on their behalf and then use already authenticated connections. From a security point of view the portlets never get in touch with the credential secrets and thus there is no risk a portlet could violate any security rules like, for example, storing the secret on the portlet session. While there might not always be an appropriate active credential class available, it is the preferred type of credential object to use.

All credential types that are available within the portal are registered in a credential type registry. WebSphere Portal provides a small set of credential types, but additional credential objects can easily be registered in this registry.

Passive Credential Objects:

SimplePassive: This credential object stores secrets in form of serializable Java objects. As the vault service does currently not support binary large object (BLOB) secrets, this is intended for future use only.
UserPasswordPassive: Credential object that stores secrets in the form of userid/password pairs.
JaasSubjectPassive: Credential object that stores secrets in form of javax.security.auth.Subject objects. Again, this kind of secret cannot currently be stored by the vault service.

Active Credential Objects:

HttpBasicAuth: This credential object stores userid/password secrets and supports HTTP Basic Authentication.
HttpFormBasedAuth: This credential object stores userid/password secrets and supports HTTP Form-Based Authentication.
JavaMail: A credential object that stores userid/password pairs and leverages the authentication functionality of the javax.mail API.
LtpaToken: A credential object for authenticating with a backend system that is within the same WebSphere Application Server single sign-on domain as the portal.
SiteMinderToken: A credential object for authenticating with a backend system that is within the same SiteMinder single sign-on domain as the portal. This credential should be used when SiteMinder is used as an authentication proxy for the portal.
WebSealToken: A credential object for authenticating with a backend system that is within the same WebSEAL single sign-on domain as the portal. This credential should be used when a WebSEAL authentication proxy is used by the portal.

Storing credential objects in the PortletSession

Credential objects do not implement java.io.Serializable - they cannot simply be stored in the PortletSession. This is for security reasons. Because the credential classes store the actual credential secret as one of their private attributes, the secret could be found by anyone who has access to the appserver session database.

However, you can store a credential object in the PortletSession as long as you ensure sure that it is not serialized in a cluster setup. One way of doing this would be to define a credential container class that stores the actual credential object as a transient member. This container object can then be stored in the PortletSession without any problems, you only have to make sure to check whether the credential object got lost during serialization and in this case retrieve it from the vault again.

Credential vault usage scenarios

Portlets that need a credential to complete their service have two options:

Use an existing slot that has been defined by the portal administrator in an administrator-managed vault segment.
Create a slot in the user-managed vault segment.

The option you choose depends on how the portlet will be used. Generally, the best solution hides the technical details of the credential vault from users. The following are some example scenarios for the use of slots.

Intranet Lotus Notes mail portlet

A company has an intranet employee portal. Each portal user has a Lotus Notes mail server account and a Lotus Notes mail portlet will be deployed and pre-configured on one of the employee's default portal pages.

Design solution:

The Notes mail portlet needs to store the user's Notes password. As most users will actually use this portlet, the administrator needs to create a "Lotus Notes Credential Slot" for it. Using the portlet's configure mode, the administrator sets the vault slot ID for all concrete portlet instances. The portlet allows users to set their personal Notes password in edit mode. The portlet can store each user's password in the credential vault.

Stock of inventory portlet

A company's buying department runs a portal that integrates different legacy applications. One of these applications is a mainframe ordering application that directly connects to the systems of the suppliers. Several employees use the ordering portlet. However, the mainframe application is secured by a single system ID; it doesn't support several user accounts.

Design solution:

The ordering portlet needs to access the ordering application under the system ID. The administrator configures the vault slot ID during portlet deployment. The portal administrator therefore creates a vault slot in an administrator-managed vault segment and marks it as a system credential. The administrator uses the Credential vault portlet to store the ordering system ID and password in this slot. The buying department's employees do not have to be concerned with credentials at all.

Internet Mail federating POP3 portlet

An Internet community portal offers, among other features, a mail-federating portlet that can be used by a portal user to collect mail from a number of POP3 mail accounts.

Design solution:

The mail federating portlet is just another feature of the community portal and thus is likely to be used only by some of the portal users. Furthermore, it is not clear from the outset how many mail accounts a user wants to federate. Therefore, it does not make sense for the portal administrator to create a vault slot for this portlet. Instead, the portlet provides users with a comfortable configuration in edit mode. Users can add as many POP3 mailboxes as necessary. The portlet creates a vault slot for each of the user's mailboxes in the user-managed vault segment.

Theoretically, a user could configure two instances of the portlet on a page, one for business accounts and one for private mail accounts. Therefore, and because it most likely doesn't make sense to share the user's mail credentials with other portlets, the portlet created vault slots are better marked as portlet private.

Change the credential vault encryption

WebSphere Portal supports different vault adapters for the storage and retrieval of credentials. The default vault adapater stores the credential passwords in the database. You can customize the encryption for the default vault.

Write a class that implements the EncryptionExit interface:

package com.ibm.wps.sso.vaultservice;

public interface EncryptionExit 
{
 
   /**
    * Encrypt the password
    *
    * @param password Unencrypted Password
    * @return Encrypted password as a char[]
    */

   public char[] encryptPassword(char[] password);

   /**
    * Decrypt the password
    *
    * @param password Encrypted Password
    * @return Unencrypted Password as a char[]
    */

   public char[] decryptPassword(char[] password);
}

Deploy the new class to your portal.
- Create a jar file with the new encryption exit class and place it under...
  wp_root/shared/app
- Use the WebSphere Application Server Administrative Console and navigate to...
  Environment -> Shared Libraries -> WPSlib
  
  You might have to start the server1 appserver to access the admin console.
- Enter the location of the new jar file under Classpath .
Set the name of your adapter file properties in the file
wp_root/shared/app/config/services/VaultService.properties

...to...
default.config=defaultvault.properties

Add the file...
wp_root/shared/app/defaultvault.properties

...with the following contents:
encryptionExit=com.yourcompany.YourEncryptionExit
Restart your WebSphere Portal.