Oracle9iAS Single Sign-On Application Developer's Guide Release 3.0.9 Part Number A90343-01 |
|
This chapter explains how to use the PL/SQL Single Sign-On Application Programming Interface.
This chapter contains these topics:
The information in this section allows you to enable applications to participate in Oracle9iAS 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:
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:
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 figure that follows illustrates the Login Server authentication sequence used by Oracle9iAS Portal as a partner application.
WWDOC_PROCESS.PROCESS_DOWNLOAD
procedure that is invoked when requesting a document resident in Oracle9iAS Portal.
If the procedure has no security, then it simply returns HTML, resulting in the display of the page.
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 Oracle9iAS Portal gateway establishes a public session if it cannot find an existing cookie. The cookie name is specified in the Database Access Descriptor (DAD), and if not specified, defaults to the DAD name.
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.
SHOW_LOGIN_SCREEN
procedure.
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 URL to which this parameter is passed is stored in the Login Server configuration table. The Partner Application entry specifies:
In Oracle9iAS Portal, 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, Oracle9iAS 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.
PROCESS_SIGNON
procedure redirects the browser to the URL initially requested by the user. The CHECK_PRIVILEGE
function is invoked. Because the user is logged in, it is possible to check whether the user has sufficient privilege, by using the APIs that query the Oracle9iAS Portal WWSEC_SYS_PRIV$
table, to invoke the procedure.
If the user has sufficient privileges, the procedure executes. If the user does not hve sufficient privileges, 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.
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:
This procedure returns enabler configuration information for a partner application.
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 |
---|---|
|
Listener token to get the necessary partner application registration configuration |
|
Enabler configuration type |
wwsec_sso_enabler_private.papp_show_config ( p_lsnr_token => listener token enabler_config => enabler configuration type );
This function generates a redirect URL along with SITE2PSTORETOKEN that the Login Server parses.
FUNCTION GENERATE_REDIRECT ( P_LSNR_TOKEN IN VARCHAR2, URLREQUESTED IN VARCHAR2, URLONCANCEL IN VARCHAR2 ) RETURN VARCHAR2;Table 3-2 GENERATE_REDIRECT Function Parameters
Return Value | Description |
---|---|
|
URL to which the partner application must direct the browser to delegate authentication to the Login Server. This URL contains the request for authentication. |
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 );
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.
This function parses the URL cookie that is generated by the GENERATE_REDIRECT
function on the Login Server side.
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, SUBSCRIBER_ID IN OUT NUMBER NEWSITEKEY IN OUT VARCHAR2 );Table 3-4 PARSE_URL_COOKIE Function Parameters
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 ,SUBSCRIBER_ID => Resend for future use ,NEWSITEKEY => reserved for future use );
This function returns the partner application registration information specified by the listener token.
PROCEDURE get_enabler_config ( P_LSNR_TOKEN IN VARCHAR2 ) RETURN sec_enabler_config_type;Table 3-5 GET_ENABLER_CONFIG Function Parameters
Parameter | Description |
---|---|
|
Listener token to get the necessary partner application registration configuration |
WWSEC_SSO_ENABLER_PRIVATE.GET_ENABLER_CONFIG ( p_lsnr_token => listener token )
This procedure stores the partner application registration information specified by the listener token into the enabler configuration table.
PROCEDURE create_enabler_config ( P_CONFIG IN sec_enabler_config_type );Table 3-6 CREATE_ENABLER_CONFIG Procedure Parameters
Parameter | Description |
---|---|
|
sec_enabler_config_type object which contains partner application registration information |
WWSEC_SSO_ENABLER_PRIVATE.CREATE_ENABLER_CONFIG ( p_config => sec_enabler_config_type object )
This procedure updates the partner application registration information specified by the listener token.
PROCEDURE update_enabler_config ( P_LSNR_TOKEN IN VARCHAR2, P_CONFIG IN sec_enabler_config_type );Table 3-7 UPDATE_ENABLER_CONFIG Procedure Parameters
WWSEC_SSO_ENABLER_PRIVATE.UPDATE_ENABLER_CONFIG ( p_lsnr_token => listener token ,p_config => sec_enabler_config_type object )
This procedure deletes the partner application registration information specified by the listener token.
PROCEDURE delete_enabler_config ( P_LSNR_TOKEN IN VARCHAR2 );Table 3-8 DELETE_ENABLER_CONFIG Procedure Parameters
Parameter | Description |
---|---|
|
Listener token to get the necessary partner application registration configuration |
WWSEC_SSO_ENABLER_PRIVATE.DELETE_ENABLER_CONFIG ( p_lsnr_token => listener token )
This section lists and describes the exceptions raised by the procedures and functions in this chapter.
Table 3-9 ExceptionsThis 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) );
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')) );
This table stores debug information when debug is enabled.
CREATE TABLE wwsec_sso_log$ ( , SUBSCRIBER_ID NUMBER NOT NULL , id NUMBER , msg VARCHAR2(1000) , log_date DATE );
|
Copyright © 2001 Oracle Corporation. All Rights Reserved. |
|