# Administrator Guide

# Common Questions and Answers

This appendix includes the following sections:

- SSO FAQ
- Other FAQ

## SSO FAQ

This section provides answers to common deployment issues in question and response format.

Question: Why does SSO not work for a particular user?

Answer: Examine the following settings or events to diagnose the cause of this problem:

- In portalconfig.xml, the user name prefix must match the value for the Authentication Source Category set in the Authentication Source portal object. Ensure these strings are identical.
- Use AquaLogic Interaction Logging Spy to see if the SSO authentication server is passing the user name to the portal. If you see an error message in red type that indicates "SSO integration returned a null user name. Exiting SSOLoginPage," then there is something wrong with the configuration. Make sure you have configured the authentication server correctly to forward the user name after authentication to the portal. See Configuring AquaLogic Interaction Logging Spy for more information.

Question: Why isn't the SSO cookie forwarded to remote servers or portlets?

Answer: Examine the following settings or events to diagnose the cause of this problem:

- In portalconfig.xml, ensure the value of the <CookieDomain> element begins with a period.
- In portalconfig.xml, ensure the value of the <CookiePath> element is the standard value, `<CookiePath value="/"/>`, or otherwise is a reasonable value.
- In the authentication server, ensure the value of the cookie object enables the cookie to be forwarded.
- Examine the configurations for the authentication server and the portal to ensure fully qualified domain names are specified for all servers.
- If you are unable to diagnose the problem with these methods, use a TCP tracing tool to see the value returned by the SSO provider. The path and domain must match the values for <CookiePath> and <CookieDomain> in portalconfig.xml.

Question: Does the portal with SSO support guest user access?

Answer: Guests can access the portal while SSO is enabled. Guest access is controlled by the AllowGuestAccess setting in the Authentication section of portalconfig.xml. When guest access is disabled, users can browse the portal without logging in. When users click Login in the portal banner or when they attempt to visit a page for which the guest user does not have access, the portal redirects them to the SSO login page, and they are prompted by the SSO product for their login credentials.

If users already have an SSO cookie from another application, they still browse the portal as the guest user until they click Login. At which point, they are logged in without entering their user name and password.

Guest access can be enabled or disabled independently from SSO. If guest access and SSO are both disabled, users have to log in before accessing any part of the portal.

Question: How can a user change login credentials, for example, to become Administrator?

Answer: If users need to log in as Administrator or other portal users from within their SSO session, they can click Log Off in the portal banner. This logs them out of the portal and takes them to the portal login page, as if SSO were disabled. From this page they can log in as a non-SSO user or they can browse the portal as guest. When they want to log back in as an SSO user, they can click Login in the portal banner and they are automatically logged in to the portal.

Question: Why can't I access the portal through SSOLogin.aspx or the SSOServlet?

Answer: The first time you access the portal after you deploy SSO, you must access the portal from the main portal URL: http://<servername>/portal/Server.pt.

If you try to access the portal through /portal/sso/SSOLogin.aspx (.NET) or /portal/SSOServlet (Java), your request fails and the following error appears in AquaLogic Interaction Logging Spy trace logs: "The SSO Login Page was unable to retrieve the request URL from the session. Will use a relative redirect to return to the main page."

Question: If I configure my SSO authentication server to protect the Image Service virtual directory, users encounter JavaScript errors and portal menus fail to load. Why?

Answer: The portal and other AquaLogic User Interaction products, such as Collaboration and Publisher, periodically send HTTP requests to the Image Service to check the version of the JavaScript components stored on the Image Service. These requests are not associated with a particular user's session and do not send an SSO cookie or other credentials. If the Image Service is protected by your SSO solution, the request from the portal is blocked from checking the JavaScript versions. As a result, the portal is unable to load the proper JavaScript files and end users encounter JavaScript errors and possibly other errant behavior. To resolve this problem, do not configure your SSO authentication server to protect the Image Service, but only the portal. You do not need to protect the Image Service as it contains only static public content that ships with every portal installation. No data specific to users or to your organization is ever stored on the Image Service.

Question: How can I debug my SSO deployment?

Answer: The portal provides built-in trace statements that are useful for debugging SSO integration. For example, when a user attempts to log in using SSO, the contents of all headers are traced. To enable this tracing, turn on all tracing for the Portal UI - Infrastructure component. See Configuring AquaLogic Interaction Logging Spy for more information.

Question: How do I configure reverse proxy with my SSO deployment?

Answer: AquaLogic Interaction has verified deployments with reverse proxy using Apache HTTP server, Oblix Netpoint Access Server (versions 6.1.1 or 6.5) with an Apache WebGate, and a Java-based portal.

Follow these basic steps to complete this configuration:

1. Install Oblix NetPoint Access Server, including NetPoint Access Manager, NetPoint COREid, and Oblix Apache WebGate. WebGate must be installed on the same server as the Apace HTTP server. For detailed instructions, refer to Oblix documentation.
2. Use Oblix Access Manager to create the portal protection policy. For detailed instructions, refer to Oblix documentation.
3. Configure Oblix NetPoint Access Server. For detailed instructions, see Configuring an Oblix Authentication Provider.
4. Configure the Apache HTTP server for reverse proxy. For detailed instructions, see the procedures that follow these steps.
5. Configure the portal for SSO. For detailed instructions, see Configuring the Portal for SSO.
6. Configure the portal application server for reverse proxy. For detailed instructions, see the procedures following these steps.
7. Restart services to apply configuration modifications.

To configure the Apache HTTP server for reverse proxy:

1. Install the version of the Apache HTTP server recommended by the Oblix Installation Guide. For Netpoint 6.5, Oblix recommends the latest version of the Apache, v1.3 line. The configuration described in this example has been tested with version v1.3.29.
2. Turn on the proxy module inside of the Apache configuration). To do so, edit <apache_install_dir>/conf/httpd.conf to uncomment the lines titled LoadModule proxy_module modules/mod_proxy.so and AddModule mod_proxy.c. (to uncomment a line, remove the pound symbol (`#`) at the beginning of the line).
3. Configure Apache to act as a reverse proxy for your portal. To do so, add lines similar to the following example at the end of httpd.conf:
4. ProxyRequests Off
5. ProxyPass /portal http://your_portal_server.domain.com:7001/portal
6. ProxyPassReverse /portal http://your_portal_server.domain.com:7001/portal
7. This example configuration redirects requests from the Apache Web server (http://proxy_server.domain.com:80/portal/xyz) to the portal application server (http://your_portal_server.domain.com:7001/portal/xyz).
8. You must specify the fully qualified domain name here and for all other times you type in the server names.
9. For more information on Apache reverse proxy, see http://httpd.apache.org/docs/mod/mod_proxy.html.
10. Start or reboot the Apache HTTP server.

To configure the Java application server for reverse proxy:

1. Open PT_HOME/ptportal/6.1/settings/config/portalconfig.xml for editing.
2. Configure the <URLMapping> element so that it is similar to the following example:

    <URLFromRequest0 value="*"/>

    <ApplicationURL0 value="http://proxy_server.domain.com/portal/server.pt"/>

    <SecureApplicationURL0 value="*"/>

Replace `proxy_server.domain.com` with the fully qualified domain name for the Apache HTTP server.

3. Configure the <SSOVirtualDirectoryPath> element so that it is similar to the following example:

    <SSOVirtualDirectoryPath value="http://proxy_server.domain.com/portal/"/>

Replace `proxy_server.domain.com` with the fully qualified domain name for the Apache HTTP server.

4. Reboot the application server.

## Other FAQ

Question: I get a timeout error when I edit a folder in the Knowledge Directory, change the Security page, and try to apply the security changes to all child objects of the folder.

Answer: This problem may occur if you have many levels of nested subfolders with a large number of child objects (other folders or documents). To work around this problem if it occurs:

1. To find out which folders are updated with the security changes, select all first level subfolders then select the security icon.
2. Scroll through the list to see at which folder the security changes stopped being applied.
3. Work with the remaining folders and apply the needed security changes: open each first level folder separately, set the security, save, and select Yes to apply the security changes to all the child objects for that folder.
4. Repeat this process for all remaining first level subfolders that did not get the security applied to them successfully due to the error.