+

Search Tips   |   Advanced Search

Configure SSL


  1. Overview
  2. Configure SSL only for the login process
  3. Set up Client Certificate Authentication
  4. Cryptographic hardware for SSL acceleration


Overview

Use SSL to encrypt traffic between client browsers and portal web and app servers.

If configured, a front-end security proxy server such as IBM Tivoli Access Manager WebSEAL can encrypt traffic from client browsers. Traffic between Web server and the front-end security proxy server can also be encrypted, if needed. To use a Tivoli Access Manager WebSEAL TAI with an SSL junction, complete only steps 1-3 of this procedure.

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


Configure SSL

  1. Configure the Web server to support HTTPS.

  2. Depending on the Web server to use, other software may have to be installed on the Web Server.

    For example: instance Microsoft Internet Information Server and Microsoft Certificate Service.

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

  4. For production environments, obtain a certificate from a certificate authority.

    For testing purposes, use IKEYMAN to generate a self-signed certificate.

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

  5. Configure the web server plug-in for SSL

  6. 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, we 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 WAS.

    • For information about configuring SSL between the Web server and the application server, use the IBM Redbook...

        WAS V7.0 Security Guide

      Use section "8.7.2 Application server configuration: Web container configuration of the IBM WAS"

    • For information about this step, use the IBM Redbooks link in the related links section. Search for Security Handbook.

    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.

  7. To create or modify the two required properties in the configuration services:

    1. Log on to the WAS admin console and go to...

        Resources | Resource Environment | Resource Environment Providers | WP ConfigService | Custom Properties | redirect.login.ssl

      Complete one of the following options:

      Parameter values: redirect.login.ssl determines the protocol to use after login completes.

      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

    2. Locate the host.port.https property and complete one of the following options:

      • If the property exists, click the property to modify it and change the value to alias_port. alias_port is the port number used for the virtual host alias pecified 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

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

    4. Log out of the WAS admin console.

  8. Update the Transport Security Constraint in wps.ear.

    We can modify the transport guarantee so that WAS 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: Complete this step on the primary node, then complete a full resynchronize to propagate the changes to all nodes.

    1. Export wps.ear.

    2. cd /path/to/exported/EAR/installedApps/node_name/wps.ear/wps.war/WEB-INF

      You might need to extract the exported EAR before we can edit any files (EARExpander).

    3. Edit web.xml

    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.

    7. For clusters, synchronize the nodes.

      Log in to the dmgr and run...

        System Administration | Nodes | nodes | Full Resynchronize

  9. To update theme links:

    1. Edit the JSP and JSPF file that provide the login link. Locate the JSP and JSPF file 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.

      Find theme resources:

      See the Location of theme resources link in the Related section.

      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="http://setgetweb.com/p/portal80/<% 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 JSP tags might use a different tag prefix.

  10. Optional: Complete 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 WAS admin console, go to...

        Servers | Server Types | WebSphere appservers | WebSphere_Portal | Web Container Settings | Web Container Transport Chains | New

    2. Select a name for the transport chain.

    3. Select the WebContainer-Secure template...

        templates/chains|webcontainer-chains.xml

    4. Select Next.

    5. Specify the Port name; for example 443.

    6. Click Next.

    7. Click Finish to confirm the creation of the transport chain.

    8. Click Save.

    9. If this is a clustered environment, repeat the previous steps for each node in the cluster, for example WebSphere_Portal2, and then synchronize the changes to all nodes.

  11. Optional: Complete the following steps only if using the Login portlet:

    1. Log in to WebSphere Portal and go to...

        Administration | Portlet Management | Portlets | Login portlet | Configure portlet icon

    2. Locate the UseSecureLoginActionUrl parameter and click the Edit value icon.

    3. Type true in the Value field and click OK to save the changes.

    4. Click OK to return to the Manage Portlets portlet.

  12. In a stand-alone environment, stop and restart the WebSphere_Portal server. In a clustered environment, stop and restart the dmgr and the WebSphere_Portal servers.

    Clustered environments: In the Deployment Manger, verify the EAR changes have been successfully synchronized to all nodes. Stop and restart the servers on all nodes.

  13. To test the changes:

    1. Launch the home page in a Web browser through an HTTP URL that is not secure...

        http://hostname.example.com:10039/wps/portal

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

    3. Enter the 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.

      After clicking 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 we 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 does not protect the login page and the portal pages.


Configure SSL only for the login process

We can encrypt only the login process to IBM WebSphere Portal and then allow subsequent requests via HTTP.

To configure SSL only for the login process:

Remember: These steps only configure SSL for the login; to configure SSL for other features such as themes and skins, perform the steps in "Setting up SSL".

  1. Verify the following parameters exist and are correctly set for the installation in the WP ConfigService application:

    1. Log on to the WAS admin console in a standalone environment or on the dmgr console in a clustered environment.

    2. Navigate to...

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

    3. Set the the redirect.login.ssl property.

      If set to true, https is used. If set to false, http is used. This setting is not affected by the protocol used to access the main page.

      • 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

    4. 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_for_HTTPS.

        alias_port_for_HTTPS is the port number used for the virtual host alias (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

    5. Locate the host.port.http property and perform one of the following options:

      Set the host.port.http if we are using a port other than the default 80.

      • If the property exists, click the property to modify it and change the value to alias_port_for_HTTP.

        alias_port_for_HTTP is the port number used for the virtual host alias (usually 80).

      • If the property does not exist, click New to create the property and enter the following information:

        • Name: host.port.http
        • Value: 80
        • Type: java.lang.String

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

    7. Log out of the WAS admin console.

  2. To only encrypt the login process to WebSphere Portal and allow subsequent requests via HTTP:

    The Login portlet uses the UseSecureLoginActionUrl parameter to control the generation of the login action URL. Set this parameter to true to use a secure URL for login.

    1. Navigate to...

        Administration | Portlet Management | Portlets

    2. Search for Title start with = "Login".

    3. Select the Configure portlet icon.

    4. Edit the UseSecureLoginActionUrl parameter and set the parameter to true.

We can test the SSL login using the following unprotected URL:

...and submitting the credentials. You will notice that the URL does not change to https.

Confirm the login was encrypted by monitoring the packets via a network utility such as Ethereal or by reviewing the source code of the login form when accessed through an unprotected HTTP URL. The login form should have an action URL that is secured, for example...

Set the browser to warn you when changing between secure and insecure modes to see the behavior on the client-side.


Set up Client Certificate Authentication

The supported scenario is a "client certificate only" setuthat switches completely to this authentication method and does not allow form-based login via username and password. Other configuration scenarios are possible, but are neither recommended nor supported.

To configure WebSphere Portal for SSL client certificate authentication:

  1. Complete the following steps when you configure IBM WAS for SSL support with client certificates:

    1. When we define the Quality of protection (QoP) settings for the new SSL Repertoire:

      1. Choose Required from the Client Authentication list

      2. Choose SSL_TLS from the Protocol list.

      3. In the Provider section, select Predefined JSSE provider, then choose IBMJSSE from the Select provider list.

    2. Reference the correct key and trust files.

      Create new key and trust files using the IKEYMAN tool and the PKCS12 format for maximum browser compatibility.

      The key file must contain the server certificate. The trust file must contain either all the client certificates of users that will be authenticated or a certification authority certificate (CA keyused to verify the client certificates of users.

    3. Associate the secure transport chain with the new SSL Repertoire.

    4. Configure the advanced LDAP security settings. Certificate-based authentication requires that you configure the authentication mechanism so that one of the following conditions apply:

      • WAS maps the entire Distinguished Name (DN) from the subject field of the certificate to a corresponding Distinguished Name in the LDAP. To use this option, set the mapping technique in the LDAP configuration panel to exact.

      • WAS maps the entry in the subject field to a different attribute than the Distinguished Name in the user registry. To use this option, set up the mapping technique in the LDAP configuration panel to use the certificate filter option. Using the certificate filter option allows us more flexibility in using attributes other than the Distinguished Name to identify the users.

        For example, the filter uid=${SubjectCN} maps the SubjectCN field of the client certificate to the uid attribute in the LDAP.

  2. Complete the following steps if we use an external HTTP server:

    1. Regenerate the plug-in. Go to Servers > Web Servers. Select the Web server and click Generate Plug-in. Update the HTTP server with the generated plug-in.

    2. Restart the HTTP server for the changes to take effect.

    3. Enable client certificate authentication in the Web server. For IBM HTTP Server (IHS), refer to http://www.redbooks.ibm.com/ and search for security handbook for the latest information about WAS.

  3. Update wps.ear to change the authentication method and transport guarantee setting to support client certificate authentication.

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

    1. Export wps.ear. See the following topic title in the Related task section for instructions: Exporting the portal EAR file.

    2. Go to the directory where you exported wps.ear: /path/to/exported/EAR/installedApps/node_name/wps.ear/wps.war/WEB-INF

      You might need to extract the exported EAR before we can edit any files.

    3. Edit the web.xml file located in the exported ear directory under /wps.war/WEB-INF.

    4. Change the login-config tag to the client certificate authentication method. 
      <login-config id="LoginConfig_1"> 
  <auth-method>CLIENT-CERT</auth-method> 
  <realm-name>WPS</realm-name> 
  <!--<form-login-config id="FormLoginConfig_1">     
   <form-login-page>/redirect</form-login-page>    
   <form-error-page>/error.html</form-error-page> 
  </form-login-config> -->
</login-config>

    5. Change the transport guarantee setting in the security constraint for the protected area to CONFIDENTIAL: 
      <security-constraint id="SecurityConstraint_1"> 
  <web-resource-collection id="WebResourceCollection_1">   
   <web-resource-name/>  
   <url-pattern>/myportal/*</url-pattern>   
   <http-method>DELETE</http-method>   
   <http-method>GET</http-method>   
   <http-method>POST</http-method>   
   <http-method>PUT</http-method>   
   <http-method>HEAD</http-method> 
  </web-resource-collection> 
  <auth-constraint id="AuthConstraint_1"> 
   <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>

    6. Save and close web.xml.

    7. Redeploy wps.ear. See the following topic title in the Related task section for instructions: Redeploying the portal EAR file.
    8. Clustered environments: Synchronize the nodes.

      1. Log in to the dmgr.

      2. Select System Administration > Nodes.

      3. Select the nodes to synchronize from the list.

      4. Click Full Resynchronize.

  4. Update the themes and settings.

    1. Modify the URLs for login and logout in the themes used in the scenario. The file containing the login and logout links can be different, depending on the theme. In more recent themes, these links might be located in Default.jsp. In older themes, these links might be located in either banner.jspf or mainMenu.jsp.

      Find theme resources:

      See the Location of theme resources link in the Related section.

      Clustered environments: Complete the following steps. Noticthat in a clustered environment, the steps must be completed on the dmgr.

      • For the login link, use an arbitrary protected page. The login link will then implicitly trigger the SSL handshake in WAS due to the security constraint.

        For example, we can generate the URL to point to the protected welcome page: 

        <%-- Login button --%>
<%-- comment this to enable screen login --%> 
<portal-logic:if loggedIn="no">
<portal-navigation:urlGeneration 
contentNode="ibm.portal.Home.Welcome" home="protected">    
    <a tabIndex="7" class="toolbarLink" href='<% 
wpsURL.write(escapeXmlWriter); %>'>    
    <portal-fmt:text key="link.login" bundle="nls.engine"/>    
</a></portal-navigation:urlGeneration>
</portal-logic:if>

      • For the logout, you need to consider whether or not a logout should redirect you back to HTTP. If so, set the property redirect.logout.ssl in the configuration service to true. Also, set the host.port.http in the same service to the correct port. To stay in the HTTPS protocol after the logout, you do not need to complete any configuration steps here.

    2. Remove the login portlet from all pages where it is placed; for example, the welcome and the login page.

    3. To completely disable the entry points 'login portlet' and 'login URL' to WebSphere Portal: set the command.login property in the configuration service to the value LoginUserBlocked. This ensures that a login can only be triggered after being authenticated by WAS, in this case by the client certificate handshake.

      1. Log on to the WAS admin console and go to...

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

      2. Click command.login and change the value from LoginUserAuth to LoginUserBlocked.

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

      4. Log out of the WAS admin console.

  5. Stop and restart servers, dmgrs, and node agents.

  6. Verify the setup.

    1. Import one of the client certificates that are accepted by the server to the browser.

    2. Launch the home page in this 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 Portal is running and 10039 is the default transport port; the port number may be different for the environment..

    3. Click the login link.

    4. Verify the server switches to HTTPS and we are prompted for the client certificate.

    5. After selecting and confirming the correct client certificate, we are redirected to the protected area served with HTTPS.


Cryptographic hardware for SSL acceleration

We use cryptographic hardware to offload encryption and improve performance. WebSphere Portal tolerates interfacing through WAS with cryptographic hardware for SSL acceleration. However, the tasks involved in setting up and configuring cryptographic hardware are generally specific to Web servers or WAS, and do not necessarily involve configuring WebSphere Portal. The WAS Information Center contains several topics for setting up password encryption with cryptographic hardware.

Most cryptographic hardware requires the PKCS11 support software for the host machine and internal firmware. To get started with cryptographic hardware....

We can create a plug point to encrypt and decrypt all passwords in WAS that are currently encoded or decoded using Base64-encoding.

Create a custom class to encrypt passwords after creating the server profile.

In stand-alone environments, administrative functions such as installing WAR files or adding trace settings can fail when you meet both of the following conditions:

If the stand-alone environment meets both of the preceding conditions:

  1. Log in to the WAS admin console.

  2. Navigate to Security > Global Security > Administrative security > Administrative authentication

  3. Select Only use the active application authentication mechanism.

  4. Click Apply then OK and save the changes to the master configuration.

  5. Log out of the WAS admin console.

  6. Restart the WebSphere_Portal server.


See also

  1. Secure with SSL communications
  2. Create SSL digital certificates and SAF Facility keyrings that applications can use to initiate HTTPS requests
  3. Configure the web server plug-in for SSL
  4. WAS V7.0 Security Guide
  5. WAS Network Deployment v8.0: Create an SSL configuration
  6. WAS Network Deployment v8.0: Quality of Protection
  7. Redbooks
  8. Export the portal EAR file
  9. Redeploying the portal EAR file
  10. Location of theme resources