Configuring Transport Layer Security (TLS)

You can configure Transport Layer Security (TLS) by modifying or replacing the keystore and truststore, and choosing the certificate alias for your configuration.

Before you begin

  • You can configure TLS with Version 1.0.0.4 or later.
  • You must be using WebSphere® eXtreme Scale Client Version 7.1 Fix 1 or later.
  • You must be assigned the Appliance administration permission.
  • You must have a keystore or truststore with the associated passwords that you want to add to the appliance configuration.
  • If you want to modify the existing truststore, you can download the truststore from the appliance.
  • You must update the truststore with the public certificates of the clients. The appliance must trust the clients that are connecting.
  • The supplied truststore must include a public certificate that corresponds to an entry in the keystore. Certificate aliases from the keystore must be trusted in the truststore to be supplied as a possible configuration option for the certificate alias for the appliance.
  • The global security setting in WebSphere Application Server determines how that server attempts connections to the WebSphere DataPower® XC10 Appliance:
    • When the global security setting is disabled, connections are attempted over TCP/IP.
    • When the global security setting is enabled, you must add the public certificate of the appliance to the WebSphere Application Server truststores.
    If your WebSphere DataPower XC10 Appliance has TLS required configured, you must enable global security. For more information about configuring global security, see Global security settings.

About this task

The TLS settings apply to the user interface and data grids. The settings are applied to all of the appliances in the collective.

Procedure

  1. Required for WebSphere Application Server: Add the appliance public certificate to the WebSphere Application Server default truststores.
    • If you are using the default appliance truststore:
      Run the addXC10PublicCert.py script from the was_root/bin directory on the deployment manager. Use the following command:
      wsadmin -lang jython -f addXC10PublicCert.py
    • If you are using custom keys for the appliance:
      Run the addXC10PublicCert.py script from the was_root/bin directory on the deployment manager with the -certPath command line option. The value of the -certPath command line option is the disk location of the public certificate that corresponds to the alias that is configured for the keystore on the appliance.
      wsadmin -lang jython -f addXC10PublicCert.py -certPath ./trustStore.jks
  2. Required for WebSphere Application Server: Download the appliance truststore and WebSphere Application Server public certificates and run the keytool utility to add the certificate to the truststore. This tool updates the appliance truststore to include the certificates from WebSphere Application Server.
    1. If you are using the default appliance truststore, download the active truststore. Click Appliance > Settings > Transport Layer Security (TLS). Click Download active truststore and remember the location of where you saved the file on disk, for example in the /downloads/trustStore.jks directory.
    2. Extract the WebSphere Application Server public certificate.
      1. In the WebSphere Application Server administrative console, click Security > SSL certificate and key management > Keystores and certificates.
      2. From Keystore usages, select Root certificates keystore.
      3. Select DmgrDefaultRootStore.
      4. Select Personal certificates.
      5. Click the checkbox next to a certificate in the root keystore. Specify a fully-qualified file name of the certificate to extract, such as: /certificates/public.cer.
      6. In a command-line window, run the following command: cd /java_home/bin
      7. Run the keytool utility.
        keytool -import -noprompt -alias "example alias" -keystore /downloads/trustStore.jks  -file /certificates/public.cer -storepass xc10pass -storetype jks
      8. If you have additional certificates to import, repeat the steps to extract the certificates and run the keytool utility again.
  3. Upload keystore and truststore information to the appliance. In the appliance user interface, click Appliance > Settings > Transport Layer Security (TLS). If you completed the steps for WebSphere Application Server, upload the updated /downloads/trustStore.jks file. After you upload a keystore or truststore, you must update the associated password. If you are using the default truststore, the password is xc10pass.
  4. Select the certificate alias for the collective.
  5. Specify the transport type. Choose one of the following transport type settings:
    • TLS supported: Data grids communicate with TCP/IP, SSL, or TLS. The user interface is accessible with HTTP and HTTPS.
    • TLS required: Data grids communicate with SSL or TLS only. The user interface is accessible with HTTPS only.
    • [Version 2.0.0.3 and later] Data grid TLS disabled: Data grids communicate with non-secure connections. The user interface is accessible with HTTP and HTTPS.
  6. To require the client to send a trusted certificate to enable communication, select Enable client certificate authentication.
  7. Click Submit TLS settings to save the changes to your configuration.

Results

The collective must restart to complete the TLS configuration changes.

Limited portions of the user interface are accessible when the collective is restarting. If you cannot access portions of the user interface, wait for an appropriate time and submit the request again. The Tasks panel shows completion for some TLS changes automatically by displaying a success status.

If you changed the certificate alias that is used by the appliance, you might need to restart the browser, log out and log back in to the user interface, or trust new certificates from a browser prompt.

If the user interface seems to be unavailable when client authentication is enabled, verify that you have a trusted client certificate imported into the browser. If a trusted client certificate is not imported into the browser, you cannot access the user interface. After you successfully log on to the user interface, the task indicates the success of the TLS configuration.

What to do next

Best practices
  • To avoid browser warnings when you access the user interface from different appliances, consider including a wildcard in the Common Name (CN) of the certificate in the keystore. Each appliance uses the same certificate for TLS configuration, as specified by the certificate alias. For example, you might use *.mycompany.com instead of myhost.mycompany.com to make the certificate valid for all hosts in the mycompany domain.
  • You might want to use a private certificate authority (CA) to sign the certificate that is associated with the certificate alias that you chose for your TLS configuration. You can then import the CA certificate into the browser and trust any collective with a certificate signed by the private CA without being prompted. Using a private CA is generally only appropriate for access on a private intranet.
Parent topic: Security
Related concepts:
IBM WebSphere DataPower XC10 Appliance security overview
User permissions
Related tasks:
Configuring IBM WebSphere DataPower XC10 Appliance user interface security
Configuring your appliance to authenticate users with an LDAP directory
Managing users and groups
Securing data grids
Configuring HTTP session manager with WebSphere Portal
Administering with the HTTP command interface
Monitoring with the xscmd utility
Related reference:
REST gateway: Security configuration
Related information:
Managing keys with the IKEYMAN graphical interface