# Deployment Guide

# Implementing Network Security

This chapter describes security options you can implement for your deployment.

The purpose of this chapter is to help you understand the security requirements so that you can assign responsibility for developing a plan for security in your deployment.

This chapter includes the following topics:

- Security Architecture
- Security Modes
- Deploying SSL
- Single Sign-On Options

BEA provides the following additional resources to prepare the security leader for this assignment.

Resource | Description
--- | ---
Consulting Services | Get advice from the experts.
Knowledge Base | Register and log into the Support Center. Search the Knowledge Base for security-related topics, such as "SSL", "SSO", "Security Modes", "firewall", and the like.

## Security Architecture

Figure 7-1 provides a high-level representation of the recommended network security for deployment of ALI components.

Figure 7-1 Representation of Network

### Firewalls and Security

A firewall can be a valuable component in an overall security strategy. However, firewalls alone do not create security. Firewalls typically provide the first line of defense, intelligently routing requests and filtering out those that do not meet requirements configured into the device (or software). Depending on the sophistication of the firewall product, more or less intelligence can be built into the decision tree affecting whether a packet should pass through the firewall. Having a firewall in place can provide a false sense of security, however. Consider the following real world scenario:

Suppose a Web server operating in a DMZ behind a firewall restricts traffic to port 443 (HTTPS) requests. A second firewall insulates the internal network from the computers in the DMZ. A hacker from the Internet sends a buffer overrun attack to the IP address of the Web server. The data looks like a regular HTTPS request, it goes to port 443, and is passed through to the Web server as a TCP stream. The Web server tries to decrypt the stream in the normal fashion. The data inside the request exploits a weakness in the Web server that allows it to overrun the memory stack of one of its threads. The thread executes some code sent by the hacker. The code gains control of the Web server, opens a new socket and sends a similar malicious request to the next server in the HTTP(S) chain. The request goes unnoticed by the second firewall (it still uses HTTPS TCP port 443). The target Web server is controlled in the same fashion. If the second server is a member of your primary domain, the hacker has a good access point to your network. If the buffer overruns were done carefully and security audits for successes (versus failures) are not implemented on the Web servers in the chain, it is unlikely the attack would even be noticed.

This is not to imply that firewalls are useless. On the contrary, firewalls can dramatically limit the nature and even the source of potential attacks. Firewalls must be supplemented by good internal security policies and measures. For example, by restricting the rights and privileges of the user in whose process space the Web server runs, risks can be minimized or eliminated. Furthermore, with careful configuration of network trusts and operating system security audits and alerts, an attack such as that described above could be very difficult to implement.

### Implementing AquaLogic Interaction in a DMZ

A DMZ (sometimes referred to as a demilitarized zone or perimeter network) is a computer or small network inserted as a neutral zone between a private network (intranet) and the outside public network (Internet or extranet). A DMZ uses some combination of firewalls and gateways to prevent outside users from having direct access to a server that holds company data.

The remainder of this section focuses on the positioning of ALI components with respect to firewalls and perimeter networks (DMZs). BEA does not advocate the use of any specific configuration. This section presents several possible topologies that incorporate firewalls, since they are a common element of many company infrastructures.

The most important security measure is the "hardening" (establishing maximum possible security) of the computers involved in the portal configuration, especially those that receive direct user requests. These Web server computers are sometimes referred to as bastion hosts, since they are typically the most vulnerable to attack. Establishing the appropriate privileges for the ALUI user is a critical component of this activity (as is installing all of the appropriate security patches for the operating system and application server). However, once steps are taken to secure bastion hosts and other computers, you can provide extra layers of security to protect against unknown vulnerabilities in the operating system or Web server software.

#### Web Services and Internal Network Security

Residing in the DMZ, the Portal component requires the most scrutiny in designing for security. Except for the Database and Search, all requests from the Portal component into the internal network are made through web services protocols using TCP/IP and HTTP 1.1. This web services architecture provides the following security advantages:

- HTTP 1.1 is a well-known protocol for tools to monitor and audit.
- Each web service runs over a single, configurable port number, which is easy to protect with a firewall.
- The Portal component implements the full range of HTTP security, including SSL/TLS, certificates, and basic authentication when making requests.
- Single sign-on (SSO) products that are designed to protect HTTP traffic can be used to protect web services residing in the internal network. The portal is designed to forward SSO tokens as needed.
- Full connections to systems of record are not provided to the DMZ. Each web service is designed to provide remote calls to specific functionality. This is analogous to providing only a set of stored procedures instead of full DBA-level database access to a client-server application.
- On Windows networks, the portal can authenticate against multiple Windows domains with no trust relationship by using multiple Windows authentication web services.
- Administrators can ban all traffic except known HTTP connections from the DMZ into the internal network. Protocols considered "unsafe" for use in a DMZ are limited to use on the internal network.

ALI provides many out-of-the-box integration web services to connect to Windows Active Directory, LDAP Servers, Documentum, Microsoft Exchange, Lotus Notes, SAP, PeopleSoft, and Siebel, just to name a few. Organizations are encouraged to develop custom web services to integrate with internal systems. From a security standpoint, these are all the same and all would be deployed on the internal network. Organizations can use firewalls to further compartmentalize internal networks as needed.

#### Risk Mitigation Scenarios

Following are some simplified examples of perimeter network topologies. In all cases, the target audience for the portal is both internal and external, thus some form of perimeter network is implemented. VPN topology is deliberately omitted, although it is a very common means of accessing internal portal content from outside the firewall. For the purposes of this discussion, VPN is considered equivalent to internal network access.

##### Scenario 1: The Reverse Proxy + IIS

One of the simplest implementations of a perimeter network involves a reverse proxy. Much as proxy servers route traffic from the internal network to the Internet, reverse proxies route traffic in the opposite direction. A reverse proxy can be hardware (for example, F5 Big IP Application Switch) or a software component (for example, MS Proxy Server), and can incorporate other functionality, such as packet inspection and intelligent routing. The reverse proxy generally acts as the firewall between the outside world and the internal network, but can also be used in concert with multiple firewalls. Reverse proxies are somewhat controversial among network administrators, but are commonly used by organizations who view reverse proxy servers as one component in an overall solution.

##### Scenario 2: Multiple Network Cards

A second very common practice is to create multiple networks in a single computer through the use of two or more Network Interface Cards (NICs). With this scenario, you might also incorporate a firewall in addition to multiple NICs, with the firewall and one NIC serving as the perimeter network. The firewall blocks all traffic except HTTP requests, which are received by the Portal component on the first NIC. The Portal component uses the second NIC to communicate with other hosts residing on the internal network. Multiple NICs on the other hosts with yet another firewall can serve to separate them from the true internal network computers. In this case, adding another layer of indirection offers considerable benefit, without any associated performance degradation. The extra network card doubles the network bandwidth of the Portal component, improving scalability, increasing network security, and eliminating the need for server-to-server encryption, since there is no access to the dedicated subnet.

##### Scenario 3: Limited Functionality for External Users

Given the ALUI architecture, it is possible to deploy multiple ALI Web servers that implement different functionality. For example, one Web server might implement administrative functionality (for example, Content Service creation), while another might not. Administrative users are redirected to a separate URL to take advantage of the administrative portal pages. Similarly, external users can be granted more limited use of the portal than internal users. (Users that access the portal through a VPN are considered internal users.) Relegating all externally accessible resources to the perimeter network can eliminate virtually all traffic through the firewall for external users. At some sites, the only resource accessible through the firewall is the database server using vendor-specific database proxy software. For example, you might not want to allow internal documents to be searched or viewed by external users. Likewise, all external users are ALUI users, not LDAP users, since no HTTP or LDAP connection is enabled.

## Security Modes

After you install ALI components, you can configure portal communication to use any of the following security modes.

Security Mode | Description
--- | ---
0 | Portal pages remain in whatever security mode, http or https, that the user initially uses to access the portal. For example, if a user accesses the portal via http, all the portal pages will remain http; if a user accesses the portal via https, all the portal pages will remain https. This is the default setting. Use this mode only when the deployment is used internally, behind a firewall, and without an SSL accelerator. For example, you might want to use this mode for testing or development deployments.
1 | Certain portal pages are always secured via SSL and other pages are not. For example, the login page may always be secured but a directory browsing page may not. The page types that are secured are configurable. This mode is not generally recommended.
2 | All portal pages are always secured via SSL, that is, pages are accessed via https. Use this mode if you are not using an SSL accelerator. In this mode, the Web server should provide an SSL endpoint. We recommend against configuring the SSL endpoint directly on the Tomcat application server. Although application servers can handle Web requests directly, for scalability and security reasons, we recommended that you not permit your users to connect to the application server directly. Instead of securing the application server itself, you secure the front-end Web server and the channel between the Web server and the application server. Therefore, you must set up SSL and install an SSL certificate on the Web server.
3 | The portal uses an SSL accelerator. This is the most common set-up for production deployments. Use this mode if you are using an SSL accelerator. As with Security Mode 2, users are not connecting to the application server directly, so you need to secure the front-end application server and the channel between the accelerator and the application sever. Therefore, you must set up SSL and install an SSL certificate on the SSL accelerator.

For detailed information on configuring these settings, see the Administrator Guide. For additional information on SSL, see Deploying SSL.

## Deploying SSL

Secure Sockets Layer (SSL) is a protocol developed by Netscape for transmitting private documents on the Internet. SSL works by using a public key to encrypt data that is transferred over the SSL connection. All the major browsers support SSL, and many Web sites use the protocol to obtain confidential user information, such as credit card numbers. By convention, URLs that require an SSL connection start with https rather than http.

SSL prevents potential eavesdroppers from intercepting information (such as passwords) sent to Web sites and information (such as secure documents) the Web site sends back. Encrypting and decrypting communications requires processing and increases the time required for pages to load and display. A Web site can use SSL on some pages and not others, so most sites find a compromise between performance and security by using SSL only in strategic locations. For example, most e-commerce sites allow you to browse selections and add items to your shopping cart over HTTP, then they switch to HTTPS when you check out to protect personal information, such as your name and credit card number. Although there is some overhead in establishing an SSL session, the overhead for encrypting and decrypting during an established session is usually insignificant.

SSL can also be used to encrypt traffic between Web servers and Automation Services and portlet, Content Service, Search, or Authentication components. The Parallel Portal Engine supports SSL encryption of the parallel requests made to these remote servers, allowing safe transmission of portlet preferences and other data delivered from Portal components to other ALI components. To implement SSL between Portal and other hosts, register the remote server (the remote server object is used for all four types of web services) with an HTTPS URL. On Unix and Linux, the PPE implements SSL using OpenSSL libraries. The SSL/TLS strength and algorithm used is determined by the negotiation between the connecting parties. On Windows, the portal engine uses Microsoft SSL libraries.

### About Encryption

Generally speaking, encryption is the process of converting plain text into code in order to prevent any but the intended recipient from seeing that data. There are many types of data encryption, and they are a key element of network security. For portals, encryption is important in three primary contexts. These are:

- Data transmitted between a user's Web browser and the Portal component; this is the most important context, since data might pass over the Internet.
- Data transmitted between the Portal component and other Web services that are components of your solution. In this case, a physically secure network is the ideal solution. Secure tunnels or virtual private networks can also be used. Encryption should only be used if physical security cannot be implemented; that is, different organizations control the servers, or they are physically separated.
- Data persisted by the portal.

For the first two cases, SSL provides a convenient, standard means of encrypting any data transmitted over HTTP. ALI uses an alternate mechanism for encrypting persistent sensitive data.

#### Encryption of Persistent Data

ALUI provides a means of encrypting sensitive information that is persisted to any of a variety of repositories (for example, the ALUI database, the Windows registry, configuration files).

Data stored by ALUI components are most commonly encrypted using a 128-Bit AES algorithm. The algorithm is fixed in the software and cannot be altered. This encryption represents the final line of defense; however, additional measures are strongly recommended to secure this data, such as:

- Both the repository and the communication channel can be secured independently using vendor-specific techniques (for example, Oracle Advanced Networking Option and data encryption)
- The database server should live in a cold room, physically isolated from other computers, on an isolated subnet where it can only talk to other ALUI servers.

### About Public Key Infrastructure (PKI)

#### Public Key Cryptography

PKI systems use two mathematically related keys known as the public key and the private key. The public key can be distributed publicly without compromising the security of a system, as long as the private key remains secret. Anyone can use the public key to encrypt a message such that only someone with access to the private key can read it. Of more importance to this discussion, someone with access to the private key can digitally sign a message. Anyone can read a digitally signed message and can use the public key to verify that it was signed with the private key, proving the identity of the author.

##### Attack 1: The Imposter and the Bank

Suppose a bank receives an e-mail message directing the transfer of $10,000 from a particular account to a numbered Swiss bank account. The message is, purportedly, from a bank customer and is digitally signed. The bank officers attempt to verify the digital signature, but, as they have never received e-mail from that particular customer before, they do not have the customer's public key in the system. The e-mail contains a link to a public key server, so the officials follow the link, look up the key, and use it to verify the signature. Everything checks out, so they transfer the money to the account of the impostor who has just robbed the bank customer's account.

How? The impostor set up a key server and entered his own public key under the bank customer's name, then signed the directive using his own private key. The signature is perfectly valid since the public and private keys correspond. The bank was fooled into thinking the impostor's public key was that of the customer, making the directive seem genuine.

##### Defense: X.509 Digital Certificates

The X.509 digital certificate standard was designed for a single purpose: to certify the owner of a public key. A certificate contains a public key and the name and contact information of its owner, all signed by a trusted certificate authority. The certificate authority has taken steps to ensure the bank customer's identity before issuing the certificate, and, verifying the authority's digital signature ensures that the certificate is not a forgery.

Returning to the example above, the impostor will be unable to obtain a certificate for his public key in the name of the bank customer from a reputable authority. If he tries to use his own certificate, the bank officials will note that the owner of the key is not the purported signer of the e-mail and block the transaction.

##### Attack 2: Using a Digital Certificate to Prove Identity

Suppose the bank receives another e-mail directing a transfer, again purporting to come from one of its customers. This message is not digitally signed, but attached is a copy of the customer's X.509 digital certificate. The certificate contains the customer's name and address and is properly signed by a trusted certificate authority. Should the bank officers approve the transfer?

No, not if they understand PKI. A public key is, by definition, public information. For people to verify a signature, the owner of the signature posts it to public key servers and distributes it to anyone who asks. The message could have come from anyone who has access to a computer.

##### Conclusion: Signed and Certified

To be confident of identity in a PKI system, two pieces of information are needed:

- A valid certificate, proving ownership of the public key
- A valid signature, proving knowledge of the corresponding private key

SSL employs both of these pieces of information to provide secure client authentication as an optional part of the SSL handshake. If requested by the server, an SSL client provides a copy of its client certificate and digitally signs a digest of the handshake. An impostor can easily supply a copy of a stolen certificate, but cannot forge the signature without knowing the corresponding private key.

### About Delegation and Portals

Delegation is a technical term for a process in a computer security system that allows a system to act on behalf of a particular user, particularly when accessing other systems. As an example, consider an e-mail portlet in a portal. When the portal system attempts to access the e-mail system, the latter will respond with a challenge for credentials. At this point, the portal can prompt the user for credentials or use credentials stored earlier. What you want to be able to do, however, is delegate to the portal system the authority to access the e-mail system on your behalf. This grant of authority should last only as long as you are connected to the Portal component and should not require storing credentials permanently. Kerberos is an excellent example of a system that permits this sort of delegation.

#### PKI Does Not Permit Delegation

In any PKI system, the private key is jealously guarded, since access to it grants the privilege of signing messages. Since signing messages is the only way to prove identity within PKI, the only way to delegate authority is to share the private key. This is not controlled, secure delegation, but rather an unlimited, permanent grant of authority.

#### Application to Portals

Returning to the portal example cited previously, consider the case where the portal has been configured to authenticate using the client certificate option of SSL. When a user connects a Web browser, it sends a signed message accompanied by the user's certificate, and these together prove the user's identity to the portal. Can the portal now pass the user's certificate on to the e-mail system to retrieve mail? No, for the same reason the bank officials will reject attack 2. If the e-mail system accepted the certificate as proof of identity, anyone could easily access an e-mail account using the publicly available certificate.

So, to access e-mail on a user's behalf, the portal system needs the private key, which it does not have after the SSL handshake. Browsers do not supply any automatic way to transfer this key (nor should they), so the user needs to go through some configuration process of extracting the private key from the key store on the local machine and uploading it to the portal for storage. The user would either repeat this process on every login or allow the portal to store the certificate permanently. In the latter case, the portal becomes a holding point for every certificate in the system, a sort of master key room, which can potentially grant a hacker access to every system as any user.

#### Using PKI in Your Portal

Delegation is the major problem, but digital certificates have other drawbacks as a portal single-sign-on solution:

- Digital certificates are hard for users to set up. While the Web browser might come with support for certificates, the user still needs to install a personal certificate.
- What about users accessing from multiple computers, including, for example, an airport kiosk? Either administrators must prohibit this, severely restricting functionality, or users must remember to uninstall their certificates or risk leaving their credentials installed on public machines.
- Certificates are generally valid for many days, or even years, after they are issued. This creates the problem of certificate revocation, as an organization will want to cancel a certificate before the expiration date if an employee leaves or a certificate is stolen or compromised. Doing this requires issuing and maintaining certificate revocation lists, which are not yet standardized and create administrative and performance issues.

### Complete Solution: PKI with an SSO Server

The BEA OEM version of Oblix NetPoint SSO software supports the use of digital certificates to securely and transparently authenticate against the SSO server, which then issues a delegable credential (in the form of an HTTP cookie). Using out-of-the-box configuration options, the portal can accept this credential for user authentication and forward it to selected portlet web services. Further, the Oblix NetPoint product provides tools to simplify the process of issuing and managing certificates and can be configured to accept other forms of authentication (for example, passwords) for users on the road without access to their desktop certificate. To implement this option, consult the Oblix documentation to enable and deploy PKI within that system.

ALUI also supports integration with SSO products from other vendors.

#### Stand-Alone Solution without Delegation

In the absence of a cookie-based SSO solution, there are two approaches to configuring the portal to accept client certificates for authentication. Both require using SSL on the login page (security modes 1, 2, or 3). When using certificates tied to Windows domain accounts, you can configure IIS to accept client certificates and then use the out-of-the-box Windows SSO configuration on your portal. This is the easiest approach to take since it leverages the built-in features of Windows, and is the recommended approach whenever possible. To accept certificates from users unrecognized by IIS, you will need to implement a custom SSO solution, which entails writing a custom SSO vendor class in Java or C#.

#### Summary

You can install server digital certificates on any ALUI component (Administrative Portal, Portal, Remote Servers, and so on) and enable SSL. ALI supports SSL between browser and server as well as between a Portal component and Remote Servers.

You can use a digital certificate and SSL to communicate with your LDAP server.

You can use client digital certificates with SSL to authenticate users to the portal. This can be done with Windows Integrated SSO, with a custom SSO solution, or in conjunction with a supported third-party SSO product (for example, Netegrity, Oblix).

The portal cannot "passthrough" digital certificates to Remote Servers. This is impossible because SSL does not permit delegation.

You can do SSO to portlet Web services and use digital certificates to log in to the portal, but only if you use a third-party SSO product that supports both cookie-based SSO and digital certificates (this includes Oblix WebGate and Netegrity SiteMinder). In this case, users use the digital certificate to log in to the SSO server and obtain the SSO cookie, and ALI accepts the SSO cookie and forwards it to portlet Web services.

### Setting Up SSL

There are several steps involved in setting up SSL for your deployment. This section provides a brief overview of the steps you need to complete.

1. Set up SSL on the Web servers or SSL accelerators that run the Portal component and Image Service. Refer to your Web server or application server documentation for instructions on setting up SSL and creating, signing, and installing an SSL certificate.
2. Configure the Portal component by editing the configuration file—j_config.xml for Java deployments, n_config.xml for .NET deployments. The configuration file is located in your portal installation directory, for example, \settings\config\j_config.xml.

1. Make sure HTTPSecurePort and HTTPort are set to the ports you want to use.
2. Change ApplicationURL0 from `*` to

    http://computer_name:port_number/portal/server.pt.

Note: | You do not need to include the port_number for .NET deployments.

3. Change SecureApplicationURL0 from * to

    https://computer_name:port_number/portal/server.pt.

Note: | You do not need to include the port_number for .NET deployments.

4. If you have more than one URL mapping entry, you might need to change those entries as well. Refer to the comments in the configuration file for more information on URL mapping.
5. Change SecurityMode from 0 to 1, 2, or 3.
6. Change ImageServerSecureBaseURL from http to https, and change the Image Service port to the correct one.

3. If you set the IMAGESERVERCONNECTIONURL in the portal configuration file to an Image Service running in SSL (not recommended) you must import onto the Portal component the certificate of the CA that signed the certificate used by the Image Service. For details, see Importing CA Certificates into the Keystore.

Note: | If you have any portlets or Remote Servers that use JSControls or Adaptive Portlets you must also import the CA certificate into those runtimes. (The JSControls libraries are embedded in server and IDK products and are initialized by HTTP-downloading an XML configuration file from the Image Service.)

4. If you have a Remote Server (a server running remote Web Services such as portlets, authentication sources, profile sources, or Content Services) running in SSL, you need to import onto the Portal component the certificate of the CA that signed the certificate used by the Remote Server.
5. If you are running Publisher, Workflow, Collaboration, or Studio, refer to the following sections to configure them to use a secure Image Service and Portal:

- Setting Up Publisher to Use a Secure Image Service or Portal
- Setting Up Workflow to Use a Secure Image Service or Portal
- Setting Up Collaboration to Use a Secure Image Service
- Setting Up Studio to Use a Secure Image Service or Portal

#### Importing CA Certificates into the Keystore

##### Importing CA Certificates into the cacerts Keystore (for Java Portals)

For each machine that makes requests to a secured server running in SSL, you must import into the cacerts keystore the certificate of the CA that signed the certificate used by the secured server:

1. On the machine that makes requests to a secured server, open a command prompt.
2. Copy the CA certificate to this machine.

To obtain the CA certificate, navigate to the CA and save the .der encoded certificate file as a .cer file; you might want to use imgsvr.cer for an Image Service or portal.cer for a Portal, or you might want to use the server hostname.

3. Import the certificate:

    keytool -v -import -trustcacerts -alias CA_alias -file CA_certificate_path -keystore cacerts_keystore_path

Replace the variables with the following information:

- CA_alias - the alias for your CA, for example, verisign or the server hostname
- CA_certificate_path - the path and filename to the CA certificate you copied to the Portal component
- cacerts_keystore_path - the path to your cacerts keystore, located at "jre\lib\security\cacerts" in the home of the JVM that runs your Java application server, for example:

- For Tomcat, jakarta-tomcat-4.1.30-LE-j2sdk1.4.1_05-win32\j2sdk1.4.1_05\jre\lib\security\cacerts
- For WebLogic, bea\weblogic700\server\lib\cacerts
- For WebSphere, java\jre\lib\security\cacerts

4. Enter the password to the cacerts keystore.

##### Importing CA Certificates into MMC (for .NET Portals)

For each machine that makes requests to a secured server running in SSL, you must import into the MMC the certificate of the CA that signed the certificate used by the secured server:

1. On the machine that makes requests to a secured server, open a command prompt.
2. Copy the CA certificate to this machine.

To obtain the CA certificate, navigate to the CA and save the .der encoded certificate file as a .cer file; you might want to use imgsvr.cer for an Image Service or portal.cer for a Portal, or you might want to use the server hostname.

3. Open MMC:

    C:\>mmc

4. Click Console | Add/Remove Snap-in.
5. Click Add.
6. Click Certificates.
7. Click Computer Account and then click Next.
8. Click local computer and then click Finish.
9. Click Close to close the Add Standalone Snap-in dialog box.
10. Click OK to close the Add/Remove Snap-in dialog box.
11. In the MMC tree, expand to Console Root | Certificates | Trusted Root Certificate Authorities | Certificates.
12. Right-click Certificates and select All Tasks | Import.
13. Click Next.
14. Select your certificate.
15. Click Next.
16. Choose to place all certificates in the following store: Trusted Root Certification Authorities.
17. Click Next and then click Finish.
18. Restart IIS.

#### Setting Up Publisher to Use a Secure Image Service or Portal

1. If you are using a secure Image Service:

1. In a text editor, open content.properties (located in your Publisher installation directory, for example, C:\Program Files\plumtree\ptcs\6.0\settings\config\
   content.properties).
2. Change Image Service entries:

- If you are using Security Modes 1 or 2, find and replace all occurrences of http://machine_name/imageserver with https://machine_name/
  imageserver, where machine_name is the name of the machine hosting Publisher.
- If you are using Security Mode 3, change the Image Service entries as follows (note that some variables use http and some use https):

- `CommunityImagePublishBrowserLocation=https://machine_name/imageserver/plumtree/portal/templates`
- `CommunityImagePreviewBrowserLocation=https://machine_name/imageserver/plumtree/portal/templates/preview`
- `CommunityStyleSheetListURL=http://machine_name/imageserver/plumtree/common/public/css/community-themes.txt`
- `JSComponents.AlternateImageServerUrl=http://machine_name/imageserver`

If the Image Service is on Java, be sure to change the port to the correct one (for example, `https://machine_name:ssl_port_number/imageserver`).

2. If you are using Security Modes 1 or 2, import the certificate of the CA that signed the Image Service and/or Portal certificate into Publisher. For details, see Importing CA Certificates into the Keystore.
3. If Publisher runs on WebSphere against a .NET portal in Security Mode 1, complete the following steps:

1. Open the WebSphere Admin console.
2. Navigate to the Default Server.
3. Click the JVM Settings tab.
4. Under System Properties, click Add (this should add a line).
5. For Name type "java.protocol.handler.pkgs" and for Value type "com.ibm.net.ssl.www.protocol".

4. Restart Publisher.

#### Setting Up Workflow to Use a Secure Image Service or Portal

1. If you changed the AlternateImageServerURL in the content.properties file, perform the following steps so that Publisher can communicate the alternate Image Service URL to Workflow:

1. Restart Publisher. This writes the URL to Workflow.
2. After Publisher has restarted, restart Workflow. This forces the Workflow Web application to re-query Publisher for the alternate Image Service URL.

2. Import the certificate of the CA that signed the Image Service and/or Portal certificate into Workflow. For details, see For details, see Importing CA Certificates into the Keystore.

#### Setting Up Collaboration to Use a Secure Image Service

Collaboration does not require any changes to function in security modes 1 or 2, as it uses the portal's Image Service settings. A certificate is not required.

If you are using Security Mode 3, import the certificate of the CA that signed the Image Service and/or Portal certificate into Collaboration. For details, see Importing CA Certificates into the Keystore.

However, if the host/port of the normal Image Service URL used by browsing users is not accessible from Collaboration (for example, the Image Service is on a different machine than Collaboration), you must change the jscontrols component that Collaboration uses. The symptom of this problem is error messages displayed in the Calendar portlets. To avoid the errors:

1. In a text editor, open config.xml (located in your Collaboration installation directory, for example, C:\Program Files\plumtree\ptcollab\5.0\settings\config\config.xml).
2. In the following line set the URL to the value in the portal configuration file (j_config.xml or n_config.xml).

    <jscontrols>

    <imageServerConnectionURL>[URL]</imageServerConnectionURL>

#### Setting Up Studio to Use a Secure Image Service or Portal

Import the certificate of the CA that signed the Image Service and/or Portal certificate into Studio. For details, see Importing CA Certificates into the Keystore.

#### Troubleshooting

Component | Guidelines
--- | ---
KeyTool | If the keytool command is not recognized, it might be because Java is not in your path. Change your directory to the Tomcat installation directory, for example, C:\Program Files\jakarta-tomcat-4.1.18-LE-j2sdk1.4.1_02\j2sdk1.4.1_02\jre\bin. If, when running the keytool command, you get an "alias already exists" error, change your command's "-alias" argument to use a different alias.
Publisher | The following errors indicate that Publisher has not been set up with SSL: Workflow Tracker portlet displays "Unable to display this page" The Community Templating Style Sheets, Community Branding Image Publishing Target, and Community Branding Image Preview Target display "Write Channel Closed, possible SSL handshaking or trust failure." Attempts to create a content item or branding portlet display an http status 500 error: `org.apache.jasper.JasperException: jscomponent file for jscontrols not found or failed to load. Exceptions encountered: com.plumtree.openfoundation.io.XPIOException: java.security.cert.CertificateException: Couldn't find trusted certificate - com.plumtree.openfoundation.io.XPIOException: Unexpected end of file from server` Navigating to the image directory of the Community Directory Section in Publisher Explorer displays a blank page when trying to view the images.
Workflow | If Workflow portlets are not displayed when using an alternate Image Service URL, refer to Knowledge Base article 230242. If the My Activities portlet displays "`An unknown error has occurred`", the Workflow Server is not working. Import the certificate of the CA that signed the Image Service and/or Portal certificate into the Workflow Server JRE

####

## Single Sign-On Options

Single sign-on (SSO) has many different meanings in different contexts. It can mean protecting your Web server with a product from an SSO vendor, such as Oblix. It can mean preventing your users from having to enter credentials more than once, or at all. It can mean identity management or a way to store credentials for many systems to simplify user experience and administrative management. Usually it means some combination of these notions.

The key to understanding your SSO requirements is realizing that the portal is based on a loosely coupled architecture; different tiers of components communicate with each other, primarily over HTTP. The end-user connects to the portal tier over HTTP; the portal connects to numerous other systems over HTTP, including many systems that act on behalf of the end-user. The key is to make this simple for the end-user, simple enough for the administrator, and secure enough for the security team.

### Delegating to Remote Authentication or SSO

When users point their browsers at the portal, the default experience is for users to be presented a login screen. This login screen allows users to authenticate against any authentication source, which might be a remote system such as LDAP, the portal database, or an SSO provider.

When delegating authentication to an LDAP authentication source, the portal can be configured to keep the user credentials in a safe location within memory for later use. The sequence of events for LDAP is as follows:

1. User goes to portal HTTP address; enters credentials.
2. Portal stores credentials in safe section of memory.
3. Portal sends request to LDAP authentication source.
4. LDAP authentication source returns OK.
5. User is granted access to their profile in the portal.

Delegating authentication to an SSO source can circumvent the ALUI login screen and engage the end-user in the SSO login mechanism (could be a login screen, a key card, or some other mechanism). Common SSO sources include Oblix, Netegrity, and Windows Integrated Authentication (WIA). The sequence of events for Oblix would go something like this:

1. User goes to portal HTTP address.
2. Oblix intercepts this HTTP request, realizing user is missing a cookie. If user already has cookie, skip to Step 6.
3. Oblix redirects to Oblix server.
4. Oblix server authenticates; sets browser cookie.
5. Oblix redirects to original HTTP address.
6. Oblix intercepts this HTTP request, recognizes valid cookie and instructs ALUI to grant user access to their profile.

In both cases the authentication was delegated to an external source. In both cases this was likely ultimately delegated to LDAP. In the first case, however, the portal has the user's password for later use (if configured to do so). In the second case, the SSO vendor might have employed any of several authentication mechanisms that it supports, whether login screen or keycard.

### Logging in to the Portal with Auto-Authentication

When using Windows Integrated Authentication, the user must be logged in to a machine on a Windows network. The browser on this machine is smart enough to pick up the user's identity, so the browser can negotiate with the portal to establish the users credentials. The sequence of events for WIA is as follows:

1. User logs onto a Windows network; opens a browser.
2. User goes to portal HTTP address.
3. Portal challenges the browser with an WIA challenge (401 Unauthorized).
4. The browser asserts an encoded piece of information (Negotiate).
5. The portal challenges the browser with a piece of information (Challenge).
6. The browser asserts another encoded piece of information (Response).
7. WIA accepts the user's HTTP request; if the credential were incorrect, the user would be challenged with a login screen in Step 6.
8. The portal accepts the user's identity brokered by WIA and grants user access to their profile.

Notice that the portal was never able to capture the user's password, and the user needed to be logged in to a Windows network for the authentication to succeed. Additionally, a multi-pass handshake occurred between the browser and the portal. Companies often request that the portal be able to repeat this WIA authentication between the portal and the remote server. The portal cannot do this, because there is no forwardable token; Although WIA supports not only NTLM but also Kerberos5, which theoretically supports delegation, no supported browsers implement delegation. So, not only is the portal unable to broker this multi-pass handshake, WIA will fail across any HTTP proxy.

Other important considerations when using WIA are that the user must be an Active Directory or Windows user, Internet Explorer or Netscape 7.1+ must be used, and proxies between the browser and portal are not allowed.

#### Brokering Credentials to the Remote Tier

After the user has logged in to the portal, the portal wants to serve the user exciting applications. These applications might be pulling from custom systems as well as enterprise systems such as SAP. Let us discuss how the portal can connect to SAP.

ALI provides a Integration Services- SAP that allows business users to provide SAP functionality in their applications. This extension is a remote component that calls into various SAP APIs. These APIs require a username and password. By default, the extension gives user credentials to the SAP system.

ALUI can pass user credentials in any of several ways:

- Preferences: Users can set credentials as preferences, and these preferences can be sent in the HTTP request. This is useful if SAP runs off of different credentials than the main network and if no mapping exists between SAP credentials and the main user credential (such as LDAP). Preferences are stored in the portal database (encrypted), and controlled by the end-user.
- UserInfo: The administrator can map properties from LDAP or another system into user profiles, and segments of the user profile can be sent as UserInfo. If LDAP contains entries for SAP credentials for each user, then the user will never need to enter their SAP credentials, but the LDAP system will need to be the system of record.
- Lockbox: As part of the Credential Vault, credential pairs can be put in a Lockbox, which ensures that they are never transmitted in clear text. They can be sent to remote services over SSL.
- PassThrough: The login credentials the user provided at login can be sent to the remote tier as a Basic Authentication header. This is very useful if both the portal and SAP are based on a user's LDAP credentials. In this case, all communication between the portal and the remote tier should be over a secure channel (such as SSL) to protect the user password. For this method to work, the password had to be captured on login, which was not the case with the NTLM or Oblix examples described previously.
- SSO: An SSO token can be forwarded to the remote tier. This will not, however, let the SAP extension log in to SAP unless the SAP API accepts the SSO token as a valid user login. The SAP API that ALI uses (JCO) is not enabled to accept tokens of third-party SSO systems, such as Oblix. Systems such as Oblix can be used in conjunction with the SAP extension, but Preferences, UserInfo or PassThrough will need to be used to log in to SAP. It may be necessary, however to forward the SSO token if the remote server has been protected by Oblix; in this case, without the SSO token, the portal's request will be rejected. Also, the SSO token can be used with an SSO vendor API to reconvert to name and password, but this is highly dependent on the SSO vendor and the particular company configuration of the SSO software.

### Summary

The following table summarizes some features of different SSO options.

Feature | No SSO | Oblix | Netegrity | WIA | Custom
--- | --- | --- | --- | --- | ---
Can use windows identity | X | ¸ | ¸ | ¸ | C
Auto-login to all systems | C | C | C | C | C
Remember password | ¸ | ¸ | ¸ | ¸ | C
Forward password to remote tier | ¸ | C | C | X | C
Forward SSO token to remote tier | X | ¸ | ¸ | X | C
Supports X.509 client certificates | X | ¸ | ¸ | ¸ | C
Supports two-factor authentication | X | ¸ | ¸ | X | C
Supports non-windows applications | ¸ | ¸ | ¸ | X | C

¸ = out of box

C = custom work required

X = not supported