Oracle9iAS Single Sign-On Application Developer's Guide Release 2 (9.0.2) Part Number A96114-01 |
|
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:
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.
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."
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.
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.
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.
Table 2-1 lists commonly requested dynamic directives.
This section explains how to write and enable applications using mod_osso. The section covers the following topics:
Use the following steps to write and enable a PL/SQL application using mod_osso:
<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>
<Location /pls/DAD> require valid-user authType Basic </Location>
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;
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.
Use the following steps to write and enable a servlet or JSP application using mod_osso:
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>");
<Location/servlet> require valid-user authType Basic </Location>
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.
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:
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>"); } }
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"); } }
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"); } } }
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.
|
Copyright © 2002 Oracle Corporation. All Rights Reserved. |
|