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

• PL/SQL APIs

• Java APIs

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 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

• Table Definitions

• Exceptions

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

• PARSE_URL_COOKIE Procedure

• GET_ENABLER_CONFIG Procedure

• CREATE_ENABLER_CONFIG Procedure

• MODIFY_ENABLER_CONFIG Procedure

• DELETE_ENABLER_CONFIG Procedure

• ENCRYPT_COOKIE Function

• DECRYPT_COOKIE Function

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).