2
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?

• How Mod_osso Works

• About Dynamic Directives

• How Dynamic Directives Work

• Developing Applications Using Mod_osso

• Enabling IP Checking for Mod_osso

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 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 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	499	Osso-Paranoid: true
Single Sign-Off	470	Done-url 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

• Java Applications

• Java Applications That Use Dynamic Directives

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
     PlsqlCGIEnvironmentList   OSSO-USER-DN,OSSO-USER-GUID,OSSO-SUBSCRIBER,OSSO
   -SUBSCRIBER-DN,OSSO-SUBSCRIBER-GUID
   </Location>
   

2. Protect the application DAD by entering the following lines in the mod_osso.conf file:

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

   Note: 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
    is
    begin
       begin
           htp.init;
        exception
            when others then null;
        end;
        htp.htmlOpen;
        htp.bodyOpen;
        htp.print('<h2>Welcome to Oracle Single Sign-On</h2>');
        htp.print('<pre>');
        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('</pre>');
        htp.print('<a href=/osso_logout?'
           ||'p_done_url=http://my.oracle.com>Logout</a>');
   
        htp.bodyClose;
        htp.htmlClose;
   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 java.io.*;
   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
       {
           response.setContentType("text/html");
   
           // Show authenticated user information
           PrintWriter out = response.getWriter();
           out.println("<h2>Welcome to Oracle Single Sign-On</h2>");
           out.println("<pre>");
           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("</pre>");
           out.println("<a href=/osso_logout?"
               +"p_done_url=http://my.oracle.com>Logout</a>");
   
   

2. Protect the servlet by entering the following lines in the mod_osso.conf file:

   <Location/servlet>
      require valid-user
      authType Basic
   </Location>
   
   

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

Java Example #1: Simple Authentication

This servlet uses the function request.getRemoteUser() to check the mod_osso cookie for the user name. If the user name is absent. It issues dynamic directive 499, a request for simple authentication. The key lines are in boldface.

import java.io.*;
import javax.servlet.*;
import javax.servlet.http.*;

/**
 * Example servlet showing how to use
 * Dynamic Directive for login
 */

public class SSODynLogin extends HttpServlet
{

    public void service(HttpServletRequest request,
                      HttpServletResponse response)
        throws IOException, ServletException
    {
        String l_user     = null;

        // Try to get the authenticate user name
        try
        {
            l_user = request.getRemoteUser();
        }
        catch(Exception e)
        {
            l_user = null;
        }

        // If user is not authenticated then generate
        // dynamic directive for authentication
        if((l_user == null) || (l_user.length() <= 0) )
        {
            response.setHeader( "Osso-Paranoid", "false" );
            response.sendError(499, "Oracle SSO");
        }
        else
        {
            // Show authenticated user information
            response.setContentType("text/html");
            PrintWriter out = response.getWriter();
            out.println("<h2>Welcome to Oracle Single Sign-On</h2>");
            out.println("<pre>");
            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("</pre>");
        }
    }

Note: If Oracle JAAS Provider is used, the directive code 401 may be substituted for 499.

Java Example #2: Single Sign-Off

This servlet is invoked when users select the login link within an application. The application sets the URL to return to when sign-off is complete; then it issues a directive that sends users to the Single Sign-off page. The key lines are in boldface.

import java.io.*;
import javax.servlet.*;
import javax.servlet.http.*;

/**
 * Example servlet showing how to use
 * Dynamic Directive for logout
 */

public class SSODynLogout extends HttpServlet
{
    public void service (HttpServletRequest request,
        HttpServletResponse response)
        throws ServletException, IOException
    {
        // Set the return URL
        response.setHeader("Osso-Return-Url",
               "http://my.oracle.com" );
        // Send Dynamic Directive for logout
        response.sendError(470, "Oracle SSO");
    }
}

Java Example #3: Forced Authentication

If logged-in users have exceeded the global user inactivity timeout for a given Single Sign-On session, an application can force them to reauthenticate. The directive for reauthentication is written into the servlet that follows. If the user requesting access to this application is an administrator, the directive is not invoked. The key lines are in boldface.

Note: Before testing this application, make sure that the Single Sign-On server and mod_osso are configured for the global user inactivity timeout. To learn how to configure this timeout, see "Configuring the Global User Inactivity Timeout", in Chapter 2 of Oracle9iAS Single Sign-On Administrator's Guide.

import java.io.*;
import javax.servlet.*;
import javax.servlet.http.*;

/**
 * Example servlet showing how to use
 * Dynamic Directive for forced login
 */

public class SSODynForcedLogin extends HttpServlet
{

    public void service(HttpServletRequest request,
                      HttpServletResponse response)
        throws IOException, ServletException
    {
        String l_user = null;
        // Try to get the authenticate user name
        try
        {
            l_user = request.getRemoteUser();
        }
        catch(Exception e)
        {
            l_user = null;
        }

        // If the user is authenticated then show
        // user information; otherwise generate Dynamic
        // Directive for forced login
        if(l_user != null)
        {
            // Show authenticated user information
            PrintWriter out = response.getWriter();
            response.setContentType("text/html");
            out.println("<h2>Welcome to Oracle Single Sign-On.</h2>");
            out.println("<pre>");
            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("</pre>");
        }
        else
        {
            response.setHeader( "Osso-Paranoid", "true" );
            response.sendError(499, "Oracle SSO");
       }
    }
}

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.