Setting up SSL 

---

Get an overview of the tasks that are required to configure SSL for IBM® WebSphere® Portal. Some of these tasks are performed on the IBM WebSphere Application Server and the Web server. The steps that refer to the WebSphere Application Server and the Web server are summarized here; you should refer to the WebSphere Application Server and the Web server documentation for detailed information. Steps that are unique to WebSphere Portal are described in detail here.

Note: This procedure might be slightly different if a front-end security proxy server such as IBM Tivoli® Access Manager WebSEAL is used. In that case, the front-end security server handles the client SSL connections. The Web server receives connections from the front-end security proxy server. Mutually authenticated SSL could be configured between the Web server and the front-end security proxy server if needed. This is highly dependent on the security requirements of each deployment.

If you plan to use a Tivoli Access Manager WebSEAL TAI with an SSL junction, perform only steps 1-3 of this procedure.

Important: If only the login process should be secure over SSL, perform the first three steps and then go to Configuring SSL only for the login process.

1. Configure the Web server to support HTTPS. This involves setting up the Web server to accept inbound connections from client browsers over SSL. Depending on the Web server you want to use, other software may have to be installed on the Web Server machine, for instance Microsoft™ Internet Information Server and Microsoft Certificate Service. The Web server must have a port defined (usually 443), and the necessary certificates and keys must be installed. Go to Securing with SSL communications for information on how to enable SSL on an IBM HTTP Server.
   
If this is a production environment, you must obtain a certificate from a certificate authority. For testing purposes, you can use IKEYMAN to generate a self-signed certificate. Refer to Certificate management using iKeyman prior to SSL for information about the IKEYMAN.

For Internet Information Server, use the Web server's resource tool kit to create SSL keys.

2. Configure the WebSphere Application Server plug-in for the Web server to forward WebSphere Portal traffic that is received over SSL to WebSphere Application Server (which will then forward the traffic to WebSphere Portal ). Refer to Configuring the Web server plug-in for Secure Sockets Layer for information on how to configure the plug-in. This topic discusses the configuration for the IBM HTTP Server; however, the Web server-related configuration in this situation is not specific to any distributed platform Web server.
3. In configurations where the Web server and WebSphere Portal reside on separate machines, requests to the Web server are rerouted to the application server. Under these circumstances, you can also configure SSL between the Web server and the application server to provide more complete security. This requires that you create additional keyfiles for the Web server plug-in and for the embedded HTTPS of WebSphere Application Server. For information on configuring SSL between the Web server and the application server, refer to the section entitled 8.7.2 Application server configuration: Web container configuration of the IBM WebSphere Application Server V7.0 Security Guide, SG24-7660-00.
   
Note: Always create a new SSL keystore and truststore for the external Web server and change the WebSphere_Portal server's secure transport channel to use the new SSL repository.

CAUTION: Do not modify the default SSL key and truststore.

4. Perform the following steps to create or modify the two required properties in the configuration services:
1. Log on to the IBM WebSphere Application Server administrative console in a standalone environment or on the Deployment Manager administrative console in a clustered environment.
2. Navigate to Resources -> Resource Environment -> Resource Environment Providers.
3. Click WP ConfigService.
4. Click Custom Properties under the Additional Properties heading.
5. Locate the redirect.login.ssl property and perform one of the following options:
   
Parameter values: redirect.login.ssl determines the protocol to use when you click the login button. Specify one of the following values:

• true to use HTTPS.
• false to use HTTP.
  
  
• If the property exists, click the property to modify it and change the value to true.
• If the property does not exist, click New to create the property and enter the following information:
• Name: redirect.login.ssl
• Value: true
• Type: java.lang.String
  
  
6. Locate the host.port.https property and perform one of the following options:
   
• If the property exists, click the property to modify it and change the value to alias_port.
Note: alias_port is the port number that is used for the virtual host alias that is specified in a previous step (usually 443).

• If the property does not exist, click New to create the property and enter the following information:
• Name: host.port.https
• Value: 443
• Type: java.lang.String
  
  
7. Click Save to save the changes to the master configuration.
8. Log out of the administrative console.
   
5. Update the Transport Security Constraint in wps.ear.
   
You can modify the transport guarantee so that WebSphere Application Server enforces the use of SSL for all pages under the /myportal/ URL. This step is required only if you need to completely secure the protected area over HTTPS.

Clustered environments: Perform this step on the primary node, then perform a full resynchronize to propagate the changes to all nodes.

1. Export wps.ear.
   
See the following topic for instructions: Exporting the portal EAR file.

2. Navigate to the directory where you exported wps.ear: path_to_exported_EAR/installedApps/node_name/wps.ear/wps.war/WEB-INF
   
Note: You might need to extract the exported EAR before you can edit any files.

3. Locate and open web.xml with any text editor.
4. Set the value of the <transport-guarantee> element to CONFIDENTIAL under the <security-constraint> element for the /myportal/* URL. Do not change the values for the other <transport-guarantee> elements.
   
Update the XML as follows:



      <security-constraint id="SecurityConstraint_1">

         <web-resource-collection id="WebResourceCollection_1">

            <web-resource-name></web-resource-name>

         <url-pattern>/myportal/*</url-pattern>

			<http-method>DELETE</http-method>

            <http-method>POST</http-method>

            <http-method>GET</http-method>

            <http-method>PUT</http-method>

         </web-resource-collection>

         <auth-constraint id="AuthConstraint_1">

            <description></description>

            <role-name>All Role</role-name>

         </auth-constraint>

         <user-data-constraint id="UserDataConstraint_4">

            <transport-guarantee>CONFIDENTIAL</transport-guarantee> 

         </user-data-constraint>

      </security-constraint>



5. Save and close web.xml.
6. Redeploy wps.ear.
   
See the following topic for instructions: Redeploying the portal EAR file.

7. Clustered environments: Synchronize the nodes.
   
1. Log in to the Deployment Manager.
2. Select System Administration -> Nodes.
3. Select the nodes to synchronize from the list.
4. Click Full Resynchronize.
   
6. Perform the following steps to update theme links:
1. Edit the JSP and JSPF files that provide the login link. Locate the JSP and JSPF files that include the "wps.Login" string:
   
You should not edit any of the themes shipped with WebSphere Portal because these themes are updated with fixes. Instead, you should copy the theme and make your changes to the copy.

Finding theme resources: See the Location of theme resources link below.

This attribute should appear in a tag similar to the following:



     <portal-navigation:urlGeneration contentNode="wps.Login" 

          portletWindowState="Normal">



The exact structure of this tag can vary depending on how it was constructed by the page designer. JSP comments might also be used to indicate where the login link is located:



      <%-- login button --%>



2. After finding the login link, change or add the ssl="true" attribute to the <portal-navigation:urlGeneration> tag of the anchor, for example:
   

<wps:if loggedIn="no" notSelection="wps.Login">

 <wps:urlGeneration contentNode="wps.Login" 

            portletWindowState="Normal" ssl="true">

  <td class="wpsToolBar" valign="middle" nowrap>

   <a href="<% wpsURL.write(escapeXmlWriter); %>" class="wpsToolBarLink">

   <wps:text key="link.login" bundle="nls.engine"/>

   </a>

  </td>

 </wps:urlGeneration>

</wps:if>



Note: The previous examples use the portal-navigation: prefix to designate JSP tags from the portal navigation tag library. Your custom JSPs might use a different tag prefix.

7. Optional: Perform the following steps when using a remote Web server if you need to allow direct access to the WebSphere_Portal node on the internal port, for example http://www.ibm.com:10039/wps/portal:
1. From the WebSphere Application Server Administrative console go to Servers -> Server Types -> WebSphere application servers -> WebSphere_Portal -> Web Container Settings -> Web Container Transport Chains.
2. Click New.
3. Select a name for the transport chain.
4. Select the WebContainer-Secure template (templates/chains|webcontainer-chains.xml).
5. Select Next.
6. Specify the Port name; for example 443.
7. Click Next.
8. Click Finish to confirm the creation of the transport chain.
9. Click Save.
10. If this is a clustered environment, repeat the above steps for each node in the cluster, for example WebSphere_Portal2, and then synchronize the changes to all nodes.
    
8. Optional: Perform the following steps only if using the Login portlet:
1. Log in to WebSphere Portal.
2. Navigate to Administration -> Portlet Management -> Portlets.
3. Locate the Login portlet and click the Configure portlet icon.
4. Locate the UseSecureLoginActionUrl parameter and click the Edit value icon.
5. Type true in the Value field and click OK to save your changes.
6. Click OK to return to the Manage Portlets portlet.
   
9. In a stand-alone environment, stop and restart the server1 and WebSphere_Portal servers. In a clustered environment, stop and restart the Deployment Manager and the WebSphere_Portal servers.
   
Clustered environments: In the Deployment Manger, verify that the EAR changes have been successfully synchronized to all nodes. Stop and restart the servers on all nodes.

10. Follow these steps to test your changes:
1. Launch the home page in a Web browser through an HTTP URL that is not secure (for example, http://hostname.example.com:10039/wps/portal, where hostname.example.com is the fully qualified host name of the machine where WebSphere Portal is running and 10039 is the default transport port that is created by WebSphere Application Server; the port number may be different for your environment.).
   
2. Verify that the login link in the banner area uses the HTTPS schema for the link to the login page.
   
3. Enter your username and password and then click the login link to verify that this page is already protected; the URL must be HTTPS and the browser must indicate that the page is protected.
   
Browser security prompt: After you click the login link to accept the server certificate, a browser security prompt might appear.

4. Log off.
   
5. Log in using an HTTP URL that is not secure and that points directly to the protected area (for example, http://www.ibm.com:10039/wps/portal).
   
6. Verify that you are requested to login and that the login page and the portal page afterwards are protected through SSL.
   
Note: If the security-constraint has not been modified to CONFIDENTIAL, SSL will not protect the login page and the portal pages.

Parent topic: Configuring SSL
Next topic: Configuring SSL only for the login process

Related tasks
Redeploying the portal EAR file
Exporting the portal EAR file

Related reference
Location of theme resources

Related information
Configuring SSL only for the login process