How-To Document

Configure an Application Express Application as a Partner Application in Oracle AS Single Sign-On

Last Updated: 14-March-2008

After completing this How-To, you should understand:

  • How to download and install the SSO SDK.

  •
  • How to create the SSO authentication scheme in your Application Express application.

  •
  • How to register your Application Express installation as an SSO partner application.

  •
  • How to register your application schema as an SSO partner application.

Table of Contents

 

Introduction

For a given Oracle Application Express site, you can create as many different applications in as many different workspaces as you need to
and any of these applications can use authentication schemes based on the pre-configured scheme Oracle Application Server Single Sign-On (Oracle Application Express Engine as Partner App).

Disclaimer

The SSO Methodology and steps listed in this How To are only supported if the SSO SDK specified below is used.

Software Requirements Procedure to Register Oracle Application Express Instance as Partner Application
Step 1
  • Using the Application Express Application Builder, create your application.

Step 2

  • Using the Application Express Application Builder, use the create authentication scheme wizard to create an authentication scheme based on the pre-configured
    scheme Oracle Application Server Single Sign-On (Oracle Application Express Engine as Partner App).
  • Name the new authentication scheme anything you like, then click Create.
  • Make the new authentication scheme current for the application (click the Change Current sub-tab, and select the newly created authentication scheme, click Next>,
    and then Make Current).

Step 3

  • Determine the schema name used for your Application Express installation: it will be FLOWS_xxxxxx, where xxxxx represents a version like 030100.

Step 4 - Install the SSO SDK 

    a. As shown in the  
                                      
Using the PL/SQL and Java APIs section of the  
                                      
Oracle Application Server 10g R1 Single Sign-On Application Developer's Guide, 
       locate the single sign-on software developer kit at $ORACLE_OAS_HOME/sso/lib/ssosdk902.zip and unzip it into a local directory.  (Please note that it is not
       necessary to install the full  
                                      
Oracle Application Server 10gR1 to acquire the ssosdk902.zip file.  During the installation process an option to install only the "10as Developer Kits" is provided.)
    b. Load the SSO SDK objects into the FLOWS_xxxxxx schema as shown in step Aii of the ReadMe.txt document provided in ssosdk902.zip, and then log out of sqlplus.
    c. Follow the directions provided in Step D also in the provided ReadMe.txt
                                      


       Note: The  
                                      
ssosdk_schema_name and  
                                      
SSOSDK schema mentioned in the Readme.txt refer to the FLOWS_xxxxxx.

          i.When you get to the SSO administration form (the Single Sign-On Administrator's Guide provides directions to access this form) that asks for the partner app information, 
            use the following examples as a guideline:   

            home url: http://host:port/pls/some_dad/htmldb
            success url: http://host:port/pls/some_dad/wwv_flow_custom_auth_sso.process_success
            logout url: http://host:port/pls/some_dad/htmldb
       
            Note: The values for 'home url' and 'logout url' registered with SSO don't really do 
                  anything unless you're trying to integrate your app with the login server's 
                  Single Sign-Out page. So if you did have multiple applications using the single 
                  registered partner app, and you wanted 'home url' to be a useful link, you could 
                  make 'home url' (as registered with SSO) be a page (based anywhere) that shows a 
                  menu of applications with different login links, and the SSO 'logout' URL could 
                  be made similarly generic. (Detailed nformation on enabling single sign-out from 
                  within your application is available in the  
                                      
Oracle(R) Application Server Single Sign-On Application Developer's Guide) 
       
         ii.When you start entering values for regapp.sql, note that the listener_token for the 
            partner app is supposed to be in this format:
  
                app_name:your-host:port
        
            You must use the case-sensitive string, "HTML_DB", as the app_name. So the value you enter would be something like:

                HTML_DB:www.myserver.com:80

            Also when running regapp.sql, note that the requested values for site_token, login_url, site_id and encryption_key respectively
                refer to the Token, Login URL, ID, and Encryption Key values that result from registering your applicaton with the SSO 
                server as instructed in Step 4ci of this document.

Step 5 - (only necessary if SSO SDK was installed after installing Application Express) 

    a. Locate the custom_auth_sso source files for your Application Express installation.
    b. Connect as SYS and from the location of the files run:
        alter session set current_schema = flows_xxxxxx;
        @custom_auth_sso.sql
        @custom_auth_sso.plb
        grant execute on wwv_flow_custom_auth_sso to public;

Step 6

  • Test your application. If SSO doesn't work, you can run @secdbg.sql (from the packages directory of the SSO SDK) and then
    browse the WWSEC_SSO_LOG$ table for a trace of data exchanged between the login server and the components on your side.

Step 7

  • Repeat steps 1 and 2 for each Oracle Application Express application that is to use Oracle AS Single Sign-On. (At this time, all applications so configured must use the same protocol,
    host, port, and DAD as those used in the 'success url', but the applications may exist in different workspaces.)
  • Repeat steps 4c through 6 when you upgrade Oracle Application Express and it installs into a new FLOWS_xxxxxx schema. You can copy the old
    registration key values from the SSO SDK table WWSEC_ENABLER_CONFIG_INFO$ which you will find in the old FLOWS_xxxxxx schema. To avoid having to do this work after an Application Express upgrade,
    an alternate method is to install the SSO SDK into its own schema, say HTMLDB_SSO, which you would create. Then run these statements after you install the SSO SDK initially and again for each new flows_xxxxxx schema that comes along with Application Express upgrades: 
         Connect as SYS and from the location of the files run:
        alter session set current_schema = flows_xxxxxx;
        create synonym wwsec_enabler_config_info$ for htmldb_sso.wwsec_enabler_config_info$;
        create synonym wwsec_sso_enabler_private for htmldb_sso.wwsec_sso_enabler_private;
        
        connect htmldb_sso
        grant execute on wwsec_sso_enabler_private to flows_xxxxxx;
        grant select on wwsec_enabler_config_info$ to flows_xxxxxx;
    If you install the SSO SDK into its own schema, be sure to use that as the partner schema name in step 4, above.

With the approach just described you only have to install the SSO SDK once per Oracle Application Express instance, and you only need to register one application. No matter which application is accessed,
the SSO server will redirect back to registered 'success' procedure after login which will, in turn, redirect to the requested application/page.

Alternate Procedure for Individual Registration of Partner Application Schemas

This alternative approach allows you to install the SSO SDK into Oracle Application Express workspace schemas controlled by workspace developers, so you don't have to allow access to the FLOWS_xxxxxx schema to developers who are trying to debug SSO authentication. It also gives developers more flexibility if they want to tweak the configuration without affecting other users/workspaces in the Oracle Application Express site, for example, if they want to test their SSO-authenticated applications with their own AS/SSO infrastructure. Note: This option will not work in Application Express versions prior to 1.5.1.

Multiple applications in a workspace can refer to the same registered partner application "record" in their authentication schemes. No matter which application is accessed, the SSO server will redirect back to registered 'success' procedure after login which will, in turn, redirect to the requested application/page.. At this time, applications must use the same protocol, host, port, and DAD as those used in the partner application's success url, as registered. After you get SSO working for one application, create an authentication scheme for the next application as a copy of the first (copy and subscribe works too). The partner application name is the key to the registration "record" in the SSO SDK schema.

  1. Do steps 1 - 3 (above), but in step 2, create the authentication scheme based on the pre-configured scheme Oracle Application Server Single Sign-On (My Application as Partner App). The wizard will ask for your partner application name. Enter 'MY_PARTNER_NAME' (we'll use that for the rest of this example. You can enter a different name, just use the same name where it's expected in other places and don't put whitespace in the name).
  2. Perform steps 4a and 4b (above) to install the SSO SDK in the FLOWS_xxxxxx schema, then do steps 5 - 7 (above). (The purpose of doing steps 4a-4b is so that the SSO packages owned by FLOWS_xxxxxx will compile in step 5, above.)
  3. Now go back and perform all of step 4 (above) with the following changes:
    • Instead of FLOWS_xxxxxx, use your application's schema as partner_schema_name
    • For success URL in step 4c, enter:
    •         http://host:port/pls/some_dad/YOUR_APP_SCHEMA.YOUR_PACKAGE.PROCESS_SUCCESS
    • When you start entering values for regapp.sql in step 4c (above), for the listener_token use the case-sensitive string, "MY_PARTNER_NAME", as the app_name. So the value you enter would be something like:
    •         MY_PARTNER_NAME:www.myserver.com:80
  4. Create a package (YOUR_PACKAGE) in YOUR_APP_SCHEMA with a PROCESS_SUCCESS procedure that does this (notice where the case-sensitive partner app name is coded):
  5.     procedure process_success(
        urlc in varchar2)
    as
    begin
        wwv_flow_custom_auth_sso.process_success(
            urlc=>urlc,
            p_partner_app_name=>'MY_PARTNER_NAME');
    end process_success;
  6. The schema YOUR_APP_SCHEMA must not be a schema used by multiple workspaces.
  7. Grant execute on YOUR_APP_SCHEMA.YOUR_PACKAGE to public (or at least to the DAD user).

Repeat the steps in this procedure for each application schema for which you want to register partner applications. Be sure to use a different partner name each time, while ensuring that the name used in each process_success procedure matches the name you entered in regapp.sql.

Additional Resources

Oracle Application Express Home

Discuss this how-to in the Oracle Application Express Discussion Forum.

Left Curve
Popular Downloads
 Right Curve
Untitled Document