Skip Headers

Oracle9iAS Single Sign-On Application Developer's Guide
Release 2 (9.0.2)

Part Number A96114-01
Go To Documentation Library
Home
Go To Product List
Solution Area
Go To Table Of Contents
Contents
Go To Index
Index

Go to previous page Go to next page

3
Single Sign-On Software Development Kit

The Oracle9iAS Single Sign-On Software Development Kit (SDK) consists of application programming interfaces (APIs) for PL/SQL and Java. These APIs are used to create partner applications--that is, applications enabled for Single Sign-On. Chapter 4, "Using the PL/SQL and Java APIs", provides code that shows how the APIs might be implemented.

The chapter covers the following topics:

Authentication Flow in SDK-Enabled Single Sign-On

Applications that use the SDK to enable Single Sign-On are required to implement the functions and procedures in the package WWSEC_SSO_ENABLER if PL/SQL is the language of implementation. The classes in oracle.security.sso.enabler are used if Java is the language of choice. Applications that are integrated with the SDK are called partner applications. They incorporate logic that enables them to delegate authentication, but not authorization, to the Single Sign-On server.

Figure 3-1 illustrates the authentication steps in SDK-enabled Single Sign-On. To understand how the process differs from mod_osso authentication, see "How Mod_osso Works" in Chapter 2, "Developing Applications Using Mod_osso."

Figure 3-1 Authentication Flow for SDK-Enabled Single Sign-On

Text description of ssoag009.gif follows
Text description of the illustration ssoag009.gif

  1. The user requests a URL for Partner Application A.

  2. The user is redirected to the Single Sign-On server.

  3. The Single Sign-On server presents the user with the Single Sign-On login form. He uses this form to submit his user name and password.

  4. The Single Sign-On server validates the user's password by checking it against Oracle Internet Directory. It also retrieves user attributes--specifically, the user's distinguished name and globally unique user ID.

  5. The user is redirected to the success URL. This URL passes the URLC token to the application. The URLC token contains the user's information.

  6. The application success URL sets the application session cookie and then redirects the user to the requested URL.

If the authenticated user requests Partner Application B, he need not authenticate again. The Single Sign-On server retrieves his credentials from the Single Sign-On cookie upon redirect (Step 2).

PL/SQL APIs

This section covers the following topics:

Functions and Procedures

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

The section covers the following functions and procedures:

GENERATE_REDIRECT Function

This function generates a redirect URL, along with SITE2PSTORETOKEN, that the Single Sign-On server parses.

Syntax

FUNCTION GENERATE_REDIRECT 
(
     P_LSNR_TOKEN    IN  VARCHAR2
   , P_URL_REQUESTED IN  VARCHAR2
   , P_URL_CANCEL    IN  VARCHAR2
   , P_FORCED_AUTH   IN  NUMBER DEFAULT SIMPLE_AUTH
) RETURN VARCHAR2;
Table 3-1 Parameters for GENERATE_REDIRECT
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.

P_URL_REQUESTED

URL requested by the client.

P_URL_CANCEL

URL that users are directed to if they select cancel on the login page.

P_FORCED_AUTH

Forced authentication flag.

REDIRECTURL

URL to which the partner application must direct the browser to delegate authentication to the Single Sign-On server. This URL contains the request for authentication.

Example

WWSEC_SSO_ENABLER.GENERATE_REDIRECT
(
  p_lsnr_token    => listener token
  p_url_requested => requested url
  p_url_cancel    => cancel url
  p_forced_auth   => forced authentication flag
  redirecturl     => redirect url 
);

PARSE_URL_COOKIE Procedure

This procedure parses the URL cookie that is generated by the GENERATE_REDIRECT function on the Single Sign-On server side.

Syntax

PROCEDURE parse_url_cookie 
(
     P_LSNR_TOKEN            IN   VARCHAR2
   , P_ENC_URL_COOKIE        IN   VARCHAR2
   , P_URL_REQUESTED         OUT  VARCHAR2
   , P_SSO_USERNAME          OUT  VARCHAR2
   , P_SSO_USER_DN           OUT  VARCHAR2
   , P_SSO_USER_GUID         OUT  VARCHAR2
   , P_SUBSCRIBER_NAME       OUT  VARCHAR2
   , P_SUBSCRIBER_DN         OUT  VARCHAR2
   , P_SUBSCRIBER_GUID       OUT  VARCHAR2
   , P_USER_IPADDRESS        OUT  VARCHAR2
   , P_SSO_TIMEREMAINING     OUT  NUMBER
   , P_NLS_LANGUAGE          OUT  VARCHAR2
   , P_NLS_TERRITORY         OUT  VARCHAR2
);
Table 3-2 Parameters for PARSE_URL_COOKIE
Parameter Description

P_LSNR_TOKEN

Listener token

P_ENC_URL_COOKIE

Encrypted URL cookie

P_URL_REQUESTED

Requested URL

P_SSO_USERNAME

Authenticated Single Sign-On user name

P_SSO_USER_DN

Authenticated Single Sign-On user DN

P_SSO_USER_GUID

Authenticated Single Sign-On user GUID

P_SUBSCRIBER_NAME

Subscriber name

P_SUBSCRIBER_DN

Subscriber DN

P_SUBSCRIBER_GUID

Subscriber GUID

P_USER_IPADDRESS

IP address of the Single Sign-On user's machine

P_SSO_TIMEREMAINING

Remaining Single Sign-On session duration

P_NLS_LANGUAGE

language selection of Single Sign-On user

P_NLS_TERRITORY

territory selection of Single Sign-On user

Example

WWSEC_SSO_ENABLER.PARSE_URL_COOKIE
(
   p_lsnr_token        => listener token
   p_enc_url_cookie    => encrypted URL cookie
   p_url_requested     => requested URL
   p_sso_username      => authenticated SSO username
   p_sso_user_dn       => authenticated SSO user DN
   p_sso_user_guid     => authenticated SSO user GUID
   p_subscriber_name   => subscriber name
   p_subscriber_dn     => subscriber DN
   p_subscriber_guid   => subscriber GUID
   p_user_ipaddress    => ipaddress of the sso user's machine
   p_sso_timeremaining => remaining Single Sign-On session duration
   p_nls_language      => language selection of sso user
   p_nls_territory     => territory selection of sso user
 );

GET_ENABLER_CONFIG Procedure

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

Syntax

PROCEDURE GET_ENABLER_CONFIG 
(
    P_LSNR_TOKEN            IN   VARCHAR2,
    P_SITE_TOKEN            OUT  VARCHAR2,
    P_SITE_ID               OUT  VARCHAR2,
    P_LS_LOGIN_URL          OUT  VARCHAR2,
    P_LS_LOGOUT_URL         OUT  VARCHAR2,
    P_URL_COOKIE_VERSION    OUT  VARCHAR2,
    P_ENCRYPTION_KEY        OUT  VARCHAR2,
    P_IPADDR_CHECK          OUT  VARCHAR2
);
Table 3-3 Parameters for GET_ENABLER_CONFIG
Parameter Description

P_LSNR_TOKEN

Listener token

P_SITE_TOKEN

Site token

P_SITE_ID

Site token

P_LS_LOGIN_URL

Login url of SSO Server

P_LS_LOGOUT_URL

Single Sign-Off URL of SSO Server

P_URL_COOKIE_VERSION

URL cookie version

P_ENCRYPTION_KEY

Encryption key

P_IPADDR_CHECK

If IP address should be verified

Example

WWSEC_SSO_ENABLER_PRIVATE.GET_ENABLER_CONFIG
(
   p_lsnr_token          =>  listener token
   p_site_token          =>  site token
   p_site_id             =>  site token
   p_ls_login_url        =>  login url of SSO Server
   p_ls_logout_url       =>  Single Sign-Off URL of SSO Server
   p_url_cookie_version  =>  url cookie version
   p_encryption_key      =>  encryption key
   p_ipaddr_check        =>  if ip address should be verified

CREATE_ENABLER_CONFIG Procedure

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

Syntax

PROCEDURE CREATE_ENABLER_CONFIG 
(
    P_LSNR_TOKEN           IN  VARCHAR2,
    P_SITE_TOKEN           IN  VARCHAR2,
    P_SITE_ID              IN  VARCHAR2,
    P_LS_LOGIN_URL         IN  VARCHAR2,
    P_LS_LOGOUT_URL        IN  VARCHAR2,
    P_URL_COOKIE_VERSION   IN  VARCHAR2,
    P_ENCRYPTION_KEY       IN  VARCHAR2,
    P_IPADDR_CHECK         IN  VARCHAR2
);
Table 3-4 Parameters for CREATE_ENABLER_CONFIG
Parameter Description

P_LSNR_TOKEN

Listener token

P_SITE_TOKEN

Site token

P_SITE_ID

Site token

P_LS_LOGIN_URL

Login URL of the Single Sign-On server

P_LS_LOGOUT_URL

Single Sign-Off URL of the Single Sign-On server

P_URL_COOKIE_VERSION

URL cookie version

P_ENCRYPTION_KEY

Encryption key

P_IPADDR_CHECK

If IP address should be verified or not

Example

WWSEC_SSO_ENABLER.CREATE_ENABLER_CONFIG
(
   p_lsnr_token          =>  listener token
   p_site_token          =>  site token
   p_site_id             =>  site token
   p_ls_login_url        =>  login url of SSO Server
   p_ls_logout_url       =>  Single Sign-Off URL of the Single Sign-On server
   p_url_cookie_version  =>  URL cookie version
   p_encryption_key      =>  Encryption key
   p_ipaddr_check        =>  If IP address should be verified
)  

MODIFY_ENABLER_CONFIG Procedure

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

Syntax

PROCEDURE MODIFY_ENABLER_CONFIG 
(
    P_LSNR_TOKEN           IN  VARCHAR2,
    P_SITE_TOKEN           IN  VARCHAR2,
    P_SITE_ID              IN  VARCHAR2,
    P_LS_LOGIN_URL         IN  VARCHAR2,
    P_LS_LOGOUT_URL        IN  VARCHAR2,
    P_URL_COOKIE_VERSION   IN  VARCHAR2,
    P_ENCRYPTION_KEY       IN  VARCHAR2,
    P_IPADDR_CHECK         IN  VARCHAR2
);
Table 3-5 Parameters for UPDATE_ENABLER_CONFIG
Parameter Description

P_LSNR_TOKEN

Listener token

P_SITE_TOKEN

Site token

P_SITE_ID

Site token

P_LS_LOGIN_URL

Login url of SSO Server

P_LS_LOGOUT_URL

Single Sign-Off URL of SSO Server

P_URL_COOKIE_VERSION

URL cookie version

P_ENCRYPTION_KEY

Encryption key

P_IPADDR_CHECK

If IP address should be verified or not

Example

WWSEC_SSO_ENABLER.MODIFY_ENABLER_CONFIG
(
   p_lsnr_token          =>  listener token
   p_site_token          =>  site token
   p_site_id             =>  site token
   p_ls_login_url        =>  login url of SSO Server
   p_ls_logout_url       =>  Single Sign-Off URL of SSO Server
   p_url_cookie_version  =>  url cookie version
   p_encryption_key      =>  encryption key
   p_ipaddr_check        =>  if IP address should be verified or not
)  

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-6 Parameters for DELETE_ENABLER_CONFIG
Parameter Description

P_LSNR_TOKEN

Listener token to get the necessary partner application registration configuration

Example

WWSEC_SSO_ENABLER.DELETE_ENABLER_CONFIG
(
   p_lsnr_token  =>  listener token
);

ENCRYPT_COOKIE Function

This function returns the encrypted cookie body.

Syntax

FUNCTION ENCRYPT_COOKIE
(
    p_lsnr_token  in  varchar2,
    p_cookie      in  varchar2
 )  return varchar2;
Table 3-7 Parameters for ENCRYPT_COOKIE
Parameter Description

P_LSNR_TOKEN

Listener token to get the necessary partner application registration configuration

Example
WWSEC_SSO_ENABLER.ENCRYPT_COOKIE
(
  p_lsnr_token  =>  listener token
  p_enc_cookie  =>  cookie value to be encrypted
)

DECRYPT_COOKIE Function

This function returns the decrypted cookie value from the encrypted cookie.

Syntax

(
    P_LSNR_TOKEN  IN  VARCHAR2,
    P_ENC_COOKIE  IN  VARCHAR2
 )  RETURN VARCHAR2;
Table 3-8 Parameters for DECRYPT_COOKIE
Parameter Description

P_LSNR_TOKEN

Listener token to get the necessary partner application registration configuration

P_ENC_COOKIE

Cookie value to be encrypted

Example

WWSEC_SSO_ENABLER.DECRYPT_COOKIE
(
   p_lsnr_token  =>  listener token
   p_enc_cookie  =>  cookie value to be encrypted
)

Table Definitions

The Single Sign-On SDK contains two tables for partner applications: SEC_WWSEC_ENABLER_CONFIG_INFO$ and WWSEC_SSO_LOG$. The first stores configuration information that enables the application to determine which Single Sign-On server to connect to. The second stores client-side debug information, which can be accessed when debugging is enabled.

WWSEC_ENABLER_CONFIG_INFO$

CREATE TABLE wwsec_enabler_config_info$
(
  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_SSO_LOG$

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

Exceptions

Table 3-9 lists and describes the exceptions raised by PL/SQL functions and procedures.

Table 3-9 Exceptions
Exception Description

UNKNOWN_ERROR_EXCEPTION

Generic error

CONFIG_MISSING_EXCEPTION

SDK configuration table is unpopulated, or its contents are invalid

DUP_CONFIG_EXCEPTION

Partner configuration with same listener token already exists

ENCRYPTION_FAILED_EXCEPTION

Wrong key or bad input data

DECRYPTION_FAILED_EXCEPTION

Wrong key or bad input data

UNSUPPORTED_VERSION_EXCEPTION

SDK version and Single Sign-On server version are incompatible

IPADDR_ERROR_EXCEPTION

Pre- and post-authentication addresses do not match. User might be accessing applications through a proxy, or there might be a security attack, or user's computer might not use fixed IP addresses

COOKIE_EXPIRED_EXCEPTION

Authentication token sent by Single Sign-On server timed out

NULL_ATTRIBUTE_EXCEPTION

Wrong input data

Java APIs

Java APIs can be used in place of PL/SQL APIs to create partner applications. To learn how to use the Java APIs, see Oracle9iAS Single-On API Reference (Javadoc).


Go to previous page Go to next page
Oracle
Copyright © 2002 Oracle Corporation.

All Rights Reserved.
Go To Documentation Library
Home
Go To Product List
Solution Area
Go To Table Of Contents
Contents
Go To Index
Index