Siebel CRM Desktop for IBM Notes Administration Guide > Customizing Authentication > CRM Desktop SSO Objects You Can Customize >

SSO Client Object

This topic describes functions that you can use with the SSO client object. It includes the following topics:

• Create Request Function
• Create Response Function
• Decode URL Function
• Encode URL Function
• Exception Occurred Function
• Get Platform Cookie Function
• Interactive Function
• Request Handler Function
• Set Platform Cookie Function
• Other Functions That the SSO Client Object Includes

To communicate the credentials that the user enters in the CRM Desktop login dialog box to the SSO script, CRM Desktop SSO uses the get_sso_username and get_sso_password functions of the sso_client object.

The sso_client object is a global object that is available anywhere in the main script file. The following registry key identifies this main script file:

SSO\ScriptFileName

For more information, see Windows Registry Keys You Must Set to Enable CRM Desktop SSO.

Create Request Function

The create_request function creates a request and returns a new request object. It uses the following format:

create_request(url, method, body, encoding)

where:

• url is a string that contains the URL that identifies the request endpoint.
• method is a string that identifies the HTTP request method. It can include one of the following values:
  • GET
  • POST
• body is a string that contains the body of the request.
• encoding is a string that identifies how to encode the request body. It can include one of the following values:
  • iso-8859-1
  • utf-8
  • utf-16

For example, the following code creates a simple GET request to a URL:

var req = sso_client.create_request("http:\\siebel\eai_enu", "GET", "", "utf-8");

For more information, see Request Object.

Create Response Function

The create_response function creates and returns a new response object. It uses the following format:

create_response(http_code, http_status, body, encoding)

where:

• http_code is an integer that identifies an HTTP status code. For example, 200, 500, or 404. For more information, see the topic about status code definitions at the World Wide Web Consortium (W3C) web site.
• Åhttp_status includes a string that identifies an HTTP status message that corresponds to the value that http_code identifies. For example, OK for 200, Not found for 404, and so forth.
• body includes a string that is the response body.
• encoding includes a string that identifies how to encode the response body. It can include one of the following values:
  • Åiso-8859-1
  • Åutf-8
  • Åutf-16

    You must use double quotes to enclose each value. For example:

  var resp_body = "... response body ...";
  var resp = sso_client.create_response(500, "Internal Server Error", resp_body,
  "UTF-8");
    resp.get_headers().add_header("Content-Type", "text/xml; charset=utf-8");
    resp.get_headers().add_header("Content-Length", ""+resp_body.length);

Decode URL Function

The decode_url function decodes a URL. It does the following:

1. Splits a URL into components and then reconstructs this URL. It adds any missing components.
2. Replaces encoded sequences into their corresponding values. The following format identifies a sequence:

   %xx

   where:

   • Å% represents percent encoding that allows you to encode information in a Uniform Resource Identifier (URI).

The decode_url function uses the following format:

decode_url(url)

where:

• url is a string that contains the URL that the decode_url function decodes.

Encode URL Function

The encode_url function encodes a URL. It replaces each nonstandard character with the encoded value. The following format identifies a sequence:

%xx

The encode_url function uses the following format:

encode_url(url)

where:

• url is a string that contains the URL that the encode_url function encodes.

Exception Occurred Function

The cpp_exception_occurred function is a Boolean function that returns True if the last call to an execute_request function resulted in C++ code creating an exception. Any subsequent call to the execte_request function resets a previously recorded exception, so you must use this function immediately after the call to the execute_request function.

Get Platform Cookie Function

The get_platform_cookie function gets the Internet Explorer cookie. It can only get Internet Explorer cookies that are persistent and that are not of type HTTPOnly. It uses the following format:

get_platform_cookie(url, name)

where:

• url is a string that contains the URL that CRM Desktop SSO uses to get the cookie.
• name is a string that contains the name of the cookie.

Interactive Function

The interactive function instructs the SSO script to use interactive authentication. It uses callbacks to monitor the state of the interactive session. CRM Desktop SSO runs the statement that occurs immediately after the statement that calls the interactive function only after the interactive authentication finishes. While interactive authentication runs, the SSO script gets notifications from the function that the callback parameter identifies. This callback delivers the information that this script requires to monitor the interactive authentication. It can send a request to stop the interactive authentication when the interactive session finishes.

The interactive function uses the following format:

interactive(ia_state, callback)

where:

• ia_state is a string that identifies the object that contains information about interactive authentication.
• callback is a string that identifies the function that CRM Desktop SSO calls on every change that occurs in the ia_state.status. This callback must return a Boolean value. If it returns True, then CRM Desktop SSO stops the interactive authentication. ia_state is an object that the sso_client.create_ia_state function creates and then uses to control how interactive authentication runs. The callback is a function that returns one of the following values:
  • true. Interactive authentication finished.
  • false. Interactive authentication has not yet finished.

The following example does a simple callback for interactive authentication. It does not do any processing. It always return false to indicate that CRM Desktop SSO must display the native browser dialog box in every subsequent web page where the user navigates:

function ia_callback(ia_state)
{
  switch (ia_state.status) {
    case "before":
    // before navigate to url
    break;

    case "finished":
    // page download complete
    break;

    case "cancelled":
    // user closed dialog
    break;
}
  return false;
}

This example includes the following code. This code is part of the request handler function:

var ia_state = sso_client.create_ia_state();
ia_state.url = url;
ia_state.dialog.width = 1024;
ia_state.dialog.height = 768;
ia_state.dialog.title = "SSO";
ia_state.dialog.visible = false;
sso_client.interactive (ia_state, ia_callback);

Request Handler Function

CRM Desktop SSO routes each request from the Siebel Connector through the request_handler function. This function handles requests that occur from the Siebel Connector to the Siebel Server. This request_handler function expects a single argument that contains the initial request object from the SSO Connector. It sends a return value to the SSO Connector as if the Siebel Server sent this reply. The Siebel Connector is a proxy that resides between the Siebel Connector and Siebel Web Services. The SSO Agent protects these Web services. This proxy hides the SSO Agent from the Siebel Connector.

The following example includes a CRM Desktop SSO script that passes all requests from the Siebel Connector to the Siebel Server without doing any processing. This example is for illustration purposes only. An actual SSO Connector script includes the process_request function to do processing:

sso_client.request_handler = process_request;
function process_request(request)
{
return sso_client.execute_request(request);
}

The following line from this code defines the entry point where CRM Desktop SSO registers the handler:

sso_client.request_handler = process_request

Set Platform Cookie Function

The set_platform_cookie function sets the Internet Explorer cookie. It can only get Internet Explorer cookies that are persistent and that are not of type HTTPOnly. It uses the following format:

get_platform_cookie(url, name, value)

where:

• url is a string that contains the URL that CRM Desktop SSO uses to set the cookie.
• name is a string that contains the name of the cookie.
• value is a string that contains the data that CRM Desktop SSO associates with the cookie.

For example:

sso_client.set_platform_cookie("http:\\example.com", "Cookie_name", "Cookie_value");

Other Functions That the SSO Client Object Includes

You can use the following functions in the SSO Client object. CRM Desktop supports each of these functions starting with Siebel CRM Desktop version except for the execute_request function. Support for the execute_request function starts with an earlier release:

• create_ia_state. Creates and returns a new ia_state object. CRM Desktop SSO uses this object for initial configuration with interactive authentication to send status information. ia_state is an object, while create_ia_state is a function that creates the ia_state object. For more information, see Interactive State Object.
• execute_request. Runs the request and returns a reply. It accepts a request from the request_handler function or a request that the create_request function creates. It uses the following format:

  execute_request(request_object)

• get_sso_username. Gets the user name that the user provides in noninteractive authentication. CRM Desktop SSO does not use this function for interactive authentication.
• get_sso_password. Gets the password that the user provides in noninteractive authentication. CRM Desktop SSO does not use this function for interactive authentication.
• drop_exception. Drops any exceptions that the connector reports. If the script finishes running after CRM Desktop SSO calls this method, then CRM Desktop SSO does not create an exception.
• raise_not_logged_in_exception. Drops any not_logged_in exceptions that the connector reports and then creates a not_logged_in exception with a description that states it cannot process the login because a problem occurred with the Siebel Server or credentials are not valid. CRM Desktop SSO does not stop the session flow. The SSO script must finish running correctly before the connector creates the exception.
• raise_not_valid_exception. Drops any not_valid exceptions that the connector reports and creates a not_valid exception with a description that states the user password is not valid or is missing. CRM Desktop SSO does not stop the session flow. The SSO script must finish running correctly before the connector creates the exception.
• raise_cancel_exception. Clears any reported exception. It creates the following exception for the SSO Connector:

  cancelled

  CRM Desktop SSO does not stop the session flow. The SSO script must finish running the request_handler after it creates an exception.