Configuring SSL for WebSphere Application Server

This section includes the following steps to configure SSL with your IBM WebSphere Application Server.

Creating a local user account on WebSphere

For enabling SSL, WebSphere needs access to a user account in the local OS user registry that has permission to administer the system:

• (Windows) Create a Windows user who is part of the Administrators group and has the privilege to act as part of the operating system. (See Create a Windows user for WebSphere.)
• (Linux, UNIX) The user can be a root user or another user who has root privileges. When you enable SSL on WebSphere, use the server identification and password of this user.

Create a Linux or UNIX user for WebSphere

1. Log in as the root user.

2. Create a user by entering the following command in a command prompt:

   • (Linux and Sun Solaris) useradd
   • (IBM AIX) mkuser

3. Set the password of the new user by entering passwd in the command prompt.

4. (Linux and Solaris) Create a shadow password file by entering pwconv (with no parameters) in the command prompt.

   NOTE

   (Linux and Solaris) For WebSphere Application Server Local OS security registry to work, a shadow password file must exist. The shadow password file is usually named /etc/shadow and is based on the /etc/passwd file. If the shadow password file does not exist, an error occurs after enabling global security and configuring the user registry as Local OS.

5. Open the group file from the /etc directory in a text editor.

6. Add the user who you created in step 2 to the root group.

7. Save and close the file.

8. (UNIX with SSL enabled) Start and stop WebSphere as the root user.

Create a Windows user for WebSphere

1. Log in to Windows by using an administrator user account.
2. Select Start > Control Panel > Administrative Tools > Computer Management > Local Users and Groups.
3. Right-click Users and select New User.
4. Type a user name and password in the appropriate boxes, and type any other information you require in the remaining boxes.
5. Deselect User Must Change Password At Next Login, click Create, and then click Close.
6. Click Users, right-click the user you created and select Properties.
7. Click the Member Of tab and then click Add.
8. In the Enter The Object Names To Select box, type Administrators, click Check Names to ensure that the group name is correct.
9. Click OK and then click OK again.
10. Select Start > Control Panel > Administrative Tools > Local Security Policy > Local Policies.
11. Click User Rights Assignment, and then right-click Act as Part of the Operating System and select Properties.
12. Click Add User or Group.
13. In the Enter The Object Names To Select box, type the name of the user you created in step 4, click Check Names to ensure that the name is correct, and then click OK.
14. Click OK to close the Act As Part Of The Operating System Properties dialog box.

Configure WebSphere to use the newly created user as Administrator

1. Ensure that WebSphere is running.

2. In WebSphere Administrative Console, select Security > Global Security.

3. Under Administrative security, select Administrative user roles.

4. Click Add and do the following:

   1. Type * in the search box and click search.
   2. Click Administrator under roles.
   3. Add the newly created user to Mapped to role and map it to Administrator.

5. Click OK and save your changes.

6. Restart the WebSphere profile.

Enable administrative security

1. In WebSphere Administrative Console, select Security > Global Security.

2. Click Security Configuration Wizard.

3. Ensure Enable Application Security checkbox is enabled. Click Next.

4. Select Federated Repositories and click Next.

5. Specify the credentials you want to set and click Next.

6. Click Finish.

7. Restart the WebSphere profile.

   WebSphere starts using the default keystore and truststore.

Enable SSL (custom key and truststore)

Truststores and keystores can be created using ikeyman utility or admin console. To make ikeyman work properly, enure that the WebSphere installation path does not contain parentheses.

1. In WebSphere Administrative Console, select Security > SSL certificate and key management.

2. Click Keystores and certificates under Related items.

3. In the Key store usages dropdown, ensure that SSL Keystores is selected. Click New.

4. Type a logical name and description.

5. Specify the path where you want your keystore to be created. If you have already created a keystore through ikeyman, specify the path to the keystore file.

6. Specify and confirm the password.

7. Choose the keystore type and click Apply.

8. Save the master configuration.

9. Click Personal Certificate.

10. If you had added already created a keystore using ikeyman, your certificate will appear. Otherwise, you need to add a new self-signed certificate by performing the following steps:

    1. Select Create > Self-signed Certificate.
    2. Specify appropriate values on the certificate form. Ensure that you keep Alias and common name as fully qualified domain name of the machine.
    3. Click Apply.

11. Repeat steps 2 through 10 for creating a truststore.

Apply custom keystore and truststore to the server

1. In WebSphere Administrative Console, select Security > SSL certificate and key management.

2. Click Manage endpoint security configuration. The local topology map opens.

3. Under Inbound, select direct child of nodes.

4. Under Related items, select SSL configurations.

5. Select NodeDeafultSSLSetting.

6. From the truststore name and keystore name drop-down lists, select the custom truststore and keystore that you created.

7. Click Apply.

8. Save the master configuration.

9. Restart the WebSphere profile.

   Your profile now runs on custom SSL settings and your certificate.

Enabling support for AEM forms natives

1. In WebSphere Administrative Console, select Security > Global Security.
2. In the Authentication section, expand RMI/IIOP security and click CSIv2 inbound communications.
3. Ensure that SSL-supported is selected in the Transport drop-down list.
4. Restart the WebSphere profile.

Configuring WebSphere to convert URLs that begins with https

To convert a URL that begins with https, add a Signer certificate for that URL to the WebSphere server.

Create a Signer certificate for a https enabled site

1. Ensure that WebSphere is running.

2. In WebSphere Administrative Console, navigate to Signer certificates and then click Security > SSL Certificate and Key Management > Key Stores and Certificates > NodeDefaultTrustStore > Signer Certificates.

3. Click Retrieve From Port and perform these tasks:

   • In the Host box, type the URL. For example, type www.paypal.com.
   • In the Port box, type 443. This port is the default SSL port.
   • In the Alias box, type an alias.

4. Click Retrieve Signer Information and then verify that the information is retrieved.

5. Click Apply and then click Save.

HTML-to-PDF conversion from the site whose certificate is added will now work from the Generate PDF service.

Configuring dynamic ports

IBM WebSphere does not allow multiple calls to ORB.init() when Global Security is enabled. You can read about the permanent restriction at https://www-01.ibm.com/support/docview.wss?uid=swg1PK58704.

Perform the following steps to set the port to be dynamic and resolve the issue:

1. In WebSphere Administrative Console, select Servers > Server Types > WebSphere application server.

2. In the Preferences section, select your server.

3. In the Configuration tab, under Communications section, expand Ports, and click Details.

4. Click the following port names, change the port number to 0, and click OK.

   • ORB_LISTENER_ADDRESS
   • SAS_SSL_SERVERAUTH_LISTENER_ADDRESS
   • CSIV2_SSL_SERVERAUTH_LISTENER_ADDRESS
   • CSIV2_SSL_MUTUALAUTH_LISTENER_ADDRESS

Configure the sling.properties file

1. Open [aem-forms_root]\crx-repository\launchpad\sling.properties file for editing.

2. Locate the sling.bootdelegation.ibm property and add com.ibm.websphere.ssl.*to its value field. The updated field look like the following:

   sling.bootdelegation.ibm=com.ibm.xml.*, com.ibm.websphere.ssl.*
   

3. Save the file and restart the server.