CRM On Demand

Oracle CRM On Demand Integration Guide

SSO Token and Session Management December 2010

SSO Token and Session Management

Table of Contents
USE CASE PROFILE.............................................................................................................................4 OPTION 1: STATELESS WEB SERVICES ..........................................................................................5 OPTION 2: FIXED CREDENTIALS WITH CLIENT SIDE SESSION MANAGEMENT & SESSION POOLING ...............................................................................................................................................5 OPTION 3: PROMPT FOR USERNAME AND PASSWORD ................................................................6 PARTNER EXAMPLE: RELEASE IDLE SESSIONS (RESOLUTION) .................................................7 CONCLUSION........................................................................................................................................9 SOLUTION SET FAQ...........................................................................................................................10 GLOSSARY..........................................................................................................................................11

SSO Token and Session Management

Use Case Profile What is an SSO Token

An SSO Token is a secure mechanism to authenticate to CRM On Demand Stateful Web Services. When assigned as part of a Web Link, Web Applet or Web Tab, the SSO Token user field is substituted with an autogenerated random value for the token. This secure token can subsequently be used to authenticate into CRM On Demand and obtain a secure Web Services session. The SSO Token is widely used by third-party partner integrations to securely login to CRM On Demand Web Services, as it unique and cannot be recreated.

What is SSO Token Timeout

The SSO Token is valid for a set time period in order to secure the authentication process and to prevent hackers from obtaining the token. The token is valid for five (5) minutes. After this time period, once the Web Services session has expired, a new token will need to be obtained in order to access Web Services.

Partner Integration using SSO Token: Use Case

Many partner integrations requiring access to CRM On Demand data use the SSO Token as a secure way to login and access the CRM On Demand Web Services API. A sample use case is listed below: In this example, end users launch a flash application in a CRM On Demand iframe to work with and augment CRM On Demand data. The flash application is hosted on the partners server. Users navigate through the pages of the flash application and retrieve and edit CRM On Demand data. After the user makes the necessary changes, the user clicks submit and data is updated within CRM On Demand. This integration uses SSO to authenticate and Web Services to retrieve and update data. The partner integration is designed such that it can be used concurrently by multiple end users

Partner Integration using SSO Token: Problem Statement

The key challenge of this integration pattern is to provide a high number of concurrent authenticated users accessing data from CRM On Demand. Each user launches a Web Services session and retrieves data, makes the necessary changes and updates the data back to CRM On Demand. As designed, the partner application requires approximately 60-80 concurrent users to login to Web Services and access CRM data to support roughly 600 users on a daily basis. CRM On Demand limits the number of concurrent sessions that can be opened at any given time in order to protect shared server resources. The number of concurrent sessions required by the partner integration exceeds the concurrent session limit and users are prevented from logging into the Web Services API. As such, the partner application will require design considerations to accommodate for the anticipated daily usage. Listed below are options to address the SSO Token Timeout and Concurrent Sessions issues:

SSO Token and Session Management

Option 1: Stateless Web Services

Stateless Web Services are atomic transactions that do not require the partner application to maintain a unique identifier across multiple requests. Stateless transactions use server resources more efficiently and reduce the cost of implementation as partners and customers do not need to implement session pooling or be concerned about session management. In Stateless Web Services, session management is leveraged by the server and is abstracted from the client. The Stateless approach can be considered for an interactive scenario as the user's credentials are supplied with each Web Service request eliminating the need for the login request to establish an explicit session. This way, the issue of opening multiple concurrent sessions and reaching the concurrent session limit can be eliminated.

Advantages:
With the Stateless approach, there is no limit on concurrent sessions. The partner application does not need to implement session management and explicitly manage the number of concurrent sessions.

Disadvantages:
Stateless Web Services require the user's credentials to be passed with each Web Service request. While planned, there is currently no support for SSO authentication using the Stateless Web Services in CRM On Demand. The user's credentials need to be provided for each Web Service call. This can pose a security risk as the userID and password information can be exchanged as plain text via the internet in any case where the user is requested to provide credentials while navigating the partner application.

Example:
A customer requires an interactive sales application to update data in CRM On Demand that can be used concurrently by approximately 600 sales users. The Sales user will update Opportunities in CRM On Demand with data being sourced exclusively from a third-party real-time sales data analysis system. Users will login to CRM On Demand by providing username and password credentials and update Opportunity information using stateless Web Services. A Stateless Web Service client is required to access and update opportunities as data is being drawn real time from a third party sales analysis application. . This customers use case can be met using the Stateless approach where multiple users can login concurrently using Stateless Web Services. As there are no restrictions on concurrent sessions, large numbers of users can be logged in simultaneously.

Option 2: Fixed Credentials with Client Side Session Management & Session Pooling
Session pooling is an option for increasing the performance of the application and managing concurrent sessions using fixed credentials. Session pooling involves maintaining a list of active sessions in the partner application. The partner application must ensure that each session is active and valid (it must have a valid sessionID) before using it in a request. The application might determine whether the session is active based on the success of the login operation and the time that has passed since the session was used. If all active sessions are in use for pending Web Service requests a new session can be added to the pool. However the pool can only hold a certain number of concurrent sessions and the number of sessions should be less or equal to the CRM On Demand concurrent session limiter. If all sessions in the pool are currently being used, new requests for sessions will need to wait until a session becomes available.

Advantage:
Session pooling manages the number of concurrent sessions available ensuring that the number of sessions is equal to or below the limit. Session pooling can improve performance in both a single-threaded or multithreaded application. In a single-threaded application, session pooling can avoid the unnecessary overhead of SSO Token and Session Management

re-logging into the application for each request. In a multi-threaded application session, you can use session pooling to run multiple requests at the same time. This option should be considered for a batch scenario (initial data loads, recurring data loads, mass updates etc) where optimal performance can be achieved by using a pool of Web Service sessions to load large data volumes into CRM On Demand.

Disadvantages:
Session pooling is implemented by the partner application and uses single or few fixed (hardcoded) credentials to create a session pool. Each user will have the same access levels as that of the fixed users credentials used to create the session pool. This can be a disadvantage especially for interactive applications as there is no audit trail and all changes are made by a single users credentials and access levels. Session pooling is limited by the number of concurrent sessions and the pool is limited by the CRM On Demand concurrent session limiter. Session pooling has to be implemented on the client side and the client application needs to manage the sessions ensuring that the concurrent sessions do not exceed the limit. This can be somewhat complex to implement and manage by the third-party partner application.

Example:
A customer in the healthcare industry would like to synchronize provider information from various third-party systems to CRM On Demand. The provider record maps to multiple records in CRM On Demand like Accounts, Leads, Contacts and Opportunities. Data synchronization involves managing dependencies and updating the various records. The use case can be met using a single users credential (for example, Administrator) and implementing a session pool on the client side in order to obtain optimal performance.

Option 3: Prompt for Username and Password

As the user navigates the partner application screens, each time a new session is required, a prompt for or lookup of the username and password could be used to create a new session. This approach enables session management by easily creating new sessions and releasing sessions as soon as the necessary Web Service calls are made. This eliminates the need to hold on to Web Service session when the user is working on tasks that do not require Web Service access. This reduces the number of open sessions at any given time and generally keeps the number of concurrent sessions below the limit. As an alternative to prompting for the username and password, the partner application could store all usernames and passwords. However, additional work would need to be done by the partner application to look up the appropriate credentials as well as keep the data store secure and up-to-date.

Advantages:
This option reduces the number of open sessions as a Web Service session will be created only when Web Service access (i.e. retrieving, creating, updating or deleting records) to CRM On Demand is required.

Disadvantages:
Users may need to provide a password each time they navigate to the partner application screens to retrieve or update data. This creates a significant usability issue, as logging in repetitively will be seen as inconvenient and cumbersome to the end user. The retrieval of passwords, while more palatable to end users, could pose a security risk if passwords are cached on the end users machine.

SSO Token and Session Management

Option 4: Release Idle Sessions (Resolution)

In the following example, Web Services sessions are used only when needed. A user navigates to a screen and queries data from CRM On Demand using Web Services. Once data is retrieved, the session can be released in order to minimize the number of concurrent sessions. Once the user has completed editing the data, a new SSO Token can be requested and a net new session can be established in order to update data back into CRM On Demand. Overall, this will minimize number of concurrent sessions and use sessions only when required.

CRM ON DEMAND UI
1

Client Flash Application

(Data Retrieval/ View)
3

Client Flash Application Invocation Point

4 5

Get SSO Token Login to Web Services Get Session Edit CRM On Demand data Release session after data retrieval

CRM ON DEMAND UI

6 7 8 9
10

Client Flash Application

(Data Update) Programmatically obtain SSO Token CRM On Demand provides SSO Token Login to Web Services Get new session Update data to CRM On Demand Release session after data retrieval

Diagram 1: Illustration of Partner Integration and interactions with CRM On Demand Data Retrieval/ View 1) User clicks link in CRM On Demand UI to launch Client Flash Application 2) CRM On Demand passes SSO Token to Client Flash Application 3) Client Flash Application logs into Web Services to acquire a Web Services Session 4) CRM On Demand provides a Web Services Session 5) Client Flash Application interacts with CRM On Demand using Web Services Session ID Data Update 6) Client Flash Application programmatically obtains SSO Token 7) CRM On Demand passes SSO Token to Client Flash Application 8) Client Flash Application logs into Web Services 9) CRM On Demand provides a Web Services Session 10) Data is updated/ modified or deleted in CRM On Demand

NOTE: When programmatically obtaining a new SSO Token, cross-browser restrictions may be encountered as a new session is required before the user can access Web Services (as a third partner server is involved in making the call). This will be encountered only when the SSO Token needs to be retrieved programmatically. A new SSO SSO Token and Session Management

Token can be retrieved programmatically by invoking the Web Link or Web Applet from the client Web page and parsing the contents of the SSO Token user field to obtain a new valid token. However, calling the initial CRM On Demand Web Link or Web Applet leads to cross-browser restrictions since the call is made from a third-party server to CRM On Demand. This issue is not encountered in the previous options. In the Stateless option, the users credentials need to be supplied to invoke a Stateless transaction. The users credentials can be predetermined or can be obtained by prompting the user. In the Fixed Credentials and Session Pooling option, the credentials are predetermined and leveraged programmatically to create a session. In the Prompt for Username, Password option, the users credentials are obtained by prompting for user input and a new session is created. Outlined below is detailed information regarding the workaround for cross-browser restrictions.

Workaround for Cross-browser Restrictions

Listed below are recommendations for designing a browser-based integration using SSO Tokens. 1. Create a new Web Link field in Opportunity Detail page 2. Set up a test Web Link to Open in New window with a URL https://yourserver/getSSO.asp?UID=%%%User id%%%&Token=%%%SSO Token%%% It is very important that the location of this page is on the same server as the partner application otherwise cross-domain security settings in different browsers will stop the technique from working. 3. Place the Web Link on your current CRM On Demand Opportunity Page Layout 4. Open an Opportunity, confirm the new Web Link appears, then select View Source from the browser window 5. Locate the definition of the above Web Link. For e.g. <a target="_blank" href="https://secureausomxapa.crmondemand.com/OnDemand/SSOWebLink?WebLink.Object=Opportunity&#38;WebLink.Ctrl =WEBLINK_006">TEST</a> 6. The important piece to notice is the complete URL within the href attribute as this will be used later. 7. Remove or hide the Web Link from the page layout. 8. Create a web page in the server language of your choice. All it needs to do is accept the token parameter and echo it back to the browser enclosed within some SSO tags 9. Within your application code include a hidden iframe which makes a reference to the URL discovered in step 5 above. Include some JavaScript that will automatically refresh the contents of the iframe after a fixed number of seconds. The interval should be less than the time period for expiry of the SSO Token (5 minutes). In the enclosed example this has been set to 100 seconds which is specific to the partners use case. However the time period can be set to accommodate the specific requirements of the partner application, and ideally be closer to the 5 minute expiration time. Create another JavaScript function to read the contents of the iframe and search for the SSO tags returning the contents. This will be a valid SSO Token that will never be more than 100 seconds old. 10. In order to obtain a new CRM On Demand Web Service session, pass the contents of the above function to the CRM On Demand Outbound SSO API to obtain a new Web Service session.

SSO Token and Session Management

HTML page called by Web Link

Client Server
HTML Page accepts the Token parameter from the Web Link and echoes it back to the browser enclosed within SSO tags

Client Application
Hidden iframe References the CRM On Demand Web Link URL

JS Func: Refreshes Iframe every 100 secs

JS Func: Reads Iframe contents and returns SSO Token

Application: Consumes SSO Token Generates WS session

Diagram: 2 Illustration of Integration Pattern using SSO Token for Web Services Authentication

Conclusion
The partner use case was solved by designing a client integration that released sessions as soon as they were used and created a new session for each Web Service transaction. A new SSO Token was obtained prior to creating a new session. This helped to manage the number of concurrent sessions and also ensured that a valid SSO Token was available each time a new session was required. The partner integration programmatically invoked the CRM On Demand Web Link URL and a new SSO Token was obtained. Cross-browser issues were encountered and a programmatic workaround was used to counter the cross-browser restrictions.

SSO Token and Session Management

Solution Set FAQ

Why does the solution require the usage of two JavaScript functions (i.e. one to refresh the iframe and the other to retrieve the contents)? Can a single function be used to refresh the iframe and captures the SSO Token? Though it appears to be more efficient to combine the iframe refresh with the call to retrieve the contents in certain browsers it just does not work, particularly in IE8. The way in which events are triggered means that the old version of the iframe contents will always be returned in the function which is then refreshed, resulting in a response containing the outdated SSO Token. Splitting the logic into (2) two JavaScript functions, one to periodically refresh the iframe and another to retrieve the contents of the iframe, appears to return a token which is at the most 100 seconds old and well within the timeline for a valid SSO Token.

Would it be more effective to invoke a JavaScript function to refresh the iframe each time you need a new SSO Token and pass it to the application that requires a new SSO Token? The design originally did try to refresh the iframe only when a new SSO Token was needed but this does not work due to the nature of JavaScript events, particularly in IE8. If you try to do this by combining the refresh with the content retrieval you will find that the request to refresh the iframe is not completed until after the end of the function and so you will only get the previous value of the SSO Token which could have expired. Adding a call back to a server to wait for a length of time to allow the iframe to refresh did not work either, as in IE8, the refresh will also wait and not occur until after you have read the contents. The resolution was to have the two JavaScript functions with the refresh being automatically run every x seconds. This is not an optimal solution, however due to browser restrictions this is a workaround.

Would you clarify the reasoning behind refreshing the iframe every x seconds (i.e. 100 sec)? In this specific case 100 seconds was chosen to ensure that an SSO Token is never going to be out of date, however this time interval could be increased to a value nearer to the SSO Token expiry time of 5 minutes. NOTE: The client integration uses a time interval of 100 seconds to specifically meet their use case. However, it is recommended that the time interval be set to a number closer to the 5 minute expiry time period in order to minimize the frequency of calls involved to obtain a new token.

SSO Token and Session Management

10

Glossary
Client Integration: External application that integrates data and/or business processes between CRM On Demand and Customer

Cross-browser Restrictions: Security restrictions preventing an application from invoking an external Web Service

Concurrent session: Multiple sessions that are open at the same time by the same user

Concurrent session limiter: CRM On Demand limit on the number of open concurrent sessions by company.

JavaScript: Client-side scripting language used in html pages

Session Management: Specific to Stateful Web Services. Management of open sessions such that they are maintained below the acceptable limit and are kept active. Session Pooling: A pool of active sessions maintained by the client application. Specific to Stateful Web Services.

SSO Token: Unique identifier used for authenticating to CRM On Demand using a Single Sign On mechanism.

SSO Token Timeout: The SSO Token is valid for a set time period in order to secure the authentication process and to prevent hackers from obtaining the token. The token is valid for five (5) minutes. After this time period, once the Web Services session has expired, a new token will need to be obtained in order to access Web Services.

Stateful Web Service Session Timeout: Period of time after which a session is invalid. Set to 10 minutes in CRM On Demand.

Stateless Web Services: Web Services transactions in which the client application does not need to maintain a session identifier (a JSESSIONID value) to perform multiple requests to CRM On Demand. Each request is performed and authenticated independently.

Stateful Web Services: Web Services transactions in which the client application needs to maintain a session identifier (a JSESSIONID value) to perform multiple requests to CRM On Demand.

Web Services Session: Unique Identifier required in order to generate multiple requests to CRM On Demand using Stateful Web Services

SSO Token and Session Management

11