17 Configuring Single Sign-On using OracleAS SSO 10g

The chapter describes how to implement SSO using OracleAS SSO (OSSO) 10g. It includes the following major sections:

17.1 Deploying the OracleAS 10g Single Sign-On (OSSO) Solution

The OracleAS Single Sign-On solution provides single sign-on access to Web Applications. Oracle Internet Directory is the LDAP-based repository.

This solution is intended for applications that have been deployed on Oracle WebLogic Server but do not yet have single sign-on implemented. Requirements and steps to configure the OSSO solution are explained in "New Users of the OSSO Identity Asserter".

Note:

Oracle recommends using Oracle Access Manager 11g, as described in "Introduction to Oracle Access Manager 11g SSO".

Applications that are already using the OracleAS Single Sign-On solution with the JPS login module and dynamically re-directing requests to OSSO are unaffected by the new OSSO solution. In this case, there is no need to configure the new OSSO Authentication Provider described in this section.

This section is divided as follows:

17.1.1 Using the OSSO Identity Asserter

This section describes the expected behavior when you implement the OracleAS Single Sign-On Identity Asserter. This section is divided as follows:

17.1.1.1 Oracle WebLogic Security Framework

Figure 17-1 illustrates the location of components in the Oracle WebLogic Security Framework, including the OSSO Identity Asserter. Additional details follow.

Figure 17-1 Location of OSSO Components in the Oracle WebLogic Security Framework

SSO Components in WLS Security Framework
Description of "Figure 17-1 Location of OSSO Components in the Oracle WebLogic Security Framework"

At the top of the figure, Oracle HTTP Server is installed. This installation includes mod_weblogic and mod_osso, which are required to pass the identity token to the Providers and Oracle WebLogic Server. The Oracle WebLogic Server includes the partner application and the Identity Asserter (also known as the Identity Assertion Provider). The 10g OracleAS Single Sign-On server (OSSO Server), on the right side of the figure, communicates directly with the directory server and Oracle HTTP Server.

Note:

For simplicity in text, this chapter uses the generic name of the WebLogic Server plug-in for Apache: mod_weblogic. For Oracle HTTP Server, the name of this plug-in differs from release 10g to 11g:
  • Oracle HTTP Server 10g: mod_wl (actual binary name is mod_wl_20.so)

  • Oracle HTTP Server 11g: mod_wl_ohs (actual binary name is mod_wl_ohs.so)

17.1.1.2 OSSO Identity Asserter Processing

Figure 17-2 illustrates the processing that occurs when you have OSSO implemented with the Identity Asserter. Additional details follow the figure.

Figure 17-2 OSSO Identity Asserter Processing

Processing for OSSO with the Identity Asserter
Description of "Figure 17-2 OSSO Identity Asserter Processing"

The first time a request for a protected resource arrives at the mid-tier Web server, the request is redirected to the 10g OracleAS Single Sign-On server, which requires user credentials For a certificate-based authentication, no login page is displayed. After the user has been successfully authenticated, all further requests from that user require only that the user identity be asserted by the OSSO Identity Asserter before the population of a JAAS Subject takes place. The Subject is consumed by the downstream applications.

For example, suppose you have an application residing on an Oracle WebLogic Server that is front-ended with the Oracle HTTP Server. The application is protected using resource mappings in the mod_osso configuration. This case is described in the following process overview.

Process overview: OSSO Identity Asserter

  1. The user requests a protected application.

  2. The Oracle HTTP Server intercepts the request and processes it using mod_osso to check for an existing, valid Oracle HTTP Server cookie.

  3. If there is no valid Oracle HTTP Server cookie, mod_osso redirects to the OracleAS SSO Server, which contacts the directory during authentication.

  4. After successful authentication mod_osso decrypts the encrypted user identity populated by the OSSO server and sets the headers with user attributes.

  5. mod_weblogic completes further processing and redirects the request to the Oracle WebLogic Server.

  6. The WebLogic security layer invokes providers depending on their settings and the order specified. For example: the security layer invokes the:

    • Identity Asserter, which makes the identity assertion based on retrieved tokens

    • Oracle Internet Directory Authenticator (OID Authenticator), which populates the Subject with necessary Principals

  7. A response is sent to the user through the Oracle HTTP Server, and access to the application is granted.

17.1.1.3 Consumption of Headers with OSSO Identity Asserter

This topic describes the headers sent by Oracle HTTP Server and the tokens set in the header and the headers consumed by the OSSO Identity Asserter. If the application needs to use the JAAS subject, configure OSSO Identity Asserter.

Table 17-1 provides the list of headers set by Oracle HTTP Server (mod_osso and mod_weblogic). An application whose logic consumes the JAAS subject for identifying user information, should be configured to use the OSSO Identity Asserter. which uses the OracleAS SSO token type set in bold in the table (Proxy-Remote-User). The OSSO Identity Asserter looks for the Proxy-Remote-User header and asserts the user's identity. The follow up OID Authenticator populates the JAAS subject.

Table 17-1 Headers Sent by Oracle HTTP Server

Attribute Sample Value Description

Cookie

OHS-Stads42.us.oracle.com:7777=.......

Cookies

Osso-User-Guid

4F4E3D2BF4BFE250E040548CE9816D7E

GUID of the authenticated user

Osso-User-Dn

cn=orcladmin,cn=users, dc=us,dc=oracle,dc=com

DN of the authenticated user

Osso-Subscriber

DEFAULT COMPANY

Subscriber name

Osso-Subscriber-Dn

dc=us,dc=oracle,dc=com

Base DN of the subscriber

Osso-Subscriber-Guid

4F4E3D2BF410E250E040548CE9816D7E

GUID of the subscriber

Proxy-Remote-User

ORCLADMIN

The authenticated user

Proxy-Auth-Type

Basic SSO

Authentication type


Applications that do not require the JAAS subject for identifying user information, can read the headers directly using the request.getHeader() API. Such applications are free to read any header they need. Headers with user info are Osso-User-Dn, Osso-User-Guid, and Proxy-Remote-User.

17.1.2 New Users of the OSSO Identity Asserter

The new OracleAS Single Sign-On solution includes the OSSO Identity Asserter, one of the two new Authentication Providers for the Oracle WebLogic Server.

To have your application use the OSSO solution, you need the components described in the following task.

Note:

If you already have components installed and set up, you do not need more. You can skip any steps that do not apply to your deployment.

Task overview: Deploying and configuring the OSSO Identity Asserter

  1. Install the following components:

    1. OracleAS Single Sign-On Server 10g (10g OSSO server

      See Also:

      Oracle Application Server Installation Guide on Oracle Technology Network at: http://www.oracle.com/technology/documentation/oim1014.html
    2. An Oracle Internet Directory repository configured to be used by the 10g OSSO server. Ensure that the directory server is tuned for your deployment.

    3. One of the following Web servers (based on Apache 2):

    4. Oracle WebLogic Server 10.3.1+

    5. An Oracle Fusion Middleware product such as Oracle Identity Management, Oracle SOA Suite, or Oracle WebCenter is required; it includes the provider required for OSSO by Oracle WebLogic Server in the following path:

      ORACLE_INSTANCE/modules/oracle.ossoiap_11.1.1/ossoiap.jar
      
  2. Configure mod_weblogic so that it forwards requests to Oracle WebLogic Server, as explained in section "Configuring mod_weblogic".

  3. Register the module mod_osso with the 10g SSO Server as a partner application, as described in "Registering Oracle HTTP Server mod_osso with OSSO Server 10.1.4".

  4. Configure mod_osso, as described in "Configuring mod_osso to Protect Web Resources".

  5. Add the OSSO Identity Asserter to the appropriate domain, as explained in section "Adding Providers to a WebLogic Domain for OSSO".

  6. Configure a connection filter, as explained in section "Establishing Trust Between Oracle WebLogic Server and Other Entities".

  7. Configure the use of the solution by the application, as explained in section "Configuring the Application for the OSSO Identity Asserter".

  8. Identify and resolve issues with your OSSO Identity Asserter implementation, see "Troubleshooting for an OSSO Identity Asserter Deployment".

17.1.2.1 Configuring mod_weblogic

You can either edit the Oracle HTTP Server httpd.conf file directly or add mod_weblogic configuration in a separate file and include that file in httpd.conf.

The following procedure includes steps for two different Web server releases. Perform steps as needed for your deployment:

  • OHS 11g ships with mod_wl_ohs.so. In this case, skip Step 1.

  • OHS 10g does not ship with mod_weblogic (mod_wl_.so). If Oracle HTTP Server 10g is installed, start with Step 1 to copy mod_wl_20.so before configuration.

Note:

For Oracle HTTP Server, the name of this plug-in differs from release 10g to 11g:
  • Oracle HTTP Server 10g: mod_wl (actual binary name is mod_wl_20.so)

  • Oracle HTTP Server 11g: mod_wl_ohs (actual binary name is mod_wl_ohs.so)

To install and configure mod_weblogic

  1. Oracle HTTP Server 10.1.3: Copy mod_wl_20.so to the Oracle HTTP Server modules directory: For example:

    From: WL_HOME/wlserver_10.0/server/plugin/linux/i686

    To: ORACLE_HOME/ohs/modules

  2. Locate the Oracle HTTP Server httpd.conf file. For example:

    Oracle HTTP Server 10.1.3:

    ORACLE_HOME/ohs/conf/httpd.conf
    

    Oracle HTTP Server 11g:

    ORACLE_INSTANCE/config/OHS/<ohs_name>/httpd.conf
    
  3. Verify that mod_weblogic configuration is in httpd.conf, either by inclusion of the appropriate configuration file or the configuration itself directly. For example, for Oracle HTTP Server 10g:

    LoadModule weblogic_module ${ORACLE_HOME}/ohs/modules/mod_wl_20.so 
    <IfModule mod_weblogic.c>
       WebLogicHost yourHost.yourDomain.com
         WebLogicPort yourWlsPortNumber
    </IfModule>
     
    <Location /request-uri-pattern>
       SetHandler weblogic-handler
    </Location>
    

17.1.2.2 Registering Oracle HTTP Server mod_osso with OSSO Server 10.1.4

The mod_osso module is an Oracle HTTP Server module that provides authentication to OracleAS applications. This module resides on the Oracle HTTP Server that enables applications protected by OracleAS Single Sign-On to accept HTTP headers in lieu of a user name and password once the user has logged into the OracleAS Single Sign-On server. The values for these headers are stored in a mod_osso cookie.

The mod_osso module enables single sign-on for Oracle HTTP Server by examining incoming requests and determining whether the requested resource is protected. If it is, then it retrieves the Oracle HTTP Server cookie.

Under certain circumstances, you must register Oracle HTTP Server mod_osso using the 10.1.4 Oracle Identity Manager single sign-on registration tool (ssoreg.sh or ssoreg.bat). Table 17-2 provides a summary of parameters and values for this purpose. Running the tool updates the mod_osso registration record in osso.conf. The tool generates this file whenever it runs.

Table 17-2 ssoreg Parameters to Register Oracle HTTP Server mod_osso

Parameter Description

-oracle_home_path

Path to the 10.1.4 SSO Oracle_Home

-site_name

Any site name to be covered

-config_mod_osso

TRUE. If set to TRUE, this parameter indicates that the application being registered is mod_osso. You must include config_mod_osso for osso.conf to be generated.

-mod_osso_url

URL for front-ending Oracle HTTP Server Host:port. This is the URL that is used to access the partner application. The value should be specified in the URL format:http://oracle_http_host.domain:port

-update_mode

Optional. CREATE, the default, generates a new record.

-remote_midtier

Specifies that the mod_osso partner application to be registered is at a remote mid-tier. Use this option only when the mod_osso partner application to be configured is at a different ORACLE_HOME, and the OracleAS Single Sign-On server runs locally at the current ORACLE_HOME.

-config_file

Path where osso.conf is to be generated

[-admin_info

Optional. User name of the mod_osso administrator. If you omit this parameter, the Administer Information field on the Edit Partner Application page is left blank.

admin_id

Optional. Any additional information, such as email address, about the administrator. If you omit this parameter, the Administrator E-mail field on the Edit Partner Application page is left blank.

<VirtualHost ...>

Host name. Optional. Include this parameter only if you are registering an Oracle HTTP virtual host with the single sign-on server. Omit the parameter if you are not registering a virtual host.

If you are creating an HTTP virtual host, use the httpd.conf file to fill in the directive for each protected URL.


See Also:

The following books on Oracle Technology Network at: http://www.oracle.com/technology/documentation/oim1014.html
  • Oracle Application Server Single Sign-On Administrator's Guide 10g (10.1.4.0.1) Part Number B15988-01

  • Oracle Identity Management Application Developer's Guide 10g (10.1.4.0.1) Part Number B15997-01

The following procedure includes a sample command to register mod_osso. Values for your environment will be different.

To register mod_osso

  1. Go to the following 10.1.4 Oracle Identity Manager directory path:

    ORACLE_HOME/sso/bin/ssoreg
    
  2. Run ssoreg with the following parameters and values for your environment. For example, on Unix, this might look like:

    ./ssoreg.sh -oracle_home_path \OraHome -site_name wls_server  
    -config_mod_osso TRUE -mod_osso_url http://oracle_http_host.domain:7788 
    -update_mode CREATE -remote_midtier -config_file \tmp\osso.conf
    
  3. Verify that the module mod_osso of the required Oracle HTTP Server is registered.

  4. Proceed to "Configuring mod_osso to Protect Web Resources".

17.1.2.3 Configuring mod_osso to Protect Web Resources

mod_osso redirects the user to the single sign-on server only if the URL you request is configured to be protected. You can secure URLs in one of two ways: statically or dynamically. Static directives simply protect the application, ceding control over user interaction to mod_osso. Dynamic directives not only protect the application, they also enable it to regulate user access.

For more information, see:

17.1.2.3.1 Configuring mod_osso with Static Directives

You can statically protect URLs with mod_osso by applying directives to the mod_osso.conf file. You must configure mod_osso to ensure that requests are intercepted properly. In addition, you specify the location of protected URIs, time out interval, and the authentication method. Oracle recommends that you place in the httpd.conf file the include statement for mod_osso.conf before the one wherein the weblogic_module statement is loaded.

The following procedure describes how to configure mod_osso by editing the mod_osso.conf file. This procedure provides details for two different releases. Ensure that you follow instructions for your OHS deployment:

  • Oracle HTTP Server 11g: Requires Step 2 and AuthType Osso in Step 4. The path name in Step 5 differs for Oracle HTTP Server 11g.

  • Oracle HTTP Server 10g: Requires Step 3 and AuthType Basic in Step 4. The path name in Step 5 differs for Oracle HTTP Server 10g.

To configure mod_osso to protect Web resources

  1. Copy osso.conf from the location where it was generated to the following location:

    From: /tmp/osso.conf

    To:

    ORACLE_INSTANCE/config/OHS/<ohs_name>/osso/osso.conf  
    
  2. Oracle HTTP Server 11g: Copy mod_osso.conf from the disabled directory to the moduleconf directory for editing. For example:

    From:

    ORACLE_INSTANCE/config/OHS/<ohs_name>/disabled/mod_osso.conf  
    

    To:

    ORACLE_INSTANCE/config/OHS/<ohs_name>/moduleconf/mod_osso.conf  
    
  3. Oracle HTTP Server 10g: Locate mod_osso.conf for editing. For example:

    ORACLE_HOME/ohs/conf/mod_osso.conf
    
  4. Edit mod_osso.conf to add the following information using values for your deployment. For example, using Oracle HTTP Server as an example (paths are different for 10g):

    LoadModule osso_module ${ORACLE_HOME}/ohs/modules/mod_osso.so
    <IfModule mod_osso.c>
    
    OssoIdleTimeout off
    OssoIpCheck on
    OssoConfigFile  ORACLE_INSTANCE/config/OHS/<ohs_name>/osso/osso.conf   
    
    #Location is the URI you want to protect
    <Location />
    require valid-user
    #OHS 11g AuthType Osso    
    #OHS 10g AuthType Basic    
    AuthType Osso
    
    </Location>
    
    </IfModule>
    
  5. Locate the httpd.conf file for editing. For example:

    Oracle HTTP Server 10.1.3:

    ORACLE_HOME/ohs/config/httpd.conf
    

    Oracle HTTP Server 11g:

    ORACLE_INSTANCE/config/OHS/<ohs_name>/httpd.conf 
     
    
  6. In the httpd.conf, confirm that the mod_osso.conf file path for your environment is included. For example:

    include /ORACLE_INSTANCE/config/OHS/<ohs_name>/moduleconf/mod_osso.conf
    
  7. Restart the Oracle HTTP Server.

    Tip:

    If the interception of requests is not working properly, consider placing the include statement for mod_osso.conf before the LoadModule weblogic_module statement in the httpd.conf.
  8. Proceed to "Adding Providers to a WebLogic Domain for OSSO".

17.1.2.3.2 Protecting URLs and Logout Dynamically (without mod_osso)

Applications that use dynamic directives require no entry in mod_osso.conf because mod_osso protection is written directly into the application as one or more dynamic directives.

Dynamic directives are HTTP response headers that have special error codes that enable an application to request granular functionality from the single sign-on system without having to implement the intricacies of the single sign-on protocol. Upon receiving a directive as part of a simple HTTP response from the application, mod_osso creates the appropriate single sign-on protocol message and communicates it to the single sign-on server.

OracleAS supports dynamic directives for Java servlets and JSPs. The product does not currently support dynamic directives for PL/SQL applications. The JSPs that follow show how such directives are incorporated. Like their "static" counterparts, these sample "dynamic" applications generate user information:

Note:

After adding dynamic directives, be sure to restart the Oracle HTTP Server, and the proceed to "Adding Providers to a WebLogic Domain for OSSO".

Example 17-1 SSO Authentication with Dynamic Directives

The home.jsp includes ssodynauth.jsp that uses the request.getUserPrincipal().getName() method to check the user in the session. If the user is absent, it issues dynamic directive 499, a request for simple authentication. The key lines are in boldface.

//home.jsp

<%@ include file="ssodynauth.jsp" %>
<%
//page content goes here
%>

//ssodynauth.jsp

<%
response.setHeader("Cache-Control", "no-cache");
response.setHeader("Pragma", "no-cache");
response.setHeader("Expires", "0");
%>
<%
// Check for user
String ssoUser = null;
try
(
//ssoUser = request.getRemoteUser();
ssoUser = request.getUserPrincipal( ).getName( );
ssoUser = ssoUser.trim( );
 }
catch(Exception e)
{
ssoUser = null;
 }

// If user is not authenticated then generate
// dynamic directive for authentication
if((ssoUser == null) || (ssoUser.length() < 1))
{
response.sendError(499, "Oracle SSO");
return;
}%>

See Also:

Oracle Identity Management Application Developer's Guide 10g (10.1.4.0.1) Part Number B15997-01 on Oracle Technology network at: http://www.oracle.com/technology/software/products/ias/htdocs/101401.html

Example 17-2 SSO Logout with Dynamic Directives

To achieve global logout (also known as single log-out), applications are expected to first invalidate sessions and then make a call to OSSO logout. The logout.jsp issues dynamic directive 470, a request for OSSO logout. The osso-return-logout is set by the application to specify the return URL after logout.

The key lines for SSO logout with dynamic directives appear in boldface in the following example. In 11g, the SSOFilter handles session synchronization.

//logout.jsp
<%@page session="false"%>
<%
   response.setHeader("Osso-Return-Url", "http://my.oracle.com/");
   HttpSession session =  null;
   session = request.getSession();
   if (null != session )
   {
     // necessary for achieving SLO
     session.invalidate();
   }
   response.sendError(470, "Oracle SSO");
%>

See Also:

Note:

After adding dynamic directives, be sure to restart the Oracle HTTP Server, and the proceed to "Adding Providers to a WebLogic Domain for OSSO".

17.1.2.4 Adding Providers to a WebLogic Domain for OSSO

You must add the OSSO Identity Asserter to a WebLogic domain. In addition to the OSSO Identity Asserter, Oracle recommends the following Authentication Providers:

  • OSSO Identity Asserter

  • DefaultAuthenticator

  • OID Authenticator

You can add providers using either the Oracle WebLogic Administration Console or Oracle WebLogic Scripting Tool (WLST) command-line tool.

The following procedure illustrates adding Authentication Providers using the Oracle WebLogic Administration Console. Before you begin, there is a condition to pay attention to:

Step 10: If your application requires the user in the same case as in Oracle Internet Directory (uppercase, lowercase, initial capitals), check Use Retrieved User Name as Principal. Otherwise, leave it unchecked.

To add providers to your WebLogic domain for OSSO Identity Assertion

  1. Log in to the WebLogic Administration Console.

  2. OSSO Identity Asserter: Perform the following steps to add this to the domain:

    1. Click Security Realms, Default Realm Name, Providers.

    2. Select New under the Authentication Providers table.

    3. Enter a name for the new provider, select its type, and then click OK. For example:

      Name: OSSO Identity Asserter

      Type: OSSOIdentityAsserter

      Ok

    4. Click the name of the newly added provider.

    5. On the Common tab, set the appropriate values for common parameters and set the Control Flag to SUFFICIENT and then save the settings.

  3. Default Authentication Provider:

    1. Click Security Realms, Default Realm Name, Providers.

    2. Click Default Authentication Provider.

    3. Set the control flag to OPTIONAL, and click Save

  4. OID Authenticator: Perform the following steps to add this provider.

    1. Click Security Realms, Default Realm Name, Providers.

    2. Click New, and enter a name and type:.

      Name. OID Authenticator

      Type: OracleInternetDirectoryAuthenticator

      Click Save.

    3. Click the newly added authenticator to see the Settings page. Retain the default settings; do not change the Control Flag until you have verified that the Oracle Internet Directory configuration is valid.

      Note:

      If OID Authenticator is the only provider, ensure the WebLogic Server user account and its granted group memberships are created in Oracle Internet Directory. Otherwise the WebLogic domain does not start properly.
    4. Click the Provider Specific tab and specify the following required settings:

      Propagate Cause For Login Exception: Check

      Principal: LDAP administrative user. For example: cn=orcladmin

      Host: The Oracle Internet Directory hostname

      Use Retrieved User Name as Principal: Check

      Credential: LDAP administrative user password. For example: password

      Confirm Credential: For example: password

      Group Base DN: Oracle Internet Directory group search base

      User Base DN: Oracle Internet Directory user search base.

      Port: Oracle Internet Directory port

  5. Reorder Providers: The order in which providers populate a subject with principals is significant and you might want to reorder the list of all providers in your realm and bring the newly added provider to the top of the list.

  6. Save all configuration settings.

  7. Stop and restart the Oracle WebLogic Server for the changes to take effect.

  8. Log in to the WebLogic Administration Console:

    1. Click Security Realms, Default Realm Name, Providers.

    2. Select the Users and Groups tab to see a list of users and groups contained in the configured Authentication Providers.

      You should see usernames from the Oracle Internet Directory configuration, which implicitly verifies that the configuration is working.

      --If the Oracle Internet Directory instance is configured successfully, you can change the Control Flag.

      --If the Oracle Internet Directory authentication is sufficient for an application to identify the user, then choose the SUFFICIENT flag. SUFFICIENT means that if a user can be authenticated against Oracle Internet Directory, no further authentication is processed. REQUIRED means that the Authentication Provider must succeed even if another provider already authenticated the user.

  9. Application Requires User in Same Case as in Oracle Internet Directory: Check Use Retrieved User Name as Principal. Otherwise, leave it unchecked.

  10. Save the changes.

  11. Activate the changes and restart Oracle WebLogic Server.

  12. Proceed with "Establishing Trust Between Oracle WebLogic Server and Other Entities".

17.1.2.5 Establishing Trust Between Oracle WebLogic Server and Other Entities

The Oracle WebLogic Connection Filtering mechanism must be configured for creating access control lists and for accepting requests from only the hosts where Oracle HTTP Server and the front-end Web server are running.

Note:

This topic is the same whether you are using OSSO or Oracle Access Manager. In the WebLogic Administration Console.

A network connection filter is a component that controls the access to network level resources. It can be used to protect resources of individual servers, server clusters, or an entire internal network. For example, a filter can deny non-SSL connections originating outside of a corporate network. A network connection filter functions like a firewall since it can be configured to filter protocols, IP addresses, or DNS node names. It is typically used to establish trust between Oracle WebLogic Server and foreign entities.

Connection Filter Rules: The format of filter rules differ depending on whether you are using a filter file to enter the filter rules or you enter the filter rules in the Administration Console. When entering the filter rules on the Administration Console, enter them in the following format:

targetAddress localAddress localPort action protocols

See Also:

"Configuring Security in a WebLogic Domain" in Oracle Fusion Middleware Securing Oracle WebLogic Server

Table 17-3 provides a description of each parameter in a connection filter.

Table 17-3 Connection Filter Rules

Parameter Description

target

Specifies one or more systems to filter

localAddress

Defines the host address of the WebLogic Server instance. (If you specify an asterisk (*), the match returns all local IP addresses.)

localPort

Defines the port on which the WebLogic Server instance is listening. (If you specify an asterisk, the match returns all available ports on the server.)

action

Specifies the action to perform. This value must be allow or deny.

protocols

Is the list of protocol names to match. The following protocols may be specified: http, https, t3, t3s, giop, giops, dcom, ftp, ldap. If no protocol is defined, all protocols match a rule.


The Connection Logger Enabled attribute logs successful connections and connection data in the server. This information can be used to debug problems relating to server connections.

To configure a connection filter to allow requests from the host of the 11g Oracle HTTP Server

  1. Log in to the Oracle WebLogic Administration Console.

  2. Click Domain under Domain Configurations.

  3. Click the Security tab, click the Filter tab.

  4. Click the Connection Logger Enabled attribute to enable the logging of accepted messages for use when debugging problems relating to server connections.

  5. Specify the connection filter to be used in the domain:

    • Default Connection Filter: In the Connection Filter attribute field, specify weblogic.security.net.ConnectionFilterImpl.

    • Custom Connection Filter: In the Connection Filter attribute field, specify the class that implements the network connection filter, which should also be specified in the CLASSPATH for Oracle WebLogic Server.

  6. Enter the appropriate syntax for the connection filter rules.

  7. Click Save.

  8. Restart the Oracle WebLogic Server.

  9. Proceed to "Configuring the Application for the OSSO Identity Asserter".

17.1.2.6 Configuring the Application for the OSSO Identity Asserter

This topic describes how to create the application authentication method for the OSSO Identity Asserter.

Oracle WebLogic Server supports adding multiple auth-methods. If you are setting up an OSSO Identity Asserter in the WebLogic Application Console, the Web application using the OSSO Identity Asserter must have its auth-method set to CLIENT-CERT.

After deploying the application on the Oracle WebLogic Server, all web.xml files in the application EAR file must include CLIENT-CERT in the element auth-method for the appropriate realm, as described in the following procedure.

To edit web.xml for the OSSO Identity Asserter

  1. Locate the web.xml file in the application EAR file. For example:

    WEB-INF/web.xml  
    
  2. Locate the auth-method for the appropriate realm and enter CLIENT-CERT. For example:

    <login-config>
      <auth-method>CLIENT-CERT</auth-method>
      <realm-name>myRealm</realm-name>
    </login-config>
    
  3. Save the file.

  4. Redeploy and restart the application.

  5. Repeat for each web.xml file in the application EAR file.

17.2 Synchronizing the User and SSO Sessions: SSO Synchronization Filter

In Fusion Middleware 11g, a new component that synchronizes the container user session and SSO session has been introduced. SSO Sync Filter is an Oracle WebLogic system filter implementation that intercepts all requests to the container, acts on protected resource requests, and attempts to synchronize the container's user session with the user identifying header in OSSO (Proxy-Remote-User) or the user data in the Oracle Access Manager SSO session cookie (ObSSOCookie).

SSO Synchronization Filter (SSO Sync Filter) is an implementation of the Servlet Filter based on Java Servlet Specification version 2.3. SSO sync filter relieves applications from tracking the SSO user session and synchronizing it with their respective sessions. Instead, applications would only need to synchronize with container's user session.

SSO Sync Filter intercepts each request to the container and determines whether to act on it based on certain HTTP headers that are attached to the request. Filter expects SSO agent to have set those headers in the Web Tier. When access is made to unprotected areas of the application, the filter acts as a pass through. Once a protected resource is accessed, SSO agents in the Web Tier, direct user to perform authentication with SSO system such as Oracle Access Manager. After the authentication, Oracle Access Manager Identity Asserter helps establish a user identity in form of JAAS Subject to the container and a user session is created. WebLogic maintains the user session data as part of HTTP Session Cookie (JSESSIONID).

Subsequent access to the application resources provides two pieces of information to the SSO Sync Filter:

  • User identifying header in OSSO (Proxy-Remote-User)

  • User data in the Oracle Access Manager SSO session cookie (ObSSOCookie)

The job of SSO Sync Filter is to make sure that the user identity in the container matches with that of the SSO session. If there is a mismatch, filter invalidates the container's user session. As a result, the downstream application would only have to track container user session and react in a consistent fashion regardless of SSO environment in use.

Notes:

  • Enabled and Active by Default: SSO Sync Filter fetches the user information from the configured tokens, gets the user from existing session (if any), invalidates the session and redirects to the requested URL in case the CurrentSessionUser does not match the incoming SSO User. Otherwise, the request is simply passed through.

    If you have not configured the OSSO or Oracle Access Manager Assertion Providers in your domain, the filter disables automatically during WebLogic Server start-up.

  • Active for All URI's by Default (/* ): No changes are required in the application code.

  • Configured for the OSSO Tokens/Header: Proxy-Remote-User, and performs a case insensitive match.

  • Configured for the Oracle Access Manager SSO Tokens/Header: OAM_REMOTE_USER and REMOTE_USER, and does a case insensitive match.

  • Global Logout: SSO Sync Filter is intended to provide the Single Logout Experience to the Oracle Fusion Middleware applications that use the OSSO or Oracle Access Manager Solutions. Is handled similarly to single sign-on. After global logout is performed, SSO filter reconciles the session when subsequent access to an application that has not cleaned up its session is made.

    Any application that use the OSSO or Oracle Access Manager Solutions is expected to invalidate its session before making a call to OSSO logout or Oracle Access Manager logout. For more information on OSSO logout, see "SSO Logout with Dynamic Directives". For details about Oracle Access Manager logout, see "Configuring Global Logout for Oracle Access Manager 10g and 10g WebGates".

  • Application Session Time Out: SSO cookies typically track user inactivity/idle times and force users to login when a time out occurs. OSSO and Oracle Access Manager are no exception. Oracle Access Manager takes a sophisticated approach at this and specifically tracks Maximum Idle Session Time and Longest Idle Session Time along with SSO session creation time and time when it was last refreshed.

    The general recommendation for applications that are maintaining their own sessions when integrating with SSO systems is to configure their session time outs close to that of SSO session time outs so as to make user experience remains consistent across SSO and application session time outs.

You can alter the behavior of the SSO Sync Filter for application requirements by passing various over-riding system properties to WebLogic. To do this, you change the Oracle WebLogic startup script and check for EXTRA_JAVA_PROPERTIES in setDomainEnv.sh. The properties and Sync behavior is shown in Table 17-4.

Table 17-4 SSO Sync Filter Properties and Sync Behavior

Area Overriding System Property Default value of System property Default Behavior of the Sync Filter

Status (Active or Inactive)

sso.filter.enable

Not configured

Enabled

Case sensitive matches

sso.filter.name.exact.match

Not configured

Case Ignore Match

Configured Tokens

sso.filter.ssotoken

Not configured

  • OSSO: Look for Proxy-Remote-User

  • Oracle Access Manager: Look for OAM_REMOTE_USER and REMOTE_USER.

    OAM_REMOTE_USER takes precedence.

URI Mappings

Not Applicable

Not Applicable

/*


You cannot enable the filter for selected applications. The SSO Sync Filter is a system filter. As such, it is activated for all deployed applications (the URI mapping is /*).

Note:

You cannot enable the filter for selected applications.

The following procedure gives some tips about modifying the SSO Sync filter properties and behavior.

To modify the SSO Sync Filter properties and behavior

  1. Disable the Filter: Change the system property "sso.filter.enable" to "false" (pass as -D to the jvm) and restart the Oracle WebLogic Server. This toggles the filter status.

  2. User-Identifying Header Differs from Pre-Configured Sync Filter Tokens: Over-ride the SSO token that the Sync Filter looks for using the system property "sso.filter.ssotoken".

    For example, pass to the WebLogic Server jvm in the WebLogic Server startup script -Dsso.filter.ssotoken=HEADERNAME, and restart the server.

When you contact Oracle Support you might be requested to set up debugging, as described in "Setting Up Debugging in the WebLogic Administration Console".

17.3 Troubleshooting for an OSSO Identity Asserter Deployment

The troubleshooting items described in this section are grouped into the following categories:

See Also:

17.3.1 SSO-Related Problems

This section addresses the following troubleshooting items:

OHS Is Not Redirecting to SSO - Internal Server Error 500

The most likely source of this problem is an incorrect configuration.

The following sample uses Oracle HTTP Server 11g. Path names are different if you have Oracle HTTP Server 10g.

To address it, proceed as follows:

  1. Open the file mod_osso.conf and ensure that the resource is protected. For example:

    ORACLE_INSTANCE/config/OHS/<ohs_name>/moduleconf/mod_osso.conf  
    
    <Location /protected-resource-uri>
    require valid-user
    AuthType Basic
    </Location>
    
  2. Ensure that osso.conf is present and included in mod_osso.conf. For example, using Oracle HTTP Server 11g (paths are different for 10g)

    OssoConfigFile  ORACLE_INSTANCE/config/OHS/<ohs_name>/osso/osso.conf  
    

    Note:

    There is no set location for osso.conf. The value is determined at registration time; it can be any absolute path.
  3. Ensure that httpd.conf includes mod_osso.conf. For example, using Oracle HTTP Server 11g (paths are different for 10g):

    ORACLE_INSTANCE/config/OHS/<ohs_name>/httpd.conf
    
    include /ORACLE_INSTANCE/config/OHS/<ohs_name>/moduleconf/mod_osso.conf
    
  4. If all of the above were correctly specified, the SSO registration did not complete successfully and you must re-register SSO.

    To register SSO, proceed as follows using the appropriate ssoreg tool for your platform. For example:

    1. Run ssoreg.sh in 10.1.4 ORACLE_HOME/sso/bin to produce the file osso.conf. The following is a sample usage of this utility that produces the file in /tmp/osso.conf (the arguments are displayed in different lines only for illustration):

      >ssoreg.sh -oracle_home_path /OraHome 
                 -site_name wls_server 
                 -config_mod_osso TRUE 
                 -mod_osso_url http://host.domain.com:6666 
                 -update_mode CREATE 
                 -remote_midtier 
                 -config_file /tmp/osso.conf
      
    2. Copy the generated osso.confto another file system directory. For example: ORACLE_INSTANCE/config/OHS/<ohs_name>/osso.

    3. Restart OHS.

Is Attribute AuthName Required?

Log messages might suggest that the attribute AuthName is required, and certain versions of Apache do require this attribute.

This example uses Oracle HTTP Server 11g. Path names are different for Oracle HTTP Server 10g.

To include this attribute, edit the file mod_osso.conf and insert a fragment like the following:

LoadModule osso_module modules/mod_osso.so
<IfModule mod_osso.c>
OssoIdleTimeout off
OssoIpCheck on
OssoConfigFile  ORACLE_INSTANCE/config/OHS/<ohs_name>/osso/osso.conf
 
<Location />
AuthName "Oracle Single Sign On"
require valid-user
AuthType Basic
</Location>
</IfModule>

URL Request not Redirected to SSO

Once a URL request is issued, if a basic pop-up is displayed instead of being redirected to SSO, then, most likely, the URL request has been intercepted by the Apache authorization module.

To address this problem, proceed as follows:

  1. Edit the file httpd.conf and comment out the loading authorization modules as illustrated in the following fragment:

    ORACLE_INSTANCE/config/OHS/<ohs_name>/httpd.conf
    
    LoadModule access_module modules/mod_access.so
    #LoadModule auth_module modules/mod_auth.so
    #LoadModule auth_anon_module modules/mod_auth_anon.so
    #LoadModule auth_db_module modules/mod_auth_dbm.so
    LoadModule proxy_module modules/mod_proxy.so
    
  2. Restart OHS.

Error 404 - Not Found is Issued (OHS Side)

Typically, this error has the following format:

The requested URL <request-uri> was not found on this server

Most likely, the WebLogic redirect is not happening, and the request is attempting to grab an OHS resource not available.

To address this problem, verify that mod_weblogic is included in the file httpd.conf and that the WebLogic handler is set for the request pattern, as illustrated in the following fragment:

#httpd.conf
<IfModule mod_weblogic.c> 
 WebLogicHost <host>
  WebLogicPort yourWlsPortNumber
</IfModule>
 
<Location /request-uri-pattern>
 SetHandler weblogic-handler
</Location>

Error 404 - Not Found is Issued (Oracle WebLogic Server Side)

Typically, this error has the following format:

Error 404--Not Found

Cause

This message informs that the Oracle WebLogic Server is not able to find a resource.

Solution

To address the problem, check that the resource is indeed deployed on the server. For example, if the pattern is /private1/Hello, check that Hello is accessible on the server with private1 as root.

Oracle SSO Failure - Unable to process request

Problem

You receive a message stating:

Oracle SSO Failure - Unable to process request
Either the requested URL was not specified in terms of a fully-qualified host
name or Oracle HTTP Server single sign-on is incorrectly configured.
Please notify your administrator. 

Solution

Modify the Oracle HTTP Server httpd.conf file to include a port number in the ServerName and restart the Web server. For example:

From: ServerName host.domain.com

To: ServerName host.domain.com:port

OSSO Solution for Applications Deployed on a Stand-alone WebLogic Server

This chapter describes how to configure single sign-on (SSO) for applications that are deployed on Oracle Fusion Middleware Oracle WebLogic Server. However, details for applications that are deployed on a stand-alone Oracle WebLogic Server (one without Fusion Middleware) are provided here:

  • Oracle Fusion Middleware with OSSO: The required OSSO Identity Asserter (ossoiap.jar) is provided automatically when you install Oracle Fusion Middleware: Oracle Identity Management, Oracle SOA Suite, or Oracle WebCenter.

    Note:

    Oracle Fusion Middleware with OSSO enables you to use either the Oracle HTTP Server 10g or 11g Web server.
  • Stand-Alone Oracle WebLogic Server with OSSO: The required OSSO Identity Asserter (ossoiap.jar) must be acquired from the Oracle Web Tier, as described here.

    Note:

    Without Fusion Middleware, OSSO requires Oracle HTTP Server 11g.

Whether you use OSSO for Oracle Fusion Middleware applications or other applications, the Identity Asserter performs the same functions as those illustrated and described in "Using the OSSO Identity Asserter".

Included in the following are additional, optional, details that you can use to configure and test Single Logout for session invalidation and synchronization between the SSO cookie and the JSESSIONID cookie. Required files must be acquired from the Oracle Web Tier.

Task overview: Deploying and configuring the OSSO Identity Asserter for applications on a stand-alone WebLogic Server

  1. Install Oracle WebLogic Server 10.3.1+ and other required components as follows:

    1. Perform Step 1, a-d as described in the "Task overview: Deploying and configuring the OSSO Identity Asserter for applications on a stand-alone WebLogic Server".

    2. Skip Step 1e and instead deploy your application.

  2. Create a WebLogic security domain with the weblogin domain extension template that is supplied with Oracle WebLogic Server and can be used from $WLS_HOME/common/bin/config.sh.

  3. Configure mod_weblogic to forward requests to Oracle WebLogic Server, as explained in "Configuring mod_weblogic".

  4. Register and configure the module mod_osso with the 10g SSO Server as a partner application, as described in "New Users of the OSSO Identity Asserter".

    1. Perform steps described in "Registering Oracle HTTP Server mod_osso with OSSO Server 10.1.4".

    2. Perform steps described in "Configuring mod_osso to Protect Web Resources".

  5. Add Authentication Providers to the appropriate security domain as follows:

    1. Acquire the OSSO Identity Asserter (ossoiap.jar from the Oracle Web Tier at:

      $ORACLE_INSTANCE/modules/oracle.ossoiap_11.1.1/ossoiap.jar  
      
    2. Copy ossoiap.jar into $WLS_HOME/wlserver_10.x/server/lib/mbeantype, then restart the Oracle WebLogic Server.

    3. Configure providers as described in "Adding Providers to a WebLogic Domain for OSSO".

  6. Configure the Oracle WebLogic Connection Filtering mechanism to create access control lists and accept requests from the hosts where Oracle HTTP Server and the front-end Web server are running, as explained in "Establishing Trust Between Oracle WebLogic Server and Other Entities".

    Note:

    Test the secured application to ensure that it is working with the default authenticator using the Oracle WebLogic Server host and port.
  7. Configure the application authentication method for the OSSO Identity Asserter (all web.xml files in the application EAR file must include CLIENT-CERT in the element auth-method), as explained in "Configuring the Application for the OSSO Identity Asserter".

    Note:

    Test the application with users authenticated by OSSO while accessing the application with the Oracle HTTP Server host and port.
  8. Optional: You can configure and test Single Logout [Session Invalidation and synchronization between the SSO cookie and JSESSIONID cookie] as follows:

    1. Acquire ssofilter.jar and configure Oracle WebLogic Server to use it as follows:

      1. Acquire ssofilter.jar from the Oracle Web Tier at:

      $ORACLE_INSTANCE/modules/oracle.ssofilter_11.1.1/ssofilter.jar  
      

      2. Copy it to an appropriate directory in Oracle Middleware home: WLS_INSTALL/Oracle/Middleware/modules directory, for example.

      3. Add the absolute path of ssofilter.jar to the Oracle WebLogic Server classpath (by editing the setDomainEnv.sh script POST_CLASSPATH variable or CLASSPATH variable).

    2. Deploy system-filters.war as a system filter, as follows:

      1. Acquire system-filters.war from the Oracle Web Tier at:

      $ORACLE_INSTANCE/modules/oracle.jrf_11.1.1/system-filters.war 
       
      

      2. Copy system-filters.war to an appropriate directory in Oracle Middleware home: WLS_INSTALL/Oracle/Middleware/modules directory, for example.

      3. Deploy system-filters.war as an application library: From the WebLogic Administration Console, click Deployment, select New, and choose the location of file.

      4. Restart the Oracle WebLogic Server, if asked.

    3. Enable Logs to verify that the SSOFilter is working, as follows:

      1. From the WebLogic Administration Console, click Domain, Environment, Servers, AdminServer.

      2. Click the Logging tab.

      3. From the Advanced drop-down, select "Minimum Severity to Log" as "Debug".

      4. From the Advanced drop-down, "Message destinations", select LogFile: Severity Level as "Debug".

      5. Save changes and restart the Oracle WebLogic Server.

    4. Confirm that the SSOFilter is loaded as a system filter:

      1. Open the AdminServer.log file in DomainHome/Servers/AdminServer/log/AdminServer.log.

      2. Search for "SSOFilter" and confirm that you can see <Debug> messages, which indicate SSOFilter initialization nd confirm a filter load

    5. Test the filter functionality to confirm that the SSO and JSESSIONID cookie are cleaned up after user logout and that attempts to access the application after logout require another login.

      Note:

      You must have OSSO Identity Asserter configured in the WebLogic security domain, otherwise the filter will automatically disable during its initialization.
    6. Test logout with applications to confirm that the session is ends cleanly.

SSO Users Specified in "Users to Always Audit" Must Be Uppercase

When you specify SSO users in the Oracle HTTP Server audit configuration "Users to Always Audit" section, the SSO username must be specified in uppercase characters.

A comma-separated list of users can be specified to force the audit framework to audit events initiated by these users. Auditing occurs regardless of the audit level or filters that have been specified. This is true for all authentication types.

For more information, see "Managing Audit Policies" in the chapter "Configuring and Managing Auditing" in the Oracle Fusion Middleware Application Security Guide.

17.3.2 OSSO Identity Asserter-Related Problems

This section addresses the following troubleshooting items:

Error 403 - Forbidden

This message informs that the user does not have the required permission to access a resource. This message is shown, for example, when the application has been configured to allow access to users belonging to WLS Group SSOUsers and the asserted user belongs to a different group.

If you have verified that this is not a permissions issue, then check whether the JAAS Control Flag for the Default Identity Authenticator is set to REQUIRED, and if so, change the setting to OPTIONAL or to SUFFICIENT, as appropriate.

Error 401 - Unauthorized

This message informs that the access to a resource requires the user to be first authenticated.

Solution

  1. Check that the user is indeed authenticated.

  2. Check whether the server is being hit without first going through authentication using SSO.

OSSO Identity Assertion Not Getting Invoked

Situations in which the OSSO Identity Asserter is not getting invoked for a protected source, typically, involve incorrect configuration. Make sure that your environment accurately includes a configuration as that described in "Configuring the Application for the OSSO Identity Asserter".

17.3.3 URL Rewriting and JSESSIONID

In some cases when an application resource (URL) is accessed and the JSESSIONID cookie is not found, WebLogic Server rewrites the URL by including the JSESSIONID as part of the URL. If the URL in question is protected, Oracle Access Manager and OSSO Web agents might have issues matching the re-written URL.

To avoid issues of a mismatch, you can append an asterisk, *, to the end of the protected resource specified in mod_osso.conf. For example, if the protected URL is:

/myapp/login

The location in the mod_osso entry would be:

<Location /myapp/login*>
valid user
AuthType OSSO
</Location>

17.3.4 About mod_osso, OSSO Cookies, and Directives

Mod_osso module provides communication between the SSO-enabled login server and the Oracle HTTP Server listener. The mod_osso module is controlled by editing the mod_osso.conf file:

This section provides the following information:

17.3.4.1 New OssoHTTPOnly Directive in mod_osso

A new configuration directive has been added to mod_osso to configure setting the HTTPOnly flag on OSSO cookies. The new Directive is: OssoHTTPOnly. Values are On (to enable) and Off (to disable) the flag. By default, the HTTPOnly flag is set to On; the directive is not set in the configuration.

This directive appends the HttpOnly flag to the OSSO cookies set in the browser. This purpose of this flag is to prevent cross-site scripting. Cookies that have this flag set are not accessible by javascript code or applets running on the browser. Cookies that have this flag set is only sent to the server that set the cookie for the particular domain across over http or https.

This is a per VirtualHost directive. It can only be set at the global scope or inside a VirtualHost section. The following example shows the new directive:

<VirtualHost *.7778> 
OssoConfigFile  conf/osso.conf
OssoHTTPOnly On
---
---
---
<Location /osso>
AuthType Osso
---
---
</Location> 

</VirtualHost> 

17.3.4.2 OssoSecureCookies Directive in mod_osso

In mod_osso 10g, the OssoSecureCookies directive is disabled by default. However, in mod_osso 11g, this behavior is enabled by default. In mod_osso 11g, to disable the OssoSecureCookies directive you must set OssoSecureCookies to Off in the corresponding configuration file. When mod_osso is enabled, the mod_osso.conf file is available at:

ORACLE_INSTANCE/config/OHS/<ohs_name>/moduleconf/mod_osso.conf

Set the OssoSecureCookies directive as follows:

OssoSecureCookies "Off"

17.3.4.3 Mod_osso Does Not Encode the Return URL

Mod_osso does not encode the return URL in the query when redirecting to the Oracle SSO Server for logout.

To fix this issue, the encoded URL must be passed. For example: response.setHeader("Osso-Return-Url", encoded-url)

17.3.4.4 mod_osso: "Page Not found" error After Default Installation

The following causes might result in a "Page Not Found" error when trying to display SSO page:

  • Multiple routing relationships with the same OHS in the absence of load balancer: This is not supported.

  • No routing relationship

Solutions: Multiple Routing Relationships

Locate and remove the extra routing relationship that is not related to this oc4j_im. Leave the routing relationship that is related to this oc4j_im.

  1. Use the following command to display all routing relationships in your environment:

    asctl:/imha/inst1/ohs_im>ls -a -l
    oc4j_im_ohs_im_routing_relationship -> /imha/inst12/oc4j_im 
    oc4j_im_ohs_im_routing_relationship_ -> /imha/inst11/oc4j_im 
    
  2. Remove the routing relationship that is not related to this specific oc4j_im using the following command with values for your environment. For example:

    asctl:/imha/inst1/ohs_im> rmrel(name='oc4j_im_ohs_im_routing_relationship_
    ',pt='/imha/inst11/oc4j_im')
    
  3. Stop and start both OHS Web server and oc4j_im.

  4. Confirm that the SSO page displays.

Solutions: No Routing Relationships

By default, the installer creates a routing relationship between each OHS and each oc4j_im. If there is no routing relationship between OHS and oc4j_im, you must create one.

  1. Use the following command to create a routing relationship using values for your environment:

    createRoutingRelationship(name='rr1',ut='/imha/inst1/ohs_im',pt='/imha/inst12/  
    @ oc4j_im') 
    
  2. Stop and start both OHS Web server and oc4j_im.

  3. Confirm that the SSO page displays.

17.3.5 About Using IPv6

Oracle Fusion Middleware supports Internet Protocol Version 4 (IPv4) and Internet Protocol Version 6 (IPv6.) Among other features, IPv6 supports a larger address space (128 bits) than IPv4 (32 bits), providing an exponential increase in the number of computers that can be addressable on the Web.

See Also:

Oracle Fusion Middleware Administrator's Guide for details about using IPv6 with the Oracle Single Sign-on Server.