A
Single Sign-On Software Development Kit

The single sign-on SDK consists of APIs for PL/SQL and Java. You can use these APIs to create partner applications. Appendix B, "Using the PL/SQL and Java APIs", provides code that shows how the APIs are implemented.

This appendix contains the following topics:

• PL/SQL APIs

• Java APIs

  Note: The SDK has been deprecated. If you have built applications using the release 9.0.2 SDK, Oracle recommends modifying these for mod_osso. Nevertheless, 9.0.2 applications will continue to work in 9.0.4.

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 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 A-1 Parameters for GENERATE_REDIRECT

Parameter	Description
P_LSNR_TOKEN	Listener token that retrieves registration information about the partner application. The listener token is the host name and port used on the URL for the current request. This token is used to select the appropriate configuration entry in the WWSEC_ENABLER_CONFIG_INFO$ table.
P_URL_REQUESTED	URL requested by the client. Must be URL encoded if it contains a URL parameter. For example: http://host:port/jsp/order.jsp?itemid=1234&type= purchase
P_URL_CANCEL	URL that users are directed to if they click Cancel on the login page. Must be URL encoded if it contains a URL parameter. For example: http://host:port/jsp/order.jsp?itemid=1234&type= purchase
P_FORCED_AUTH	Forced authentication flag.
REDIRECTURL	URL to which the partner application must direct the browser. 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 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 A-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 user name.
P_SSO_USER_DN	Authenticated user DN.
P_SSO_USER_GUID	Authenticated user GUID.
P_SUBSCRIBER_NAME	Subscriber name.
P_SUBSCRIBER_DN	Subscriber DN.
P_SUBSCRIBER_GUID	Subscriber GUID.
P_USER_IPADDRESS	IP address of the user's machine.
P_SSO_TIMEREMAINING	Remaining session duration.
P_NLS_LANGUAGE	Language selection of the user.
P_NLS_TERRITORY	Territory selection of the 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 A-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.
P_LS_LOGOUT_URL	Single sign-off URL.
P_URL_COOKIE_VERSION	URL cookie version.
P_ENCRYPTION_KEY	Encryption key.
P_IPADDR_CHECK	Indicates whether the 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 A-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.
P_LS_LOGOUT_URL	Single sign-off URL.
P_URL_COOKIE_VERSION	URL cookie version.
P_ENCRYPTION_KEY	Encryption key.
P_IPADDR_CHECK	Indicates whether the IP address should be verified.

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 A-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.
P_LS_LOGOUT_URL	Single sign-off URL.
P_URL_COOKIE_VERSION	URL cookie version.
P_ENCRYPTION_KEY	Encryption key.
P_IPADDR_CHECK	indicates whether the IP address should be verified.

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

Parameter	Description
P_LSNR_TOKEN	Listener token. Retrieves registration information about the partner application.

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 A-7 Parameters for ENCRYPT_COOKIE

Parameter	Description
P_LSNR_TOKEN	Listener token. Retrieves registration information about the partner application.

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 A-8 Parameters for DECRYPT_COOKIE

Parameter	Description
P_LSNR_TOKEN	Listener token. Retrieves registration information about the partner application.
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: 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 A-9 lists and describes the exceptions raised by PL/SQL functions and procedures.

Table A-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 Oracle Application Server Single Sign-On API Reference.