3
PL/SQL Single Sign-On Application Programming Interface

This chapter explains how to use the PL/SQL Single Sign-On Application Programming Interface.

This chapter contains these topics:

Developing Partner Applications

The information in this section allows you to enable applications to participate in Single Sign-On by becoming partner applications. It discusses the application restructuring required. It also describes the basic architecture and explains where the API calls in this package are to be used.

This section contains these topics:

How a Partner Application Works

Partner applications delegate user authentication to the Login Server. When the application determines that this delegation is needed, it uses WWSEC_SSO_ENABLER_PRIVATE.GENERATE_REDIRECT to obtain the URL to which it performs the redirect.

As a result of this redirect, the Login Server:

Authenticates the user.
Calls a procedure that it is configured to call in the partner application. It makes this call by redirecting the browser to the specified procedure.

The procedure that the Login Server calls has a single VARCHAR2 parameter that has the default name URLC (an abbreviation for URL Cookie). This procedure should parse the encrypted value that is passed in this parameter by using the WWSEC_SSO_ENABLER_PRIVATE.PARSE_URL_COOKIE procedure. This parsing enables the partner application to obtain the ssousername and the urlrequested from the parameter.

The partner application should then establish an application session for the ssousername obtained from the parameter. Typically, this means that the application establishes a cookie for its own use, and may set up some session information internally. The application can then redirect to the urlrequested that is typically the protected URL that the user seeks to access.

Each application must develop its own convention for protecting pages that need authentication. Ideally, a well-defined procedure or function is established that all components of the application can use for access control. When it is determined that the user needs to be authenticated, then the application can perform the redirect to the Login Server from the single centralized place.

The Single Sign-On Process for a Partner Application

The figure that follows illustrates the Login Server authentication sequence used by Oracle Portal as a partner application.

Text description of ssign006.gif follows

Text description of the illustration ssign006.gif

The browser requests a URL. This URL could be a PL/SQL procedure in Oracle Portal. It also could be indirectly a PL/SQL procedure of the WWDOC_PROCESS.PROCESS_DOWNLOAD procedure that is invoked when requesting a document resident in Oracle Portal.

If the procedure has no security, then it simply returns HTML, resulting in the display of the page.
If the procedure applies access restrictions, then it calls internal Oracle Portal security APIs to check whether the current user has privileges on the current procedure. Typically, this is accomplished by calling an Oracle Portal security function, WWSEC_APP_PRIV.CHECK_PRIVILEGE. This function in turn checks whether the user is logged on by inspecting the current session information obtained from the portal_session cookie. If the user is not logged in, and, as a public user, has insufficient privileges to execute the procedure, then WWSEC_APP_PRIV.CHECK_PRIVILEGE must invoke the login sequence. Note that there will always be a portal_session cookie, because the Oracle Portal gateway establishes a public session if it cannot find an existing cookie. The cookie name is specified in the DAD, and if not specified, defaults to the DAD name.
To initiate the login sequence, Oracle Portal generates a redirect request to the Login Server, using enabler APIs provided by the Login Server to generate the token that is passed as a URL parameter. The token contains the name of the partner application, the URL that was requested in the partner application, and, optionally, another URL to return to if authentication is canceled by the user. The Login Server LS_LOGIN procedure checks for an SSO_ID cookie, referred to as the login cookie. It checks whether this specific browser has already performed a Login Server authentication within this session. If it has, then the Login Server uses the information in the login cookie and does not provide the user with another authentication challenge.
If the login cookie is not present, then the Login Server calls the SHOW_LOGIN_SCREEN procedure.
The Login Server presents a login page to the user, prompting the user for a user name and password.
The user enters a user name and password and submits the form.

The Login Server then authenticates the user's user name and password, using the configured authentication mechanism.

If the authentication fails, then the login page is displayed again with an error message.

If the user clicks Cancel on the login page, then the Login Server redirects the page to the cancel URL provided in the initial request (in Step 3).

If the authentication is successful, then the Login Server establishes a login cookie. The default name for this cookie is SSO_ID. It keeps track of the user name of the user that logged in, and the session expiry time.
The Login Server constructs a URL with an encrypted parameter containing the user's identity for processing by the partner application. The Login Server sends this URL to the partner application with the purpose of:
- Informing the partner application that the user has successfully authenticated
- Providing the user name with which the user authenticated
- Returning the URL that is being requested by the user
The URL to which this parameter is passed is stored in the Login Server configuration table. The Partner Application entry specifies:
- The URL that will process this parameter
- The name of the parameter itself
In Oracle Portal 3.0, the name of the procedure that processes this is WWSEC_APP_PRIV.PROCESS_SIGNON. The parameter name is URLC. This procedure uses the WWSEC_SSO_ENABLER_PRIVATE.PARSE_URL_COOKIE API to get the SSO user name and the requested URL. When this procedure is invoked, Oracle Portal converts the portal_session cookie to an authenticated cookie, updating the user name with the logged in user's name, and, if necessary, updating the associated db_user. Also, the WWCTX_SSO_SESSION$ table is updated with the updated session information. The session is then flagged as logged on.
Finally, the PROCESS_SIGNON procedure redirects the browser to the URL initially requested by the user. When invoking this page, the CHECK_PRIVILEGE function is again invoked, and, because the user is now logged in, it is possible to check whether the user has sufficient privilege, by using the APIs that query the Oracle Portal WWSEC_SYS_PRIV$ table, to invoke the procedure.

If the user has sufficient privileges, then the procedure executes. If the user does not have sufficient privileges, then an error page indicating insufficient privileges is displayed.

When a user later seeks access to secured pages, the CHECK_PRIVILEGE procedure sees the authenticated portal_session cookie, and does not need to interact with the Login Server. Instead, it uses the privilege APIs to determine whether the user has sufficient access privileges.

Functions and Procedures

The functions and procedures in this section are part of the WWSEC_SSO_ENABLER_PRIVATE package. This package is used to enable a PL/SQL application to become a partner application.

This section contains these topics:

PAPP_SHOW_CONFIG Procedure

This procedure returns enabler configuration information for a partner application.

Syntax


PROCEDURE PAPP_SHOW_CONFIG
(
    P_LSNR_TOKEN IN VARCHAR2
ENABLER_CONFIG IN OUT sec_enabler_config_type
);

Table 3-1 PAPP_SHOW_CONFIG Procedure Parameters

Parameter	Description
`P_LSNR_TOKEN`	Listener token to get the necessary partner application registration configuration
`ENABLER_CONFIG`	Enabler configuration type

Example

wwsec_sso_enabler_private.papp_show_config
(
   p_lsnr_token =>  listener token
   enabler_config => enabler configuration type
);

GENERATE_REDIRECT Function (URL Cookie Version V1.0)

This function generates a redirect URL along with SITE2PSTORETOKEN that the Login Server will parse.

Syntax

FUNCTION GENERATE_REDIRECT 
(
   P_LSNR_TOKEN IN VARCHAR2,
   URLREQUESTED IN VARCHAR2,
   URLONCANCEL IN VARCHAR2
) RETURN VARCHAR2;

Table 3-2 GENERATE_REDIRECT Function Parameters

Parameter	Description
`P_LSNR_TOKEN`	Listener token to get the necessary partner application registration configuration. The listener token is the host name and port used on the URL for the current request. This is used to select the appropriate configuration entry in the `WWSEC_ENABLER_CONFIG_INFO$` table.
`URLREQUESTED`	URL requested by the client for which authentication is needed
`URLONCANCEL`	URL to go to if client clicks cancel on the login page

Table 3-3 GENERATE_REDIRECT Function Return Values

Return Value Description

REDIRECTURL

URL to which the partner application must direct the browser to delegate authentication to the Login Server. This URL contains the request for authentication.

Return Value	Description
`REDIRECTURL`	URL to which the partner application must direct the browser to delegate authentication to the Login Server. This URL contains the request for authentication.

Example

WWSEC_SSO_ENABLER_PRIVATE.GENERATE_REDIRECT
(
    p_lsnr_token => listener token
   ,urlrequested => URL requested by the client for which authentication is 

                  needed
   ,urloncancel => URL to go to if client clicks cancel on the login page
);

Note:
Depending on the architecture of the system, it may be necessary for an application to be accessible through multiple web addresses. The partner application establishes an application session cookie to keep track of authenticated sessions. Since cookies have scoping properties, the session cookie needs to be scoped to the appropriate web address.
When a partner application requests authentication, the GENERATE_REDIRECT function creates the site2pstoretoken parameter, containing the ID of the partner application (site_id, site_token). This is used to look up the appropriate partner configuration on the Login Server. Also in the Login Server's partner configuration data is the URL that should be called on a successful authentication to establish the partner application's session. The URL for this 'Success URL' must have the same cookie scope (since it will be generating the cookie from this URL) as the requested URL. For this reason, each entry in the partner's configuration table must have a corresponding entry in the Login Server partner configuration file. The p_lsnr_token is what is used by the partner application to look up the appropriate configuration entry based on the current request. To establish the correct cookie scope, it needs to use a p_lsnr_token, which will retrieve the appropriate enabler entry. Typically, the p_lsnr_token should be the hostname.domain:port of the current request if the cookie path is scoped to the root "/." (without quotes) Otherwise, if the cookie is scoped down to a path, then the p_lsnr_token should include a path as well.

PARSE_URL_COOKIE Function (URL Cookie Version V1.0)

This function parses the URL cookie that is generated by the GENERATE_REDIRECT function on the Login Server side.

Syntax

PROCEDURE parse_url_cookie 
(
   P_LSNR_TOKEN        IN VARCHAR2,
   ENCRYPTED_URLCOOKIE IN VARCHAR2,
   SSOUSERNAME      IN OUT VARCHAR2, 
   IPADD            IN OUT VARCHAR2, 
   SSOTIMEREMAINING IN OUT NUMBER,
   SITETIMESTAMP    IN OUT DATE, 
   URLREQUESTED     IN OUT VARCHAR2, 
   NEWSITEKEY       IN OUT VARCHAR2
);

Table 3-4 PARSE_URL_COOKIE Function Parameters

Parameter	Description
`P_LSNR_TOKEN`	Listener token to get the necessary partner application registration configuration
`ENCRYPTED_URLCOOKIE`	URL cookie
`SSOUSERNAME`	SSO user name
`IPADD`	IP Address of user
`SSOTIMEREMAINING`	Time remaining on SSO session
`SITETIMESTAMP`	Timestamp at cookie generation
`URLREQUESTED`	URL that the client is attempting to access
`NEWSITEKEY`	Reserved for future use

Example

WWSEC_SSO_ENABLER_PRIVATE.PARSE_URL_COOKIE
(
    p_LSNR_TOKEN     => listener token
   ,ENCRYPTED_URLCOOKIE => URL cookie
   ,SSOUSERNAME      => ssousername
   ,IPADD            => IP Address of user
   ,SSOTIMEREMAINING => time remaining on SSO session
   ,SITETIMESTAMP    => timestamp at cookie generation
   ,URLREQUESTED     => URL that the client is authenticated to access
   ,NEWSITEKEY       => reserved for future use
);

GET_ENABLER_CONFIG Function

This function returns the partner application registration information specified by the listener token.

Syntax

PROCEDURE get_enabler_config 
(
    P_LSNR_TOKEN IN VARCHAR2
) RETURN sec_enabler_config_type;

Table 3-5 GET_ENABLER_CONFIG Function Parameters

Parameter	Description
`P_LSNR_TOKEN`	Listener token to get the necessary partner application registration configuration

Example


WWSEC_SSO_ENABLER_PRIVATE.GET_ENABLER_CONFIG
(
   p_lsnr_token => listener token
)

CREATE_ENABLER_CONFIG Procedure

This procedure stores the partner application registration information specified by the listener token into the enabler configuration table.

Syntax

PROCEDURE create_enabler_config 
(
    P_CONFIG IN sec_enabler_config_type
);

Table 3-6 CREATE_ENABLER_CONFIG Procedure Parameters

Parameter	Description
`P_CONFIG`	sec_enabler_config_type object which contains partner application registration information

Example

WWSEC_SSO_ENABLER_PRIVATE.CREATE_ENABLER_CONFIG
(
   p_config => sec_enabler_config_type object
)

UPDATE_ENABLER_CONFIG Procedure

This procedure updates the partner application registration information specified by the listener token.

Syntax

PROCEDURE update_enabler_config 
(
    P_LSNR_TOKEN IN VARCHAR2, 
    P_CONFIG     IN sec_enabler_config_type
);

Table 3-7 UPDATE_ENABLER_CONFIG Procedure Parameters

Parameter	Description
`P_LSNR_TOKEN`	Listener token to get the necessary partner application registration configuration
`P_CONFIG`	`sec_enabler_config_type` object which contains partner application registration information

Example

WWSEC_SSO_ENABLER_PRIVATE.UPDATE_ENABLER_CONFIG
(
   p_lsnr_token   => listener token
   ,p_config      => sec_enabler_config_type object
)

DELETE_ENABLER_CONFIG Procedure

This procedure deletes the partner application registration information specified by the listener token.

Syntax

PROCEDURE delete_enabler_config
(
    P_LSNR_TOKEN  IN VARCHAR2
);

Table 3-8 DELETE_ENABLER_CONFIG Procedure Parameters

Parameter	Description
`P_LSNR_TOKEN`	Listener token to get the necessary partner application registration configuration

Example

WWSEC_SSO_ENABLER_PRIVATE.DELETE_ENABLER_CONFIG
(
   p_lsnr_token =>  listener token
)

Exceptions

This section lists and describes the exceptions raised by the procedures and functions in this chapter.

Table 3-9 Exceptions

Exception	Description
`COOKIE_DECRYPTION_FAILED`	Decryption of URL parameter failed.
`COOKIE_ENCRYPTION_FAILED`	Creation of site2pstore token failed.
`DUP_ENABLER_EXCEPTION`	Site with the same name already exists.
`ENABLER_CONFIG_NOT_FOUND`	Could not find configuration information for partner site.
`MANDATORY_ATTRIBUTE_IS_NULL`	Login Server registration information is not correct.
`INVALID_IP_ADDRESS`	IP address contained in the URLC does not match the client's IP address.
`UNSUPPORTED_COOKIE_VERSION`	Cookie version is not supported.
`URL_COOKIE_EXPIRED`	URL cookie is timed out. The URLC parameter will time out if the user takes more than about 5 minutes to log in.

Datatype and Table Definitions

SEC_ENABLER_CONFIG_TYPE

This is the object type for partner application configuration.

CREATE OR replace TYPE sec_enabler_config_type AS object
  (
  lsnr_token              VARCHAR2(255)
  , site_token            VARCHAR2(255) 
  , site_id               VARCHAR2(255) 
  , ls_login_url          VARCHAR2(1000)
  , urlcookie_version     VARCHAR2(80)
  , encryption_key        VARCHAR2(1000)
  , encryption_mask_pre   VARCHAR2(1000)
  , encryption_mask_post  VARCHAR2(1000)
  , url_cookie_ip_check   VARCHAR2(1)
  );

WWSEC_ENABLER_CONFIG_INFO$

This table stores partner application configuration information.

create table wwsec_enabler_config_info$ OF sec_enabler_config_type
  (
  lsnr_token               constraint wwsec_seci_pk primary key
  , site_token             constraint wwsec_seci_uk1 UNIQUE
  , site_id                constraint wwsec_seci_uk2 UNIQUE 
  , ls_login_url          NOT NULL 
  , urlcookie_version      NOT NULL 
  , encryption_key         NOT NULL
  , encryption_mask_pre    NOT NULL 
  , encryption_mask_post   NOT NULL
  , CHECK (url_cookie_ip_check IN ('Y','N'))
  );

WWSEC_SSO_LOG

This table stores debug information when debug is enabled.

CREATE TABLE wwsec_sso_log$
(
    id  NUMBER
  , msg  VARCHAR2(1000) 
  , log_date DATE 
 );

3 PL/SQL Single Sign-On Application Programming Interface

Developing Partner Applications

How a Partner Application Works

The Single Sign-On Process for a Partner Application

Functions and Procedures

PAPP_SHOW_CONFIG Procedure

Syntax

Example

GENERATE_REDIRECT Function (URL Cookie Version V1.0)

Syntax

Example

PARSE_URL_COOKIE Function (URL Cookie Version V1.0)

Syntax

Example

GET_ENABLER_CONFIG Function

Syntax

Example

CREATE_ENABLER_CONFIG Procedure

Syntax

Example

UPDATE_ENABLER_CONFIG Procedure

Syntax

Example

DELETE_ENABLER_CONFIG Procedure

Syntax

Example

Exceptions

Datatype and Table Definitions

SEC_ENABLER_CONFIG_TYPE

WWSEC_ENABLER_CONFIG_INFO$

WWSEC_SSO_LOG

3
PL/SQL Single Sign-On Application Programming Interface