30.1 Introduction to Single Sign-on

Single sign-on can be implemented for WebCenter applications using several solutions. This section describes their benefits and recommended application.

Oracle Access Manager (OAM), part of Oracle's enterprise class suite of products for identity management and security, provides a wide range of identity administration and security functions, including several single sign-on options for WebCenter Spaces and WebCenter Portal applications. OAM (in particular, OAM 11g) is the recommended single sign-on solution for Oracle WebCenter 11g installations.

For deployment environments that are already invested in Oracle 10g infrastructure, and where the Oracle Application Server Single Sign-On (OSSO) server is used as the primary SSO solution, WebCenter 11g can also be configured to use OSSO for single sign-on.

For non-production, development environments where you do not have an enterprise-class single sign-on infrastructure like Oracle Access Manager or Oracle SSO, and you only need to provide a single sign-on capability within WebCenter Spaces and its associated Web applications like Discussions, and Worklist, you can configure a SAML-based SSO solution. If you need to provide single sign-on for other enterprise applications as well, this solution is not recommended.

If your enterprise uses Microsoft desktop logins that authenticate with a Microsoft domain controller with user accounts in Active Directory, then configuring SSO with Microsoft Clients may also be an option to consider.

30.2 Configuring Oracle Access Manager (OAM)

Oracle Access Manager (OAM) provides flexible and extensible authentication and authorization, and provides audit services. This section describes how to configure WebCenter Spaces and WebCenter Portal applications for OAM single sign-on authentication, including how to configure the WebLogic server side and the WebCenter application as the partner application participating in SSO.

The installation and configuration steps for OAM 11g and 10g are presented in the following subsections:

Access Server - a standalone server that provides authentication, authorization, and auditing services for Access Gates. There is one access server set up on OAM. This is done as part of the OAM install itself.

WebGate - an out-of-the-box plugin that intercepts Web resource (HTTP) requests and forwards them to the Access Server for authentication and authorization.

Identity Assertion Provider (IAP) - a type of security provider that asserts the identity of the user based on header information that is set by perimeter authentication. The OAM integration provides an OAM ID Asserter that can be configured as the OAM IAP. The OAM ID Asserter can be used for authentication or for identity assertion. For OAM SSO integration, the OAM ID Asserter should be configured as an Identity Assertion Provider (IAP) by selecting obSSOCookie under Active Types in the provider's Common settings.

WebGate prompts OAM to look up policies, compare them to the user's identity, and determine the user's level of authorization.

OAM logs policy decision and checks the session cookie.

OAM Server evaluates authorization policies and cache the result.

OAM Server logs and returns decisions

WebGate responds as follows:

If the authorization policy allows access, the request get redirected to mod_wl which in turn redirects the request to the WLS server where the WebCenter Spaces application is running, and from where desired content or applications are served to the user, as shown below:

Where <Webgate_Oracle_Home> is the directory where you have installed Oracle HTTP Server WebGate and defined it as the Oracle Home for WebGate, as in the following example:

<MW_HOME>/Oracle_OAMWebGate1

The <Webgate_Instance_Directory> is the location of the Webgate Instance Home (which should be the same as the Instance Home of Oracle HTTP Server), as in the following example:

<MW_HOME>/Oracle_WT1/instances/instance1/config/OHS/ohs1

Note that an Instance Home for Oracle HTTP Server is created after you configure the Oracle HTTP Server. This configuration should be performed after installing or patching to Oracle HTTP Server 11.1.1.4.0.

Run the following command to ensure that the LD_LIBRARY_PATH variable contains <Oracle_Home_for_Oracle_HTTP_Server>/lib:

Add the <Webgate_Installation_Directory>\webgate\ohs\lib and <Oracle_Home_for_Oracle_HTTP_Server>\bin locations to the PATH environment variable. Add a semicolon (;) followed by this path at the end of the entry for the PATH environment variable.

From your current working directory, move up one level:

For Unix operating systems, move to:

<Webgate_Home>/webgate/ohs/tools/setup/InstallTools

For Windows operating systems, move to:

<Webgate_Home>\webgate\ohs\tools\EditHttpConf

From the command line, run the following command to copy the apache_webgate.template from the Webgate_Home directory to the WebGate Instance location (renaming it to webgate.conf) and update the httpd.conf file to add one line to include the name of webgate.conf file:

Copy the generated files and artifacts (ObAccessClient.xml and cwallet.sso) from <RREG_Home>/output/$$webtierhost$$_webcenter to your WebGate instance configuration directory (<Webgate_Instance_Directory>/webgate/config). Note that <Webgate_Instance_Directory> should match the instance home of OHS, as in the following example:

Return to the WebCenter REST Auth Policy created above, add all the /rest entries you removed and click Apply. REST needs to follow the BASIC authentication scheme so that external clients, such as the Outlook plugin and iPhone application, can connect to WebCenter REST and be protected with SSO.

Click Access Server Configuration to display a list of all access servers.

Click an access server in the list to see server details.

The host name and port are the values you need for the oam_aaa_host and oam_aaa_port parameters respectively in the script.

Run the following command.

The oamcfgtool.jar is available in ORACLE_HOME/modules/oracle.oamprovider_11.1.1/oamcfgtool.jar in the WebCenter installation. Values in bold are the ones that you must supply based on the settings of your WebCenter and OAM instances.

We recommend that you register your domain (for <your_domain_name>) as something like "webtier.example.com", where "webtier.example.com" is your Web Tier, so that you can easily distinguish the various policies in OAM.

If your command ran successfully, you should see something like the following output depending on the values you used:

You can also run the Validate command to validate your configurations:

java -jar WC_ORACLE_HOME/modules/oracle.oamprovider_11.1.1/oamcfgtool.jar mode=VALIDATE app_domain=<your_domain_name>
ldap_host=<Hostname of LDAP server> ldap_port=<Port of LDAP server>
*ldap_userdn=<DN of LDAP Admin User, usually "cn=orcladmin">*
ldap_userpassword=<Password of LDAP Admin User>
oam_aaa_host=<HOST of OAM server>
oam_aaa_port=<Port of OAM server>
test_username=<Username to be used for policy validation> test_userpassword=<Userpassword to be used for policy validation>

If your command runs successfully, you should see the same output as above.

If your instance also contains a SOA installation, then run oamcfgtool again to protect the SOA URIs in the policy domain you created in the previous step. Use the same parameters as the ones used in the previous step so that the existing policy domain is updated with URIs in the soa.oam.conf file.

If your installation contains Oracle Content Server, then you also need to protect these URIs. Use the same parameters as the ones used in the previous steps so that the existing policy domain is updated with the URIs in the Content Server's oam.conf file.

You should see the domain you just created in the list of policy domains. In the URL prefixes column, you should also see the URIs that were specified as part of the webcenter.oam.conf script file. You should also see the URIs from the SOA and Content Server OAM configuration files if you have run the oamcfgtool from SOA and Content Server domains.

Click the domain you just created and open the Resources tab.

The URIs you specified should display. You can also open other tabs to view and verify other settings, and manually add additional resources later, if required.

Check the Access Gate Configurations.

Click Access System Console.

Open the Access System Configuration tab.

Click AccessGate Configuration.

Enter some search criteria and click Go.

When the Access Gate for the domain you just created displays (it will have the suffix _AG), click it to see the setting details.

Locate the policy domain that you created and verified in the previous steps and open the Policies tab.

You should see two policies already created - Protected_JSessionId_Policy and Default Public Policy

Create another policy called WebCenterRESTPolicy, using the values shown below:

30.2.3.2.4 Installing the WebGate 10g on the Web Tier

This section describes how to install the WebGate.

To install the WebGate:

Copy the ZIP file (Oracle_Access_Manager10_1_4_3_0_linux_GCClib.zip) containing the two gcc libraries required for the installation (libgcc_s.so.1 and libstdc++.so.5) to a /tmp directory. For more information, refer to the chapter on "Installing the WebGate" in the Oracle Access Manager Installation Guide.

Run the installation as root. For example, from the /tmp directory run:

sudo -u root ./Oracle_Access_Manager10_1_4_3_0_linux_OHS11g_WebGate

Follow the installation runtime instructions, providing the installation directory, information of the AccessGate that you created earlier and the absolute path to the httpd.conf file of the web server. For example:

WT_ORACLE_HOME/instances/<your_instance>/config/OHS/ohs1/httpd.conf

Information for the AccessGate can be found in the Access System Console.

After the installation, a new section is inserted in the httpd.conf file between the following entries:

30.2.4 Configuring the WebLogic Domain for OAM

If your environment spans multiple domains (for example, a domain for WebCenter Spaces, a separate domain for SOA, and a separate domain for Oracle Content Server), repeat the steps in this section for each domain.

30.2.4.1 Configuring the Oracle Internet Directory Authenticator

Assuming Oracle Internet Directory is backing the OAM identity store, an Oracle Internet Directory authenticator (OracleInternetDirectoryAuthenticator) should be configured for the LDAP server that is used as the identity store of OAM, and the provider should be set to SUFFICIENT.

30.2.6.1 Configuring WebCenter Spaces for SSO

Configure the WebCenter Spaces application for SSO by adding a setting to EXTRA_JAVA_PROPERTIES.

There is a system property that tells WebCenter and ADF that the application is configured in SSO mode and some special handling is required. The following system property is required in this mode:

Field

Value

Comment

oracle.webcenter.spaces.osso

true

This flag tells WebCenter that SSO is being used, so no login form should be displayed on the default landing page. Instead, it displays a login link that the user can click to invoke the SSO authentication.

To set this property, edit the setDomainEnv.sh script located in your <domain>/bin directory, and add an entry like the following:

This section describes how to update the discussions server connection for WebCenter Spaces so that it uses the Web Tier's host and port values. Note that the steps below assume that the Discussions service has already been installed and configured in the WebCenter domain.

When you log in to WebCenter Spaces, you automatically sign on to the discussion server as well.

30.2.6.3 Configuring the Worklist Service for SSO

Assuming that you've already set up a Worklist connection, modify the URL to use the Web Tier host and port instead of the SOA server host and port. You can do this using Fusion Middleware Control or using WLST commands as described in Section 22.4, "Setting Up Worklist Connections."

After modifying the URL and completing the setup required for OAM SSO, run the following command on the WebCenter Administration server so that the Worklist service changes take effect:

30.2.6.4 Configuring OAM for RSS Feeds Using External Readers

By default, WebCenter RSS feeds are protected by SSO. However, they will not work well with external readers if left protected (external readers will not work at all with OAM 11g protected RSS). If access using external readers is important, Oracle recommends that the WebCenter RSS resource be unprotected so that the authentication for the RSS Servlet is handled by WebLogic Server's BASIC authentication that external readers can handle.

Follow the steps below to unprotect the RSS feeds:

Open the OAM Admin Console.

Select Access System Console > Policy Manager and open the applicable policy domain.

This section describes how to optionally set up OAM single sign-on for the WebLogic Server Administration Console and Enterprise Manager.

Note:

Setting up OAM SSO for Enterprise Manager and the WebLogic Server Administration Console would provide single sign-on access to same set of users for whom OAM SSO access has been configured. If want the Web Tier to be accessible to external users through OAM, but want administrators to log in directly to Enterprise Manager and the WebLogic Server Administration Console, then you may not want to complete this additional configuration step.

To set up OAM SSO for the WebLogic Server Administration Console and Enterprise Manager:

Log in to the OAM Console using your browser to navigate to:

http://host:port/access/oblix

Where host is the host ID of the server hosting the Access Manager (for example, oam.example.com), and port is the HTTP port number (for example, 8888).

In your Web Tier, modify the mod_wl_ohs.conf file (in WT_ORACLE_HOME/instances/<your_instance>/config/OHS/ohs1/) to include the WebLogic Server Administration Console and Enterprise Manager, by adding two additional Location entries using the actual host ID for the WebCenter Administration Server for WebLogicHost.

This section describes how to optionally set up OAM 11g single sign-on for the WebLogic Server Administration Console and Enterprise Manager.

Note:

Setting up OAM SSO for Enterprise Manager and the WebLogic Server Administration Console would provide single sign-on access to same set of users for whom OAM SSO access has been configured. If want the Web Tier to be accessible to external users through OAM, but want administrators to log in directly to Enterprise Manager and the WebLogic Server Administration Console, then you may not want to complete this additional configuration step.

To set up OAM 11g SSO for the WebLogic Server Administration Console and Enterprise Manager:

Log in to the OAM Console using your browser:

http://host:port/oamconsole

Go to Policy Configuration > Application Domains.

The Policy Manager pane displays.

Locate the application domain you created using the name while registering webgate agent.

Expand the Resources node and click Create.

The Resource page displays.

Add the resources that must be secured. For each resource:

Select http as the Resource Type.

Select the Host Identifier created while registering the WebGate agent.

In your Web Tier, modify the mod_wl_ohs.conf file (in WT_ORACLE_HOME/instances/<your_instance>/config/OHS/ohs1/) to include the WebLogic Server Administration Console and Enterprise Manager, by adding two additional Location entries using the actual host ID for the WebCenter Administration Server for WebLogicHost.

You should now be able to access the WebLogic Server Administration Console and Enterprise Manager with the following links:

http://host:OHS port/console
http://host:OHS port/em

and be prompted with the OAM SSO login form.

30.2.6.7 Configuring Oracle Content Server for SSO

Assuming that you've already set up a connection for Oracle Content Server, specify the web context root in the JCRContentServerConnection using Fusion Middleware Control or as per the following WLST example:

setJCRContentServerConnection(appName, name, webContextRoot='/cs')

30.2.6.8 Restricting Access with Connection Filters

Follow the steps below to only allow users to access WebCenter and other services through the Web Tier OHS ports so that they can be properly authenticated.

To configure a custom connection filter, specify the class that implements the network connection filter. Note that this class must also be present in the CLASSPATH for WebLogic Server.

In the Connection Filter Rules field, enter the syntax for the connection filter rules.

For example:

<webtier IP>/0 * * allow
0.0.0.0/0 * * deny

which says: allow all traffic coming from the local host and disallow all traffic from any other IP address. You should, of course, write the network filter(s) that are relevant to your environment. For more information about writing connection filters, see "Developing Custom Connection Filters" in Oracle Fusion Middleware Programming Security for Oracle WebLogic Server.

Click Save and activate the changes.

Restart all the managed servers and the Administration Server.

Verify that all direct traffic to the WebLogic Server is blocked by attempting to navigate to:

http://host:WLS_port/webcenter

This should produce the following error:

"The Server is not able to service this request: [Socket:000445]Connection rejected, filter blocked Socket, weblogic.security.net.FilterException: [Security:090220]rule 3"

You should, however, still be able to access WebCenter through the OHS port:

http://host:OHS_port/webcenter

30.2.7 Testing Your OAM Installation

After installing and configuring either OAM 10g or 11g, check that you can access all of the configured applications below (as they apply to your environment), and that the global login and logout is giving you access to all of your configured applications without prompting you to sign in again. Also test global logout where available and make sure you are logged out of all other related applications.

WebCenter Spaces: Access any protected Spaces URL (a protected Group Space, for example), and make sure that you see the SSO login challenge. If you are already logged into another related application that uses the same SSO, you should automatically be shown content.

REST: Access http://ohshost:ohsport/rest/api/resourceIndex. You should see the BASIC authentication challenge. If you are already logged into another related application that uses the same SSO, you should automatically be shown content.

REST: Access http://ohshost:ohsport/rest/api/cmis/.... (retrieve this from resourceIndex access output in the previous step). You should not see a login challenge and should be able to see public content. When you access this after you've logged in, then you should see all content to which you have access rights.

ActivityGraph Engines: Access http://host:port/activitygraph-engines. You should see an SSO login challenge. Once logged in, you should be able to see content.

OracleContent Server: Go to the profile UI and check that you can see Content Server screens embedded in iFrames without challenging you to log in. You should also be able to access Site Studio content in Content Presenter templates without logging in as you are already logged into WebCenter Spaces application.

SOA: Access links in a workflow task flow and make sure that you are not challenged to log in.

Discussion Forums: Access the Discussions application at http://host:port/owc_discussions and log in. Check that the login is the SSO login challenge. Similarly, the Administration login to the Discussions server at http://host:port/owc_discussions/admin should also go through the SSO login challenge.

30.3 Configuring Oracle Single Sign-On (OSSO)

In a default installation, WebCenter uses the HTTP ports in the Managed Server created for WebCenter. To configure WebCenter with Oracle Single Sign-On, WebCenter needs Oracle HTTP Server and the associated Module mod_osso to integrate with Oracle Single Sign-On (OSSO).

Note:

The BPEL Console does not support SSO integration. When WebCenter is configured for SSO, login to BPEL must still be done through the standard login page on the BPEL Console.

30.3.2 OSSO Components and Topology

In a default installation, WebCenter uses the HTTP ports of the Managed Server created for WebCenter. To configure WebCenter with Oracle Single Sign-On, WebCenter needs the Oracle HTTP Server and the associated Module mod_osso, to integrate with Oracle SSO. The diagram below (Figure 30-19) shows the overall architecture of this integration:

30.3.4 Configuring the OSSOIdentityAsserter

Include the OSSO Identity Assertion Provider (IAP) provider in the Oracle WebLogic domain for WebCenter. Use the WebLogic Server Administration Console to add the OSSO IAP to your domain as shown in the steps below. If your environment spans multiple domains (for example, a domain for WebCenter Spaces, separate domain for SOA, and a separate domain for Oracle Content Server), repeat the steps in this section for each domain.

Enter a name for the new provider, select OSSOIdentityAsserter as its type and click OK.

On the Providers tab, click the newly added provider.

Set the control flag to OPTIONAL.

Ensure that OracleInternetDirectoryAuthenticator (or the primary authenticator you selected when you configured the Identity Store to use an external LDAP) is set as the primary authenticator for the domain so that the user profile can be retrieved from the associated Oracle Internet Directory server. For information about configuring the Identity Store to use an external LDAP, see Chapter 28, "Configuring the Identity Store."

For OID, the provider list should appear as follows:

OSSOIdentityAsserter (OPTIONAL)

OracleInternetDirectoryAuthenticator (SUFFICIENT)

DefaultAuthenticator (SUFFICIENT)

DefaultIdentityAsserter (OPTIONAL)

30.3.5 Registering OHS with Oracle SSO

Register the module mod_osso in the Web Tier OHS with the SSO Server as a partner application by following the steps below.

To register OHS with Oracle SSO:

Run ssoreg from the SSO server to generate an osso.conf file and FTP it in binary mode to the Web Tier host (WT_ORACLE_HOME).

The following example shows how you would register a remote partner application on a SSO Server. Check that the ORACLE_HOME environment variable is set (ORACLE_HOME here is the ORACLE_HOME of the OSSO installation on the SSO server) before running ssoreg.sh.

Copy the WT_ORACLE_HOME/instances/<your_instance>/config/OHS/ohs1/disabled/mod_osso.conf file to WT_ORACLE_HOME/instances/<your_instance>/config/OHS/ohs1/moduleconf. All files in the moduleconf directory are included in the httpd.conf file.

Copy the webtier.example.com.osso.conf file generated by ssoreg in step 1 to a location accessible in the Web Tier other than the moduleconf directory (for example, WT_ORACLE_HOME).

Note:

If using FTP, be sure to transfer the file using binary mode.

Add rules to the mod_osso.conf file to protect the /webcenter and related application resources URLs with Oracle SSO.

30.3.6.5 Configuring Oracle Content Server for SSO

Since it's possible to access the Oracle Content Server repository directly from WebCenter Spaces, you may also want to include it in the single sign-on configuration. Assuming that you've already set up a connection for the Oracle Content Server, specify the web context root in the JCRContentServerConnection using Fusion Middleware Control or using WLST as shown in the following example:

30.3.6.6 Configuring OSSO for RSS Feeds Using External Readers

By default, WebCenter RSS feeds are protected by SSO. However, they will not work well with external readers if left protected. If access using external readers is important, Oracle recommends that the WebCenter RSS resource be unprotected so that the authentication for the RSS Servlet is handled by WebLogic Server's BASIC authentication that external readers can handle.

30.4 Configuring SAML-based Single Sign-on

Security Assertion Markup Language (SAML) enables cross-platform authentication between Web applications or Web Services running in a WebLogic Server domain and Web browsers or other HTTP clients. WebLogic Server supports single sign-on (SSO) based on SAML. When users are authenticated at one site that participates in a single sign-on (SSO) configuration, they are automatically authenticated at other sites in the SSO configuration and do not need to log in separately.

Note:

Although SAML-based single sign-on provides support for logging users onto subsequent applications after initial sign-on, global logout is not supported. Consequently, users must log out of each individual application they open.

Note also that if you set up SAML-based single sign-on with WebCenter Spaces as the source application and Oracle WebCenter Discussions as the destination application, you can access administration pages of the Discussions application from the WebCenter Spaces Manage Group Space Services screen or Configure WebCenter Services screen. However, since the Oracle WebCenter Discussion administration pages do not participate in SSO, if you access administration pages directly, you are required to log in to Oracle WebCenter Discussions again.

Finally, SAML-based single sign-on is not available for the sdpmessaginguserprefs-ui application. As an application administrator, if you click Manage Configuration in the Preferences > Messaging dialog in WebCenter Spaces, you will need to log in again.

This SSO mechanism can be used for departmental WebCenter installations for which there is no existing Oracle SSO or Oracle Access Manager single sign-on infrastructure, but single sign-on between only WebCenter Spaces and its services is required. For High Availability and large enterprise deployments, the Oracle Access Manager SSO configuration is recommended.

This section describes how to set up SAML 1.1-based single sign-on for Oracle WebCenter Spaces and the Worklist service running on different managed servers within the same domain.

30.4.1 SAML Components and Topology

Figure 30-25 shows the components and their interaction in a SAML-based single sign-on configuration that includes WebCenter Spaces and the Discussions service.

A SAML-based single sign-on solution consists of the following components:

SAML Credential Mapper - The SAML Credential Mapping provider acts as a producer of SAML security assertions, allowing WebLogic Server to act as a source site for using SAML for single sign-on. The SAML Credential Mapping provider generates valid SAML 1.1 assertions for authenticated subjects based on the configuration of the target site or resource.

Inter Site Transfer Service (ITS) - an addressable component that generates identity assertions and transfers the user to the destination site.

Assertion Retrieval Service (ARS) - an addressable component that returns the SAML assertion that corresponds to the artifact. The assertion ID must have been allocated at the time assertion was generated.

SAML Identity Asserter - The SAML Identity Assertion provider acts as a consumer of SAML security assertions, allowing WebLogic Server to act as a destination site for using SAML for single sign-on. The SAML Identity Assertion provider processes valid SAML 1.1 assertions for authenticated subjects obtained from the source site or resource.

Assertion Consumer Service (ACS) - an addressable component that receives assertions and/or artifacts generated by the ITS and uses them to authenticate users at the destination site

SAML Relying party - A SAML Relying Party is an entity that relies on the information in a SAML assertion produced by the SAML source site. You can configure how WebLogic Server produces SAML assertions separately for each Relying Party or use the defaults established by the Federation Services source site configuration for producing assertion.

SAML Asserting party - A SAML Asserting Party is a trusted SAML Authority (an entity that can authoritatively assert security information in the form of SAML Assertions).

Figure 30-24 shows the components and flow for a POST-configured SAML SSO configuration that includes both a WebCenter and SOA domain. The flow is similar for other destination applications participating in single sign-on such as Worklist applications and Discussions.

WebCenter Spaces passes the user credentials to the authentication service provider.

If authentication is successful, the authenticated session is established, and the WebCenter Spaces welcome page is displayed.

From the welcome page, the user then clicks on a link on the page to access a secured Web page of the Discussions service (destination site), hosted on a different WebLogic Server (WC_Collaboration) in the same domain. This triggers a call to the Inter-Site Transfer Service (ITS) servlet configured. In this case, the ITS servlet is hosted within the source site (that is, on the WebCenter Spaces application on the WC_Spaces Managed Server) that shares the same JSESSIONID cookie as WebCenter Spaces.

The ITS servlet calls the SAML Credential Mapper configured in the WebCenter domain (wc_domain) to request a caller assertion. The SAML Credential Mapper returns the assertion. It also returns the URL of the destination site application Web page (a secured Web page of the Discussions service) and path to the appropriate POST form (if the source site is configured to use the POST profile).

The SAML ITS servlet generates a SAML response containing the generated assertion, signs it, base-64 encodes it, embeds it in the HTML form, and returns the form to the user's browser.

The user's browser POSTs the form to the destination site's Assertion Consumer Service (ACS). In this case, the ACS Servlet is hosted in destination site (the Discussions service) and shares its login cookie.

The assertion is validated.

If the assertion is successful, the user is redirected to the target (the secured Web page of the Discussions service).

The user is logged in on the destination site Discussions service without having to reauthenticate.

30.4.2 Configuring SAML-based Single Sign-on

This section describes how to configure WebCenter Spaces and services for SAML-based single sign-on using a set of automated scripts.

30.4.2.1 SAML Single Sign-on Prerequisites

This section describes a set of steps that should be carrie out prior to configuring SAML-based single sign-on. Note that these steps assume that WebCenter Spaces and associated components are already installed and the relevant connections have been configured and tested.

The prerequisites for SAML-based SSO are described in the following sub-sections:

30.4.2.1.1 Configuring Oracle Content Server for SAML SSO

If your instance uses a Documents connection that requires the use of OHS to surface the Oracle Content Server user interface in WebCenter, you need to configure WebCenter and related applications with a Web Tier.

When configuring SAML SSO for a configuration that includes Oracle Content Server, all HTTP URLs should point to the Web Tier host and port. Additionally when Oracle Content Server is front-ended with OHS, the following entries must appear in mod_wl_ohs.conf, apart from the usual configuration for WebCenter:

Additionally, when a custom login page is used for WebCenter Spaces the following HTML comment must be added to the head section of the HTML page generated for Oracle Content Server for Site Studio Designer to work:

<!--IdcClientLoginForm=1-->

This HTML comment appears in the out-of-the-box log in pages in WebCenter Spaces, but if you configure a new page to be the login page in a SAML SSO setup, then the comment must be added by hand, or in generated HTML as shown in the following example for a JSF page:

After checking that the comment text is added verbatim in the metaContainer facet of af:document, check the generated HTML page using View Source and confirm that <!--IdcClientLoginForm=1--> is in the <head> section of the HTML page.

30.4.2.1.2 Configuring the Discussions Server for SAML SSO

By default, the .EAR file that is deployed for the Oracle WebCenter Discussions Server supports form-based Oracle SSO or Oracle Access Manager SSO. Therefore, before you can configure the Oracle WebCenter Discussions Server for SAML-based single sign-on, you must also first deploy the SAML SSO version of the discussion server .EAR file.

30.4.2.1.3 Configuring and Exporting the Certificates

To secure communication between the SAML source and destination sites, communication should be encrypted. Additionally, certificates should be used to verify the identity of the other party during SAML interaction. Follow the steps below to generate a key using the keytool utility (available as part of the JDK 6.0), and register it using the WebLogic Server Administration Console.

To create certificates using keytool:

Configure the necessary keystore for the WC_Spaces and Administration servers in the WebCenter domain. This keystore should contain the certificate you intend to use for securing the SAML assertions.

If you only want to test the configuration, you can either create a "demoidentity" certificate that is packaged in the DemoIdentity keystore that is configured by default, or you can use keytool to generate a new certificate in the DemoIdentity keystore. For more information about configuring a custom identity keystore, see Section 31.1.2, "Configuring the Custom Identity and Java Trust Keystores."

Using keytool, export the certificate you have chosen to use to encrypt SAML assertions. Be sure to run the export command on the keystore that is configured for WC_Spaces and the Administration server for the WebCenter Spaces domain.

keystore_name is the name of the keystore that is configured for WC_Spaces and the Administration server for the WebCenter Spaces domain

keystore_password is the password of the keystore that is configured for WC_Spaces and the Administration server for the WebCenter Spaces domain

certificate_alias is the alias name (for example, demoidentity)

certificate_password is the password for the certificate

certificate.der is the name of the certificate file

Note that the keytool -export command should be run from the WebCenter Spaces machine and should export the certificate being used in the SAML SSO setup residing in the keystore configured for the WebCenter Spaces server.

Copy or transfer the file into the destination domains (such as SOA, Oracle Content Server, and Collaboration) and configure the certPath value in the wcsamlsso.properties file when you are ready to run the SAML SSO script as described in Section 30.4.2.2.1, "The Single Sign-on Script."

30.4.2.1.4 Setting Up SSL

If the WebCenter installation requires SSL for providing transport-level security, then SSL should be configured before configuring single sign-on as described in Chapter 31, "Configuring SSL." Note that setting up SSL is not related to enabling SSO.

30.4.2.2 Configuring SAML-based SSO

After installing WebCenter Spaces and services as required for your environment, continue by configuring SAML-based single sign-on using the scripts as described in this section.

The scripts set up SAML-based single sign-on in a WebLogic environment by configuring:

30.4.2.2.1 The Single Sign-on Script

The single sign-on script to configure SAML 1.1 SSO for WebCenter Spaces and related applications is located in the $WC_ORACLE_HOME/webcenter/scripts/samlsso folder. The following files are relevant for SAML configuration:

This properties file ($WC_ORACLE_HOME/common/bin/wcsamlsso.properties) encapsulates the necessary configuration information for the SAML SSO setup. The properties file has the following sections:

spaces_config

This section captures the login information, WebLogic Admin URL, WebCenter Spaces server and URL, and so forth, of the WebCenter domain required for the Credential Mapper and Source Site Federation Services configuration. All properties in this section must be completed.

This section captures the login information, admin URL, certificate file path, and so forth, of the Collaboration domain required for the Identity Asserter and Destination Site Federation Services configuration. Only complete this section if your setup has Discussions configured.

certPath - Path to exported certificate to verify SAML assertions. Note that the certificate path should be a valid path on the machine that hosts the domain (i.e., the one specified in adminURL)

utilities_config

This section captures the login information, admin URL, and certificate file path of the Utilities domain required for the Identity Asserter and Destination Site Federation Services configuration. Complete this section out only if your setup is configured with the Activity Graph application.

certPath - Path to exported certificate to verify SAML assertions. Note that the certificate path should be a valid path on the machine that hosts the domain (i.e., the one specified in adminURL)

soa_config

This section captures the login information, admin URL, certificate file path, and so forth, of the SOA domain required for the Identity Asserter and Destination Site Federation Services configuration. Only complete this section if your setup has SOA configured.

certPath - Path to exported certificate to verify SAML assertions. Note that the certificate path should be a valid path on the machine that hosts the domain (i.e., the one specified in adminURL)

ucm_config

This section captures the login information, admin URL, certificate file path, and so forth, of the Oracle Content Server domain required for the Identity Asserter and Destination Site Federation Services configuration. Only complete this section if your installation has the Documents service configured.

certPath - Path to exported certificate to verify SAML assertions. Note that the certificate path should be a valid path on the machine that hosts the domain (i.e., the one specified in adminURL)

rss_config

This is mandatory

url - RSS URL. If usesSSL in spaces_config is "true", then change "http" to "https". If RSS is front-ended with Web Tier, then specify the Web Tier host and port here.

rest_config

This section must be completed.

url - REST URL. If usesSSL in spaces_config is "true", then change "http" to "https". If REST is front-ended with Web Tier, then specify the Web Tier host and port here.

forum_config

Complete this section if your configuration has Discussions installed.

url - OWC Discussions URL. If usesSSL in collab_config is "true", then change "http" to "https". IF Discussions is front-ended with Web Tier, then specify the Web Tier host and port here.

worklist_config

Complete this section of SOA is installed and Worklist is configured for WebCenter Spaces.

worklist_detail - Worklist Detail application URL. If usesSSL in soa_config is "true", then change "http" to "https". If Worklist Detail application is front-ended with Web Tier, then specify the Web Tier host and port here.

worklist_sdp - Worklist SDP application URL. If usesSSL in soa_config is "true", then change "http" to "https". If Worklist Detail application is front-ended with Web Tier, then specify the Web Tier host and port here.

worklist_integration - Worklist Integration application URL. If usesSSL in soa_config is "true", then change "http" to "https". If Worklist Detail application is front-ended with Web Tier, then specify the Web Tier host and port here.

activitygraph_config

Complete this section if your configuration has the Utilities server installed.

url - ActivityGraphEngines URL. If usesSSL in spaces_config is "true", then change "http" to "https". If the Activity Graph application is front-ended with Web Tier, then specify the Web Tier host and port here.

cs_config

Complete this section if your configuration has Oracle Content Server installed and you have a Documents service connection configured for the WebCenter Spaces application.

url - Content Server URL. If usesSSL in spaces_config is "true", then change "http" to "https". If Oracle Content Server is front-ended with Web Tier, then specify the Web Tier host and port here. Note that if both WebCenter Spaces and Oracle Content Server are configured for your environment, then they must both be accessed using the same Web Tier.

30.4.2.2.2 Using the Scripts

Follow the steps below to use the scripts to configure SAML-based single sign-on:

Ensure that the Administration server for all the domains used in this configuration are up and running.

Generate the config and key files containing the connection information for the various domains using the storeUserConfig WLST command from the $WC_ORACLE_HOME/common/bin so that the properties file is picked up. Use the command-line help (help('storeUserConfig')) for usage and syntax details.

Connect using WLST to the WebCenter domain using the admin username and password, and run the following command:

storeUserConfig('spacesconfig.secure', 'spaceskey.secure')

This creates a user configuration file and an associated key file. The user configuration file contains an encrypted username and password. The key file contains a secret key that is used to encrypt and decrypt the username and password. The above command stores the config and key files in the directory from where WLST was invoked, or you can optionally specify a more secure path.

Repeat step 2a after connecting to the Collaboration domain using the admin username and password. Even if the Utilities server is in the same domain as WebCenter Spaces (wc_domain), you must connect to the WebCenter domain and run this command:

storeUserConfig('collabconfig.secure', 'collabkeykey.secure')

Repeat step 2a after connecting to the Utilities domain using the admin username and password. Even if the Utilities server is in the same domain as WebCenter Spaces (wc_domain), you must connect to the WebCenter domain and run this command:

storeUserConfig('utilitiesconfig.secure', 'utilitieskey.secure')

Repeat step 2a after connecting to the SOA domain using the admin username and password. Even if SOA is installed on the same domain as WebCenter Spaces, you must connect to the WebCenter domain and run this command:

storeUserConfig('soaconfig.secure', 'soakey.secure')

Repeat step 2a after connecting to the Oracle Content Server domain using the admin username and password.

storeUserConfig('ucmconfig.secure', 'ucmkey.secure')

Launch WLST and run the WLST encrypt command to encrypt the certificate password. Use the command-line help (help('encrypt')) for usage and syntax details.

This displays the encrypted certificate password. The encrypt command uses the encryption for a specified WebLogic Server domain root directory. The encrypted output needs to be set as the certPassword value in wcsamlsso.properties mentioned in the next step. Since this password will be set onto the credential mapper and source site federation services in the WebCenter domain, ensure that you run the encryption utility from the WebCenter domain.

If Discussions belongs to the same domain as WebCenter Spaces, then only restart the WC_Collaboration Managed Server. Otherwise, restart all servers including the Administration server in the Collaboration domain.

If you have a Utilities server set up, execute the configureUtilities.py script:

If the Utilities server belongs to the same domain as WebCenter Spaces, then only restart the WC_Utilities server. Otherwise, restart all servers including the Administration server in the Utilities domain.

If you have Worklist configured for WebCenter Spaces, execute the configureSOA.py script:

Since the properties file contains sensitive information, delete it from $WC_ORACLE_HOME/common/bin after you have configured and verified the SAML SSO setup. Also delete the config and key files you generated in step 2 above.

Note:

If you encounter errors when running the scripts, you must remove the asserting and relying parties set up by the scripts before running the scripts again.

Go to the Asserting Parties Settings Pane and delete the appropriate asserting parties.

Continue by fixing the issue reported and re-running the scripts.

30.4.2.3 Configuring SAML SSO for RSS Using External Readers

By default, WebCenter RSS feeds are protected by SSO. However, they will not work well with external readers if left protected. If access using external readers is important, Oracle recommends that the WebCenter RSS resource be unprotected so that the authentication for the RSS Servlet is handled by WebLogic Server's BASIC authentication that external readers can handle.

30.4.2.4 Checking Your Configuration

The last step in the process is to check that your single sign-on configuration is working. To do that:

Using a new browser, log in to WebCenter Spaces and check that you're not challenged for credentials when you click Forum Administration from Group Space Settings > Services > Discussions (assuming this service is provisioned for the group space).

Access the RSS link from Discussions or WorkList task flow, and check that you are not challenged to log in.

For Oracle Content Server, go to the Profile user interface and make sure you see Content Server screens embedded in iFrames without being challenged to log in. You should also be able to access Site Studio content in Content Presenter templates without being challenged to log in as you are already logged into WebCenter Spaces.

Access http://host:port/rest/api/resourceIndex and make sure you see the BASIC authentication challenge. If you are already logged in to another related application that uses the same SSO, you should shown content without being challenged to log in.

To test SOA, access links in the Workflow task flow and make sure you are not challenged to log in.

If while testing SAML SSO you encounter 404 or 403 errors, check the SAML configuration and also turn on debug logging for SAML on the AdminServer. Also turn on logging for the WC_Spaces server and the server hosting your destination site. The logs will be available in $domain.home/servers/<server>/logs/<server>.log. For information on how to turn on logging for WC_Spaces and other application servers, see Section 36.3, "Viewing and Configuring Log Information."

30.5 Configuring SSO for Microsoft Clients

This section describes how to set up single sign-on (SSO) for Microsoft clients, using Windows authentication based on the Simple and Protected Negotiate (SPNEGO) mechanism and the Kerberos protocol, together with the WebLogic Negotiate Identity Assertion provider for the WebCenter Spaces application. This SSO approach enables Microsoft clients (such as browsers), authenticated in a Windows domain using Kerberos, to be transparently authenticated to web applications (such as WebCenter Spaces) in a WebLogic domain based on the same credentials, and without the need to type in their password again.

Cross-platform authentication is achieved by emulating the negotiate behavior of native Windows-to-Windows authentication services that use the Kerberos protocol. In order for cross-platform authentication to work, non-Windows servers (in this case, WebLogic Server) must parse SPNEGO tokens in order to extract Kerberos tokens, which are then used for authentication.

30.5.1 Microsoft Client SSO Concepts

Understanding Kerberos

Kerberos is a secure method for authenticating a request for a service in a network. The Kerberos protocol comprises three parties: a client, a server and a trusted third party to mediate between them, known as the KDC (Key Distribution Center). Under Kerberos, a server allows a user to access its service if the user can provide the server a Kerberos ticket that proves its identity. Both the user and the service are required to have keys registered with the KDC.

The diagram below describes the basic exchanges that must take place before a client connects to a server.

SPNEGO (Simple and Protected GSSAPI Negotiation Mechanism) is a GSSAPI "pseudo mechanism" that is used to negotiate one of several possible real mechanisms. SPNEGO is used when a client application wants to authenticate to a remote server, but neither end is sure what authentication protocols the other supports. The pseudo-mechanism uses a protocol to determine what common GSSAPI mechanisms are available, selects one, and then dispatches all further security operations to it. This can help organizations deploy new security mechanisms in a phased manner.

SPNEGO's most visible use is in Microsoft's HTTP Negotiate authentication extension. The negotiable sub-mechanisms include NTLM and Kerberos, both used in Active Directory.

This feature enables a client browser to access a protected resource on WebLogic Server, and to transparently provide the WebLogic Server with authentication information from the Kerberos database using a SPNEGO ticket. The WebLogic Server can recognize the ticket and extract the information from it. WebLogic Server then uses the information for authentication and grants access to the resource if the authenticated user is authorized to access it. (Kerberos is responsible for authentication only; authorization is still handled by WebLogic Server.)

Configure the WebLogic Server domain to use the Active Directory Authenticator so that the WebLogic domain uses the same Active Directory of the domain as the identity store. You could also use a different identity store and match the users in this store with the Active Directory users of your domain, but using the Active Directory authenticator is recommended as maintaining two different identity stores risks them getting out of sync (see Section 30.5.3.2, "Configuring an Active Directory Authentication Provider").

Caution:

Ensure that only the identity store is configured for Active Directory. The policy and credential stores are not certified for Active Directory.

Add the following system properties to the JAVA_OPTIONS in setDomainEnv.sh for each WebCenter machine, changing the values below for the values of the particular host (on one line):

The Control Flag settings of any other authenticators must also be changed to SUFFICIENT. If there is a pre-existing Default Authenticator that has its Control Flag set to REQUIRED, it must be changed to SUFFICIENT.

On the Provider Summary page, reorder the providers in the following order, making sure that their Control Flags are set to SUFFICIENT where applicable:

Negotiate Identity Asserter

ActiveDirectoryAuthenticator (SUFFICIENT)

DefaultAuthenticator (SUFFICIENT)

Other authenticators...

30.5.3.3 Configuring WebCenter Spaces

Once you have completed the steps for configuring the Negotiate Identity Assertion Provider and Active Directory Authenticator, and all applications on your WebLogic domain are configured for single sign-on with Microsoft clients in the required domain, a final step is required to provide a seamless single-sign-on experience for your users when accessing WebCenter Spaces. There are two options for doing this:

Turn off public access, by logging in to WebCenter Spaces as an administrator and removing View access from the Public-User role. When public access is turned off, accessing the URL http://host:port/webcenter takes the user directly to the authenticated view rather than the default public page which has a login section. This is recommended when users are accessing WebCenter Spaces only using Internet Explorer, and are confined to the domain where WNA is set up.

If you must retain public access to WebCenter Spaces, then the recommendation is to use the oracle.webcenter.spaces.osso=true flag when starting the WC_Spaces server. This flag tells WebCenter Spaces that SSO is being used and no login form should be displayed on the default landing page. A Login link is displayed instead that the user can click to invoke the SSO authentication where the user will be automatically logged in. If Firefox is used to access WebCenter Spaces within the Windows network configured for WNA, or any browser is used to access WebCenter Spaces from outside the Windows network domain, users see the login page after clicking the Login link.

Where host and port are the host ID and port number of the WC_Collaboration Managed Server.

Open the System Properties page and edit (if it already exists) or add the owc_discussions.sso.mode property, setting it's value to true.

30.6Configuring SSO with Virtual Hosts

This section describes the OHS configuration required for an environment containing applications that use "/" as the context root, and the additional configuration required in OHS when single sign-on is involved.

However, this would affect all context roots not explicitly defined. Also, we have two applications requiring "/" mapping, which is not possible for a single OHS instance and brings up the need for virtual host configuration.

The term virtual host refers to the practice of running more than one web site (such as www.company1.com and www.company2.com) on a single machine. Virtual hosts can be IP-based, meaning that you have a different IP address for each web site, or name-based, meaning that you have multiple names running on each IP address. The fact that they are running on the same physical server is not apparent to the end user. For more information about virtual hosts, refer to your Apache documentation.

To use virtual hosts with OSSO you need to register partner applications with the virtual host option. Also, for webtier-spaces.example.com, you need to bypass single sign-on as some applications like SES and external RSS readers support only BASIC authentication and do not require single sign-on. These configurations are described in the following steps:

As Pagelet Producer (formerly called Ensemble) applications require single sign-on, register pageletproducer.example.com as a partner application with the virtual host option in addition to the webtier.example.com that you've already registered as part of the OSSO configuration steps:

Copy the generated pageletproducer.osso.conf file to the Web Tier machine in the same directory as webtier.osso.conf.

All files in moduleconf are loaded automatically by default, and we need OSSO enabled by default as well as the Pagelet Producer virtual host. We do not need single sign-on for webtier-spaces.example.com so do the following:

Move the mod_osso.conf from moduleconf to one location higher (i.e., in the same location as httpd.conf).

Copy mod_osso.conf to create another file as mod_osso_pageletproducer.conf in the same location. Be sure to reference the pageletproducer.osso.conf in this file. Also, you need to remove all protected entries with the exception of the ones applicable to Pagelet Producer as shown in the following example:

The idea is to provide a single sign-on experience for the default virtual host (webtier.example.com) and the Pagelet Producer virtual host (pageletproducer.example.com), but not for the WebCenter Spaces virtual host (webtier-spaces.example.com) as some applications like external RSS readers and SES do not support it.

Restart OHS. Also remember to update the DNS with entries for pageletproducer.example.com and webtier-spaces.example.com.

Note:

In the webtier-spaces.example.com virtual host that bypasses single sign-on, only some applications such as RSS and SES need to bypass single sign-on. For other applications like WebCenter Spaces, however, we need single sign-on so we deny access to these applications from this virtual host.

30.6.3 Configuring Virtual Hosts for OAM 10g

To configure OAM 11g for virtual hosts we need to bypass single sign-on for the SES crawler and authentication end points, and RSS as their use by SES and external RSS readers only support BASIC authorization. These integrations also do not require single sign-on. For more information, see "Associating a WebGate with Particular Virtual Hosts, Directories, or Files" in the Oracle Fusion Middleware Administrator's Guide for Oracle Access Managerfor 10g.

The idea is to provide a single sign-on experience for the default virtual host (webtier.example.com) and the Pagelet Producer virtual host (pageletproducer.example.com), but not for the WebCenter Spaces virtual host (webtier-spaces.example.com) as some applications like external RSS readers and SES do not support it.

Restart OHS. Also be sure to update the DNS with entries for pageletproducer.example.com and webtier-spaces.example.com.

Note:

In the webtier-spaces.example.com virtual host that bypasses single sign-on, only some applications such as RSS and SES need to bypass single sign-on. For other applications like WebCenter Spaces, however, we need single sign-on so we deny access to these applications from this virtual host.

30.6.4 Configuring Virtual Hosts for OAM 11g

To configure OAM 11g for virtual hosts we need to bypass single sign-on for the SES crawler and authentication end points, and RSS as their use by SES and external RSS readers only support BASIC authorization. These integrations also do not require single sign-on.

The idea is to provide a single sign-on experience for the default virtual host (webtier.example.com) and the Pagelet Producer virtual host (pageletproducer.example.com), but not for the WebCenter Spaces virtual host (webtier-spaces.example.com) as some applications like external RSS readers and SES do not support it.

Restart OHS. Also be sure to update the DNS with entries for pageletproducer.example.com and webtier-spaces.example.com.

Note:

In the webtier-spaces.example.com virtual host that bypasses single sign-on, only some applications such as RSS and SES need to bypass single sign-on. For other applications like WebCenter Spaces, however, we need single sign-on so we deny access to these applications from this virtual host.

30.6.5 Configuring WebCenter for Virtual Hosts

This section describes the additional configurations required for applications routed through the virtual host.

Sharepoint

Typically when you use the "Edit with Word" or similar features for MS Office products, the WebCenter Sharepoint application obtains the host name and port name from the current request. However, in this case the Sharepoint application needs to be routed through the virtual host requiring that some system properties be set in setDomainEnv in the WebLogic domain. For a cluster setup, be sure to change these properties on every machine.

All access to Pagelet Producer applications should be done through pageletproducer.example.com. For example, when you register an Pagelet Producer producer in WebCenter Spaces or WebCenter Portal application, it should use the virtual host for Pagelet Producer.

Similarly access to the Pagelet Producer administration application and access to any Pagelet Producer resources should also be done through the virtual host. Refer to the Pagelet Producer documentation for more information.

SES

Configuration changes are only required if you are using OAM 10g or 11g. Since SES is not equipped to handle OAM protected crawl sources, when you create an SES source for WebCenter crawling, specify the crawl and end point URLs using the webtier-spaces.example.com virtual host. Specify the authentication mechanism as BASIC and the realm as jazn.com as webtier-spaces.example.com bypasses single sign-on.

Note that these configurations do not apply if you are using OSSO for single sign-on since if you have not configured the SES URIs in mod_osso.conf, then the authentication will be handled by WLS using BASIC authentication. For OAM, however, the WebGate tends to deny access to resources not protected by OAM and consequently the need to bypass OAM by using the virtual host.

30.6.6 Testing Your Configuration

This section describes how you can test your virtual host and single sign-on configuration.

Sharepoint

Access http://webtier.example.com:7777/webcenter and check that you are challenged by SSO.

Log in and choose an MS Word document and click Edit with Word. Click OK when you see a confirmation dialog. Word should challenge you for BASIC authentication. Enter your credentials and you should be able to see the document

Navigate to Office icon > Server > Document Management Information and click Open Site in Browser. This should open the group space to which the document belongs in your default browser.

Note that you will be prompted with a BASIC authentication challenge as MS Office integration has a restriction where it needs to go to the same URL as the one for the document. You will then be redirected to the group space through webtier.example.com and be prompted for to login if not already logged in.

Pagelet Producer

Access http://webtier.example.com:7777/webcenter and check that you are challenged by SSO.

Log in.

Access http://pageletproducer.example.com:7777/pageletadmin. If you logged in in step 2, you should not be challenged to sign in. If you sign in from a new browser instance, however you should still be challenged by SSO.

Create a protected resource (for example, google) and access it using http://pageletproducer.example.com:7777/google/. Again, check that you are challenged by SSO if you did not previously log in.

When you register Pagelet Producer in WebCenter Spaces, use http://pageletproducer.example.com:7777/ and make sure that portlets render correctly.

SES

Applicable only when using OAM 10g/11g:

When you create a WebCenter crawl source, use http://webtier-spaces.example.com:7777/rsscrawl and http://webtier-spaces.example.com:7777/sesUserAuth for the crawl and authentication end points.