Skip Headers

Oracle9iAS Single Sign-On Application Developer's Guide
Release 2 (9.0.2)

Part Number A96114-01
Go To Documentation Library
Go To Product List
Solution Area
Go To Table Of Contents
Go To Index

Go to previous page Go to next page

Developing Applications Using Mod_osso

This chapter explores the role that the HTTP authentication module mod_osso plays in Oracle Single Sign-On. In addition, it explains how to develop applications to work with mod_osso.

The chapter covers the following topics:

Why Mod_osso?

In earlier releases of Oracle Single Sign-On, applications were expected to integrate with the Single Sign-On server using the Single Sign-On SDK. The SDK gave them full control over their interaction with the server, but it exacted a setup cost for registering an application. In Oracle9iAS, Release 2, an HTTP module called mod_osso, not the application, provides client-side Single Sign-On functionality.

Mod_osso eases Single Sign-On integration, but it also takes away the granular control that applications have when they use the SDK. Fortunately, a new communication mechanism between applications and mod_osso restores this granular control. This mechanism is called the dynamic directive.

How Mod_osso Works

Figure 2-1 shows what happens when a user requests a URL protected by mod_osso. To understand how the process differs from SDK-enabled authentication, see "Authentication Flow in SDK-Enabled Single Sign-On" in Chapter 3, "Single Sign-On Software Development Kit."

Figure 2-1 Single Sign-On with Mod_osso

Text description of ssoag004.gif follows
Text description of the illustration ssoag004.gif

  1. The user requests a URL through a Web browser

  2. The Web server looks for a mod_osso cookie for the user. If the cookie exists, the Web server extracts the user's information and uses it to log the user in to the requested application.

  3. If the cookie does not exist, mod_osso redirects the user to the Single Sign-On server.

  4. The Single Sign-On server looks for its own cookie in the browser. If it finds none, it tries to authenticate the user with a user name and password. If authentication is successful, the Single Sign-On server creates a cookie in the browser as a reminder that the user has been authenticated. If a cookie exists, the Single Sign-On server will authenticate using the cookie.

  5. The Single Sign-On server returns the user's encrypted information to mod_osso.

  6. Mod_osso creates its own cookie for the user in the browser and redirects the user to the requested URL.

If, during the same session, the user again seeks access to the same or to a different application, the user is not prompted for a user name and password; the application uses an HTTP header to obtain this information from the mod_osso session cookie.

Mod_osso redirects the user to the Single Sign-On server only if the requested URL is protected. Some protected applications may have public URLs. These require no redirection to the Single Sign-On server.

About 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.

Oracle9iAS, Release 2, supports dynamic directives for Java servlets and JSPs. The Oracle stack for supporting these applications consists of the OC4J engine and a corresponding HTTP module, mod_oc4j, which communicates Web requests to the OC4J engine.

How Dynamic Directives Work

When an application protected by mod_osso wants the Single Sign-On server to perform some action--for example, authentication or single sign-off--it creates an HTTP response whose header contains a dynamic directive status code understood by mod_osso. In addition, the application might want to provide values that are relevant to that directive. The status code for the login directive, for example, is 401. In addition to this code, the directive might contain the header "Osso_Paranoid", "false", indicating a simple authentication request. The response header might look like this:

      HTTP/1.1   499  Oracle SSO
      Osso_Paranoid: false

When mod_oc4j looks at an HTTP response and determines that it is a dynamic directive, it passes this directive to mod_osso. A simple response, on the other hand, is passed directly to the HTTP core. The directive handler function for mod_osso constructs the appropriate Single Sign-On protocol message indicating to the Single Sign-On server whether the application is requesting simple dynamic authentication, forced authentication, global sign-off, and so on. The handler then constructs a redirect response and passes it to the HTTP core, which passes it to the Web client. The process is illustrated in Figure 2-2. The black flow lines denote dynamic directives; the white lines simple directives.

Figure 2-2 HTTP Response Path for Dynamic Directives

Text description of ssoag007.gif follows
Text description of the illustration ssoag007.gif

Table 2-1 lists commonly requested dynamic directives.

Table 2-1 Commonly Requested Dynamic Directives
Directive Status Code Headers

Request Authentication

401, 499

Osso-Paranoid: false

Note that this header need not be set at all

Request Forced Authentication


Osso-Paranoid: true

Single Sign-Off



This is the URL to return to after single sign-off is complete

Developing Applications Using Mod_osso

This section explains how to write and enable applications using mod_osso. The section covers the following topics:

PL/SQL Applications

Use the following steps to write and enable a PL/SQL application using mod_osso:

  1. Create a database access descriptor (DAD) for the application in the dads.conf file, as follows:

    <Location /pls/DAD_name>
      SetHandler pls_handler
      Order deny,allow
      AllowOverride None
      PlsqlDatabaseConnectString    hostname:port:SID
      PlsqlDatabasePassword         schema_password
      PlsqlDatabaseUsername         schema_name
      PlsqlDefaultPage              schema.home
      PlsqlDocumentTablename        schema.wwdoc_document
      PlsqlDocumentPath             docs
      PlsqlDocumentProcedure        schema.wwdoc_process.process_download
      PlsqlAuthenticationMode       Basic
      PlsqlPathAlias                url
      PlsqlPathAliasProcedure       schema.wwpth_api_alias.process_download
      PlsqlSessionCookieName        schema
  2. Protect the application DAD by entering the following lines in the mod_osso.conf file:

         <Location /pls/DAD>
           require valid-user
           authType Basic


    The assumption here is that mod_osso is already configured for Single Sign-On. This step can be performed when iAS is installed.

  3. Write application functions and procedures in the application schema associated with the DAD.

    What follows is an example of a simple mod_osso-protected application. This application logs the user in to the Single Sign-On server, displays user information, and then logs the user out of both the application and Single Sign-On.

    create or replace procedure show_user_info
             when others then null;
         htp.print('<h2>Welcome to Oracle Single Sign-On</h2>');
         htp.print('Remote user: '
            || owa_util.get_cgi_env('REMOTE_USER'));
         htp.print('User DN: '
            || owa_util.get_cgi_env('Osso-User-Dn'));
         htp.print('User Guid: '
            || owa_util.get_cgi_env('Osso-User-Guid'));
         htp.print('Subscriber: '
            || owa_util.get_cgi_env('Osso-Subscriber'));
         htp.print('Subscriber DN: '
            || owa_util.get_cgi_env('Osso-Subscriber-Dn'));
         htp.print('Subscriber Guid: '
            || owa_util.get_cgi_env('Osso-Subscriber-Guid'));
         htp.print('<a href=/osso_logout?'
    end show_user_info;
    show errors;
    grant execute on show_user_info to public;
  4. To test whether the newly created functions and procedures are protected by mod_osso, try to access them from a browser:

    http://apache_host:port/pls/DAD. [Function | Procedure]

Selecting the URL should invoke the Single Sign-On login page if the mod_osso.conf file has been configured properly and mod_osso is registered with the Single Sign-On server.

Java Applications

Use the following steps to write and enable a servlet or JSP application using mod_osso:

  1. Write the JSP or servlet. Like the PL/SQL application example immediately preceding, the simple servlet that follows logs the user in, displays user information, and then logs the user out.

    import javax.servlet.*;
    import javax.servlet.http.*;
     * Example servlet showing how to get the SSO User information
    public class SSOProtected extends HttpServlet
        public void service(HttpServletRequest request,
                          HttpServletResponse response)
            throws IOException, ServletException
            // Show authenticated user information
            PrintWriter out = response.getWriter();
            out.println("<h2>Welcome to Oracle Single Sign-On</h2>");
            out.println("Remote user: "
                + request.getRemoteUser());
            out.println("Osso-User-Dn: "
                +  request.getHeader("Osso-User-Dn"));
            out.println("Osso-User-Guid: "
                +  request.getHeader("Osso-User-Guid"));
            out.println("Osso-Subscriber: "
                +  request.getHeader("Osso-Subscriber"));
            out.println("Osso-User-Dn: "
                +  request.getHeader("Osso-User-Dn"));
            out.println("Osso-Subscriber-Dn: "
                +  request.getHeader("Osso-Subscriber-Dn"));
            out.println("Osso-Subscriber-Guid: "
                +  request.getHeader("Osso-Subscriber-Guid"));
            out.println("Lang/Territory: "
                + request.getHeader("Accept-Language"));
            out.println("<a href=/osso_logout?"
  2. Protect the servlet by entering the following lines in the mod_osso.conf file:

       require valid-user
       authType Basic
  3. Test the servlet by trying to access it from the browser. As in the PL/SQL example, selecting the URL should invoke the Single Sign-On Login page.

    The process is this: when users try to access the servlet from the browser, they are redirected to the Single Sign-On server for authentication. Next they are redirected back to the servlet, which displays user information. Users may then select the logout link to log out of the application as well as the Single Sign-On server.

Java Applications That Use Dynamic Directives

Applications that use dynamic directives require no entry in the mod_osso.conf file because mod_osso protection is written directly into the application as one or more dynamic directives. The servlets that follow show how such directives are incorporated. Like their "static" counterparts, these "dynamic" applications generate user information.

This section covers the following topics:

Java Example #1: Simple Authentication

Java Example #2: Single Sign-Off

Java Example #3: Forced Authentication

Enabling IP Checking for Mod_osso

Mod_osso uses the directive OssoIPCheck to verify that the user who authenticates to the Single Sign-On server is the same user who is accessing a mod_osso-protected application.

To enable mod_osso for IP checks, the directive OssoIPCheck in the httpd.conf file must be set to on. Note, however, that OssoIPCheck should be enabled only if a browser can communicate with both the Single Sign-On server and the HTTP server without using proxy servers. If proxies are used, and the directive OssoIpCheck is enabled, an error message might be displayed. This is because proxies might not use static IP addresses.

Go to previous page Go to next page
Copyright © 2002 Oracle Corporation.

All Rights Reserved.
Go To Documentation Library
Go To Product List
Solution Area
Go To Table Of Contents
Go To Index