Oracle Single Sign-On Application Developer's Guide Release 3.0.6 Part Number A86782-03 |
| Library | Service | Index

# 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

- Exceptions

- Datatype and Table Definitions

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

- Functions and Procedures

### 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 the illustration ssign006.gif

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

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

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

4. If the login cookie is not present, then the Login Server calls the `SHOW_LOGIN_SCREEN` procedure.

5. The Login Server presents a login page to the user, prompting the user for a user name and password.

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

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

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

- GENERATE_REDIRECT Function (URL Cookie Version V1.0)

- PARSE_URL_COOKIE Function (URL Cookie Version V1.0)

- GET_ENABLER_CONFIG Function

- CREATE_ENABLER_CONFIG Procedure

- UPDATE_ENABLER_CONFIG Procedure

- DELETE_ENABLER_CONFIG Procedure

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

##### 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
     );

| Copyright © 1996-2000 Oracle Corporation. All Rights Reserved. |
| Library | Service | Index