Set up SSL

 

+

Search Tips   |   Advanced Search

 

SSL setup steps that refer to the WAS and the Web server are summarized here. Refer to the WAS and the Web server documentation for detailed information. Steps that are unique to WebSphere Portal are described in detail here.

This procedure might be slightly different if a front-end security proxy server such as 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 TAM WebSEAL TAI with an SSL junction, perform only steps 1-3 of this procedure.

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. Set 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
    • Microsoft Certificate Service

    The Web server must have a port defined (usually 443), and the necessary certificates and keys must be installed.

    If this is a production environment, obtain a certificate from a certificate authority. For testing purposes, you can use IKEYMAN to generate a self-signed certificate.

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

  2. Configure the plug-in for the Web server to forward portal traffic received over SSL.

  3. Optionally, secure the transport channel between Web server and WebSphere.

    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.

    Do not modify the default SSL key and truststore.

  4. Create or modify the properties...

      redirect.login.ssl=true
      host.port.https=alias_port

    ...in the configuration services...

    1. Log on to the admin console.

    2. Navigate to...

        Resources | Resource Environment | Resource Environment Providers | WP ConfigService | Additional Properties | Custom Properties

    3. If the property already exists, click the appropriate property to modify it or click New to create the properties.

    4. Click Save to save the changes to the master configuration.

    alias_port is generally 443.

    redirect.login.ssl sets the protocol used when you click the login button. If set to true, https is used. If set to false, http is used. This setting is not affected by the protocol that is used to access the main page.

  5. Export the WebSphere Portal EAR file:

    If using a custom deployed theme.war file, export, update, and reimport the corresponding EAR in addition to the WPS EAR

    When customized themes and skins are deployed into a managed cell or cluster, update them in the master configuration, which is managed by the deployment manager.

    1. Perform the following steps before exporting:

      1. Make sure the WAS administrative server is started:

        If running in a clustered environment, make sure that the Deployment Manager and all node agents are also running.

      2. Verify the WebSphere Portal is stopped.

      3. Make sure you are logged in using the WAS administrative user ID.

    2. Export the WebSphere Portal EAR file, wps.ear.

      If you have a clustered environment, the WebSphere Portal EAR must be exported from the WAS Network Deployment machine.

        cd PROFILE_HOME/bin
        ./wsadmin.sh -user admin_user_id -password admin_password -c '$AdminApp export wps /tmp/wps.ear'

    3. Use the EARExpander tool to expand the contents of the exported EAR file

        ./EARExpander.sh -ear /tmp/wps.ear -operationDir /tmp/wps_expanded -operation expand

  6. Use the following steps to update transport security constraints:

    Theme JSPs and deployment files are managed as part of the main application and are thus part of the EAR file. Update and redeploy EAR files when changing JSPs or deployment related xml files; otherwise, your changes will be deleted when the EAR file is updated.

    1. Update the Transport Security Constraint in the WPS EAR.

      This step is only required if completely secure the protected area over HTTPS.

      You can modify the transport guarantee so that WAS will enforce the use of SSL for all pages under the /myportal/ URL.

      Edit...

      /tmp/wps_expanded/wps.war/WEB-INF/web.xml

      Change the security-constraint tag of the protected URL, /myportal/*, to use HTTPS by setting each occurrence of the transport guarantee value of 'NONE' to 'CONFIDENTIAL'; leave the other security-constraint transport guarantee values unchanged: 

         <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> 

         // replace NONE by CONFIDENTIAL
      </user-data-constraint>

   </security-constraint>

  7. Update theme links:

    1. Edit the JSP and JSPF files that provide the login link. You can search the theme directories under...

        /tmp/wps_expanded/wps.war/themes/

      ...for all JSP and JSPF files that include the "wps.Login" string: This attribute should appear in a tag similar to this: 

        <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>

      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.

  8. Redeploy the WebSphere Portal EAR file:

    1. Place the updated themes and skins JSPs into the correct directory within the expanded EAR. For example:

      HTML themes go in...

        /tmp/wps_expanded/wps.war/themes/html

      HTML skins go in...

        /tmp/wps_expanded/wps.war/skins/html

    2. Delete the original the wps.ear file from the directory where you initially exported it.

    3. Use the EARExpander command to collapse the EAR directory back into an EAR file:

        ./EARExpander.sh -ear /tmp/wps.ear -operationDir /tmp/wps_expanded -operation collapse

    4. Use the wsadmin command to update the WebSphere Portal EAR:

      If you have a managed cell (with or without a cluster), perform this step on the deployment manager machine.

        ./wsadmin.sh -user admin_user_id -password admin_password -c '$AdminApp install /tmp/wps.ear {-update -appname wps -nodeployejb}'

      If you receive the following error when attempting to update the WebSphere Portal EAR, an error may have occurred when updating the wps.ear.

        com.ibm.websphere.management.exception.AdminException: The application wps was installed using Zero Binary Copy option.

      To solve this error, restart server1 and attempt the update again, specifying the paths in the format shown in the example above.

    5. Synchronize all nodes.

    6. Restart WebSphere Portal on the standalone server, or on each cluster member if using a cluster environment.

  9. Optional: Perform the following steps when using a remote Web server if allow direct access to the WebSphere_Portal node on the internal port, for example...

      http://www.ibm.com:10040/wps/portal

    If this is a clustered environment, make this update on each WebSphere_Portal node in the cluster.

    1. Depending on your version of WAS, make the appropriate selection from the navigation:

      • For WAS v6.1: From the Administrative console go to...

          Servers > Application Servers > WebSphere_Portal > Web Container Settings > Web Container Transport Chains

      • For WAS v7: From the Administrative console go to...

          Servers > Server Types > WebSphere appservers > 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, synchronize the changes to all nodes.

  10. 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.

  11. Cycle the server1 and WebSphere_Portal servers.

    If this is a clustered environment, verify that the EAR changes have been successfully synchronized to all nodes. Cycle the servers on all nodes.

  12. 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:10040/wps/portal

    2. Verify that the login link in the banner area uses the HTTPS schema for the link to the login page.

    3. Go to the login screen and verify that this page is already protected; the URL must be HTTPS and the browser must indicate that the page is protected.

      A browser security prompt might appear after you click the login link to accept the server certificate.

    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:10040/wps/portal

    6. Verify that you are requested to login and that the login page and the portal page afterwards are protected through SSL.

      If the security-constraint has not been modified to CONFIDENTIAL, SSL will not protect the login page and the portal pages.


Parent topic:

Configure SSL


Next topic:

Configure SSL only for the login process


Related tasks


Configure SSL only for the login process