Using security

If you are using a credential vault with your WebSphere® Portal, you can configure your HATS portlets to work with the credential vault. HATS provides a Web Express Logon plug-in called WebSphere® Portal Credential Vault Credential Mapper. This plug-in appears in the Add Credential Mapper plug-in window only for a portlet project. This plug-in retrieves a passive user-password credential from a vault slot.

The following classes are provided to aid the access to the Portal Credential Vault for standard portlets.

com.ibm.hats.portlet.cv.CredentialVaultHelper
com.ibm.hats.portlet.cv.UserPasswordCredential

The CredentialVaultHelper class has the following public methods. Note that the getInstance() method returns a unique instance of CredentialVaultHelper.

public static CredentialVaultHelper getInstance();
public static String generateSlotName(String vaultId,String hostDestination,String hostAppId);
public String getSlotId(PortletRequest portletRequest, String slotName, int slotType);
public void setCredential(String slotId,UserPasswordCredential credential,PortletRequest portletRequest);
public UserPasswordCredential getCredential(String slotId,PortletRequest portletRequest);

The UserPasswordCredential class has the following public methods.

public UserPasswordCredential();
public UserPasswordCredential(String user,char[] password);
public void setUser(String user);
public void setPassword(char[] password);
public void setPassword(String password);
public String getUser();
public String getPassword();

Refer to the HATS API References (Javadoc) in the HATS documentation at https://www.ibm.com/docs/en/hats/9.7.0?topic=hats-api-references-javadoc for detailed information about the com.ibm.hats.portlet.cv.CredentialVaultHelper and com.ibm.hats.portlet.cv.UserPasswordCredential classes.

You are responsible for creating and populating the vault slot for your users. The Web Express Logon plug-in can be used directly with credentials created using the setCredential() method of the com.ibm.hats.portlet.cv.CredentialVaultHelper class, because it observes the same naming convention for the slots. The vault slot name can be generated using the generateSlotName() method of the com.ibm.hats.portlet.cv.CredentialVaultHelper class, where you pass in the plug-in parameter SLOT_ID, the host name, and the application name (use null if the application name is not applicable, for example, when connecting to an IBM® i server). Note that the generated slot name is the SLOT_ID concatenated using spaces with the host name, then the application name. The three elements of the slot name are encoded to replace spaces with underscores. The actual vault slot ID can then be retrieved using the getSlotId() method of the com.ibm.hats.portlet.cv.CredentialVaultHelper class, where you pass in the PortletRequest, the slot name, and the SLOT_TYPE. Note that if the SLOT_TYPE is 2 or 3, the slot ID is equal to the slot name.

You can populate the vault slot with credentials that are specified in your business logic or retrieved from another source. If you want to use the Portal user ID, you can retrieve it using the WebSphere® Portal Network Security plug-in. This plug-in appears in the Add Network Security plug-in window only for a portlet project.

As described in Creating plug-ins for Web Express Logon, Web Express Logon uses two types of plug-ins, Network Security plug-ins and Credential Mapper plug-ins. Any of the Network Security plug-ins that are supplied with HATS can be used in a HATS portlet. Plug-in combinations lists some possible combinations of plug-ins you can use in your portlet:

Table 1. Plug-in combinations
Network Security plug-in	Credential Mapper plug-in
WebSphere® Portal NS plug-in	Any supplied or custom CM plug-in or WebSphere® Portal Credential Vault CM plug-in
None	WebSphere® Portal Credential Vault CM plug-in
Custom NS plug-in	Custom CM plug-in

The following steps are an example of how you can add Web Express Logon capability to your portlet. Add this logic to the Start event for your HATS portlet. When a user opens the portlet, check a global variable to determine whether the user’s host credentials have already been supplied.

If the host credentials have already been supplied, show the user the first screen to be displayed after authentication. This might be the screen that appears at the end of the Web Express Logon logon macro.
If the host credentials have not already been supplied, use the getCredential() method of the com.ibm.hats.portlet.cv.CredentialVaultHelper class to request the user’s credentials from the vault.
1. If the credentials are received successfully (the method does not return null), do the following:
  1. Set the global variable to show that the user’s host credentials have been supplied.
  2. Run the Web Express Logon logon macro.
2. If getCredential() returns null, do the following:
  1. Present a sign-on screen to request the user’s information. This can be a transformed host screen or an HTML page you have created for this purpose.
  2. Store the input in global variables and add it to the vault.