D Deploying Single Sign-On

This appendix describes how to deploy Single Sign-On (SSO) capabilities in the portal environment.

Common SSO Questions

This section contains links to common SSO questions and the answers.

Why Can't I Access the Portal Through SSOLogin.aspx or the SSOServlet?
How Can I Debug My SSO Deployment?
Does the Portal with SSO Support Guest User Sessions?
Why Do Users Get JavaScript Errors and Portal Menus Fail to Load if I Configure the SSO Authentication Server to Protect the Image Service Virtual Directory?
How Can I Change Login Credentials From an SSO Session?
Why Isn't the SSO Cookie Forwarded to Remote Servers or Portlets?
Why Doesn't SSO Work for a Particular User?
How Do I Configure Reverse Proxy with My SSO Deployment Using Apache HTTP Server?
How Do I Configure Reverse Proxy with My SSO Deployment Using a Java Application Server?
How Do I Configure Reverse Proxy with My SSO Deployment Using Oblix Netpoint Access Server (versions 6.1.1 or 6.5) with an Apache WebGate?

Why Doesn't SSO Work for a Particular User?

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 Oracle WebCenter 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.

Why Isn't the SSO Cookie Forwarded to Remote Servers or Portlets?

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.

Does the Portal with SSO Support Guest User Sessions?

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 Log In 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 Log In. 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.

How Can I Change Login Credentials From an SSO Session?

If you need to log in as Administrator or other portal user from within an SSO session, you can perform the following steps:

Click Log Off in the portal banner.

This logs you out of the portal and takes you to the portal login page, as if SSO were disabled.
From this page you can log in as a non-SSO user or you can browse the portal as guest.
When you want to log back in as an SSO user, click Log In in the portal banner.

You are automatically logged in to the portal in an SSO session.

Why Can't I Access the Portal Through SSOLogin.aspx or the SSOServlet?

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 Oracle WebCenter 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.

Why Do Users Get JavaScript Errors and Portal Menus Fail to Load if I Configure the SSO Authentication Server to Protect the Image Service Virtual Directory?

The portal and other Oracle WebCenter products, such as Oracle WebCenter Collaboration, 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.

How Can I Debug My SSO Deployment?

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.

How Do I Configure Reverse Proxy with My SSO Deployment Using Oblix Netpoint Access Server (versions 6.1.1 or 6.5) with an Apache WebGate?

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 Apache HTTP server. For detailed instructions, refer to Oblix documentation.
Use Oblix Access Manager to create the portal protection policy. For detailed instructions, refer to Oblix documentation.
Configure Oblix NetPoint Access Server. For detailed instructions, see Configuring an Oblix Authentication Provider.
Configure the Apache HTTP server for reverse proxy. For detailed instructions, see the procedures that follow these steps.
Configure the portal for SSO. For detailed instructions, see Configuring the Portal for SSO.
Configure the portal application server for reverse proxy. For detailed instructions, see the procedures following these steps.
Restart services to apply configuration modifications.

How Do I Configure Reverse Proxy with My SSO Deployment Using Apache HTTP Server?

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.
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).
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:
```
ProxyRequests Off
ProxyPass /portal http://your_portal_server.domain.com:7001/portal
ProxyPassReverse /portal http://your_portal_server.domain.com:7001/portal
```
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). You must specify the fully qualified domain name here and for all other times you type in the server names. For more information on Apache reverse proxy, see http://httpd.apache.org/docs/mod/mod_proxy.html.
Start or reboot the Apache HTTP server.

How Do I Configure Reverse Proxy with My SSO Deployment Using a Java Application Server?

Open Install_Dir/ptportal/10.3.0/settings/config/portalconfig.xml for editing.

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.
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.
Reboot the application server.