Establishing and Managing the Web Services Session

This chapter describes the different ways in which Oracle CRM On Demand Web services sessions can be established and maintained. It contains the following topics:

About Establishing and Managing the Web Services Session

A Web services-enabled client (that is, a client written in any language that interacts with the Web services framework), must establish a secure session with Oracle CRM On Demand. After authentication, the client interacts with the published Oracle CRM On Demand Web Services to perform data retrieval, modification, creation, and deletion operations. Oracle CRM On Demand and the client format requests and resulting data as standard XML/SOAP messages.

There are multiple methods by which client applications can establish authenticated sessions with Oracle CRM On Demand. These sessions can be managed either by the client application or by the Oracle CRM On Demand server based on the login mechanism used to establish the session.

Oracle CRM On Demand Stateful and Stateless Request Support

Oracle CRM On Demand offers two different mechanisms to manage the allocation of resources to users who are interacting with Oracle CRM On Demand through Web services:

Stateless requests
Stateful session management

Stateless Web services transactions are those in which the client application does not need to maintain a session identifier (a JSESSIONID value) to perform multiple requests to Oracle CRM On Demand using the same session. Stateless Web services transactions are ideally suited for situations in which an interactive application is used to integrate with Oracle CRM On Demand.

Stateful Web services transactions require the client application to maintain and provide a session identifier (a JSESSIONID value) to perform multiple requests to Oracle CRM On Demand using the same session. Subsequent requests with the session identifier do not require reauthentication.

Using Stateless Web Service Requests

Interactive applications can be developed such that a user's credentials are supplied within a request sent to Oracle CRM On Demand, eliminating the need for an explicit login request. If the request qualifies as a stateless request (see Enabling Support for Stateless Requests), the Oracle CRM On Demand server checks to see whether a session has already been established for that user. If a session is found, it is reused for the new request. If no existing session is found for the user, a new session is established.

There is no logoff operation required for stateless Web service requests. Sessions will eventually be released either due to time-out, or will be reclaimed by session management routines for use by other users.

Enabling Support for Stateless Requests

To establish a session that is managed on the Oracle CRM On Demand server:

A company must have stateless Web services support enabled, see Enabling Stateless Web Services Support.
The WS-I login mechanism must be used with the correct namespace and formats as described by the WS-I basic security profile at
http://www.ws-i.org/Profiles/BasicSecurityProfile-1.0.html#UsernameToken
- The WSSE security namespace (http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd) must be specified in the request.

Requests that meet these criteria qualify as stateless requests.

Oracle CRM On Demand Stateless Authentication Mechanisms

Stateless login is available on all APIs. Stateless Web services requests for the Web Services v1.0, Web Services v2.0, Services, and Data Loader APIs can be authenticated using:

UserName and Password provided in SOAP security header (using WSSE Version 1.0 Namespace)
Oracle CRM On Demand Single Sign On (SSO) Token provided in SOAP security header
SSO with SAML v1.1 or v2.0

For the Administrative Services APIs only, the following login options are supported for stateless Web services requests:

UserName and Password provided in SOAP security header (using WSSE Version 2.0 Namespace)
Oracle CRM On Demand Single Sign On (SSO) Token provided in SOAP security header
SSO with SAML v1.1

Login with UserName and Password in the SOAP Security Header

The ability to supply a user’s credentials is due to support for the UserNameToken profile of the WS-I Basic Security Profile Version 1.0. In this case, the SOAP header contains the element <wsse:UsernameToken>, which has child elements containing a username and password:

<soap:Header>
	<wsse:Security soap:mustUnderstand="1">
		<wsse:UsernameToken>
			<wsse:Username>USERNAME</wsse:Username>
			<wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-
			wss-username-token-profile-1.0#PasswordText">password</wsse:Password>
		</wsse:UsernameToken>
	</wsse:Security>
</soap:Header>

Note: URL encoding of login credentials is not supported when they are provided in the SOAP security header.

For the Administrative Services API, a similar login mechanism is used, but with a WSSE Version 2.0 namespace instead of the WSSE Version 1.0 Namespace.

Login with Oracle CRM On Demand Single Sign-On Token in the SOAP Header

This login mechanism is a type of outbound SSO, see Outbound SSO.

The client application supplies the SSO token in the <wsse:KeyIdentifier> element of the SOAP header:

<soap:Header>
	<wsse:Security>
		<wsse:SecurityTokenReference>
			<wsse:KeyIdentifier ValueType="http://schemas.crmondemand.com/ws/2011/01/
			secext#SSOTokenKeyIdentifier">$6$qx6pJ/czNwO1trwQRazQ26j4osNiQHMoqQSwRfpz/
			6HX2D5cw=;$6$IjwKO/BBoBW5oiuqC7P/TxwOBX1LxVpExR9vp7P5J/
			kixzGFWIjxHyRye7zy9Ld2g2vKp4W4jykxjbgF3KE8CFOGmD5g==</wsse:KeyIdentifier>
		</wsse:SecurityTokenReference>
	</wsse:Security>
</soap:Header>

Note: URL encoding of the SSO token is not supported when provided in the SOAP security header. If the SSO token is URL encoded, it must first be decoded before supplying it in the SOAP security header.

The SOAP request will not be processed if the SSO token expired. It is best practice to validate the SSO token before using it for login, see SSO Token Validation.

SSO with SAML v1.1 or v2.0

This login mechanism is a type of inbound SSO, see Inbound SSO.

For SSO using Security Assertion Markup Language (SAML), Oracle CRM On Demand only supports the SAML Web Browser Profiles - the Browser/Artifact Profile and the Browser/POST Profile using the Proprietary Token method.

Stateless Server Affinity Support

The HTTP response of a Stateless Web Service request includes a cookie, containing a session ID (JSESSIONID). This session ID does not identify a specific user session, but rather is used to identify the server in the Oracle CRM On Demand environment on which the session was initially created. Subsequent requests can be sent to include the session ID value, thus ensuring that the request is routed to the same server as the original request, maintaining server affinity. The actual session, however, cannot be used to process the request unless the session is explicitly kept active, see Maintenance of a Stateless Java Session.

Note: Providing a session ID in subsequent requests is optional, however it is recommended that this value is included as it will increase performance when there are multiple application servers deployed.

Maintenance of a Stateless Java Session

The optional SOAP header parameter <SessionKeepAlive> allows a client to instruct the Oracle CRM On Demand server to keep the Java session open after a stateless request has been processed. By specifying the optional <SessionKeepAlive> parameter with a value of true in the SOAP header of a stateless request, the Java session will not be logged off by Oracle CRM On Demand after the request has been processed, and OM session pooling will continue to be used. In addition, the JSESSIONID value that is returned in the SOAP response can be used to authenticate future requests allowing them to reuse the same Java session, without having to reauthenticate. This is especially useful when SAML assertions are used for authentication, as it eliminates multiple round-trips to the Identity Provider when multiple requests are being processed for the same user.

For stateless requests where the <SessionKeepAlive> parameter is set to false, where it is empty, or where <SessionKeepAlive> is not present, the Java session will be logged off by Oracle CRM On Demand after the request has been processed.

Unlike stateful Web services sessions, there is no logoff command for stateless requests. Java sessions will be logged off by the Oracle CRM On Demand server following a period of inactivity. Any attempt to use a JSESSIONID value for a Java session that has expired, will result in an error being returned to the client for that request. Stateless requests must provide either a valid JSESSIONID value or valid user credentials (SSO token, SAML assertion or UserName and Password) to authenticate. Any request lacking either a valid JSESSIONID value or valid user credentials will be rejected.

Note: A request that contains both a JSESSIONID value as well as user credentials will be reauthenticated.

The following is an example of a SOAP header containing the <SessionKeepAlive> element:

<soap:Header>
	<crmod:SessionKeepAlive xmlns:crmod="urn:crmondemand/ws">true
	</crmod:SessionKeepAlive>
	<wsse:Security>
		<wsse:SecurityTokenReference>
			<wsse:KeyIdentifier ValueType="http://schemas.crmondemand.com/ws/2011/01/
			secext#SSOTokenKeyIdentifier">$6$qx6pJ/rGFlDyJBy91C3Uxifc3oDEg/
			Sshtrsyj2z27RoHmO5M=;$6$jWkqu/
			HvIXoqw2FoHx10GDcYDc5WdZ2UV4v1G06AMEBNbWZv0JZinyJ1C4v7OHJR4OQVhZ4J3X+U/
			EvrP1c82LYHVOHA==</wsse:KeyIdentifier>
		</wsse:SecurityTokenReference>
	</wsse:Security>
</soap:Header>

Using Stateful Web Services Requests

In instances in which the application manages the creation and release of user sessions, the following apply:

Clients must make login and logoff calls in their code to manage the session.
The login step returns an HTTP cookie that contains the session identifier that must be used for making additional requests.
A session remains active until the user explicitly logs out or until the session times out.

Web services session management is HTTP-based and uses a session ID (also known as a JSESSIONID), which is contained in HTTP Session cookies, to uniquely identify a session established with Oracle CRM On Demand.

Oracle CRM On Demand Web Services enable session management by first creating a session using the login call, which is then referenced in any subsequent SOAP operations.

In an Oracle SOAP session, after a session ID has been created in a login request, it can be referenced by including the session ID within the cookie header line. When a session ID is referenced as a cookie, a cookie header line must appear in the request with the name JSESSIONID=. In this case, the session ID appears in uppercase, and the value of the cookie is exactly the same as the session ID received from the login request.

Note: This is the recommended approach to referencing the session ID, for several reasons. The Java servlet specification advises the use of cookies and not the URL wherever possible. Most development environments and programming languages are efficient in using cookies rather than adding arguments to the URL. Furthermore, it is much simpler to implement cookies because the cookie container from the Oracle CRM On Demand login response can be copied onto further requests being sent to Oracle CRM On Demand. Attaching the session ID as a parameter to the URL request line is contrary to security standards and is not good practice.

When a login request is made, the session ID is returned as a cookie in the response to the request. The client is responsible for extracting this session ID and using it throughout the session. If the session times out for any reason, the error returned reports that the session is not valid and the client must then request a new session. In this case, no explicit logoff operation is required.

Once a session ID is retrieved, it is possible to use the session ID to invoke Web services by using HTTP POST; for more information, see Integration Requests for the Web Services Session.

To issue a logoff request to terminate a session, the request must identify the session using the JSESSIONID value.

All requests must use HTTP Secure (HTTPS).

Oracle CRM On Demand Stateful Authentication Mechanisms

Stateful login can be used with the Web Services v1.0, Web Services v2.0, Service, and Data Loader APIs, but is not available for the Administrative Services APIs.

The following login options are supported by Oracle CRM On Demand for stateful requests:

HTTP Login (containing UserName and Password in the HTTP Header)
UserName and Password provided in SOAP security header (using WSSE Draft Namespace)
HTTP Login (with Oracle CRM On Demand Single Sign On (SSO) Token in HTTP Header)
SSO using SAML v1.1

Login Using HTTP GET (Providing UserName and Password in the HTTP Header)

An HTTPS request can be used to instantiate an Oracle CRM On Demand Web services session and obtain a valid session ID. A client invokes login by sending an HTTP GET request to a URL such as the following:

https://secure-ausomx[ENV].crmondemand.com/Services/Integration?command=login

where [ENV] is the three-letter identifier for your company’s environment. If you do not know what this value is for your company, refer to the URL you use to access the Oracle CRM On Demand UI.

Note: The login parameter value is case sensitive.

Login Input

There are different mechanisms for login depending on whether the login header contains URL encoding with the UTF-8 encoding system. This is necessary when login credentials contain multi-byte characters.

The input to login is provided in the URL parameters and the HTTP headers, as follows:

Two URL parameters:
- command, which has the value login
- isEncoded, which is used if the HTTP headers are URL encoded using UTF-8. This parameter must have the value Y or y if encoding is required. The default value is N or n.
Two HTTP headers, UserName and Password, must be set with the appropriate values for your system. For example:
- UserName: johndoe@email.com
- Password: mypass
HTTP headers can be in clear text, or can be URL encoded.

Login Output

The login command returns the following items:

A session cookie, JSESSIONID. The client must use this cookie when submitting subsequent requests, including logoff requests.
A status code of 200, if the session does not encounter any errors. This indicates that the request succeeded.

For code samples for login, see: https://codesamples.samplecode.oracle.com/servlets/Scarab/action/ExecuteQuery?query=crm_on_demand"

Login with UserName and Password in the SOAP Security Header

A similar login mechanism to that for stateless requests is used, but with a WSSE draft namespace (http://schemas.xmlsoap.org/ws/2002/04/secext or http://schemas.xmlsoap.org/ws/2002/07/secext) instead of the WSSE Version 1.0 Namespace. For more information, see Oracle CRM On Demand Stateless Authentication Mechanisms.

The SOAP header contains the element <wsse:UsernameToken>, which has child elements containing a username and password:

<soap:Header>
  <wsse:Security soap:mustUnderstand="1">
    <wsse:UsernameToken>
      <wsse:Username>USERNAME</wsse:Username>
      <wsse:Password Type="wsse:PasswordText">password</wsse:Password>
    </wsse:UsernameToken>
  </wsse:Security>
</soap:Header>

Note: URL encoding of login credentials is not supported when they are provided in the SOAP security header.

Login with Oracle CRM On Demand Single Sign-On (SSO) Token in the HTTP Header

This login mechanism is a type of outbound SSO, see Outbound SSO.

The client instantiates an Oracle CRM On Demand Web services session and obtains a valid session ID by sending an HTTP GET request to the following URL and specifying the SSO token:

https://secure-ausomx[ENV].crmondemand.com/Services/
Integration?command=ssologin&odSsoToken=[SSOTOKEN]

where:

[ENV] is the three-letter identifier for your company's environment. If you do not know what this value is for your company, refer to the URL you use to access the Oracle CRM On Demand UI.

Note: The login parameter value is case sensitive.
[SSOTOKEN] is the SSO token string used to authenticate a user to have access to data within Oracle CRM On Demand.

If the login request is successful, the server returns the session ID in the response.

The session will not be instantiated and the session ID will not be returned if the SSO token has expired. It is best practice to validate the SSO token before using it for login, see SSO Token Validation.

SSO with SAML v1.1

For SSO using Security Assertion Markup Language (SAML), Oracle CRM On Demand only supports the SAML Web Browser Profiles – the Browser/Artifact Profile and the Browser/POST Profile. For information about logging in and retrieving the session ID to be used for stateful requests, see Inbound SSO.

Logout of the Web Services Session

A client logs out by sending an HTTP POST or HTTP GET request to a URL. For example:

https://secure-ausomx[ENV].crmondemand.com/Services/Integration?command=logoff;

Note: The parameter value logoff is case sensitive.

Logoff Input

The preferred method is to include the JSESSIONID with the request as a cookie with the same name. There are no other URL parameters or HTTP headers, and there is no HTTP body.

Logoff Output

A status code of 200 is returned if the request is received by the Oracle CRM On Demand server. This does not guarantee that the logoff request has been processed, and there might be a delay until the session resources are released for use by a new Web services session.

Integration Requests for the Web Services Session

An integration request is an HTTPS request to invoke a Web service to perform data creation, retrieval, update, and deletion operations. An integration request is made by an HTTP POST command to a URL like the following:

https://secure-ausomx[ENV].crmondemand.com/Services/Integration/object

where object is the name of the relevant Oracle CRM On Demand object (record type). This Oracle CRM On Demand object is determined from the contents of the SOAP request.

Integration request input. The JSESSIONID returned to the client during login must be included with the request. The request must contain the JSESSIONID either as a cookie or as a URL parameter, as follows:

https://secure-ausomx[ENV].crmondemand.com/Services/Integration/object; 
jsessionid=xyZ12489w3482413

The Web service input is provided as a SOAP command in the body of the HTTP POST request.

Integration request output. The properties returned by the HTTP server populate the response headers and the response body. The following table shows the top-level properties that specify key properties of the HTTP response.

Table Properties of the HTTP Response

Property	Comments
HttpStatus	Status code returned in the response. If no value is provided, the response is given the value 200 (indicating success).
Content-Type	Content type returned in the response. If no value is provided, the response is given the value text/xml.

Comparison of Stateless Versus Stateful Web Services Transactions

Stateful Web services are generally used when querying a large number of records or performing bulk data operations, for example uploading large volumes of data. Some characteristics of stateful Web services transactions include:

Do not utilize OM session pooling (the client application must manage the session for each request)
Return a valid JSESSIONID value, which is used for authenticating subsequent requests
An OM session is not shared and can store details about previous requests, this is helpful when performing pagination over a query result set. The session will not be used by other applications as the session ID must be explicitly specified in the requests.
The session limit quota controls the number of sessions that can be established for a company.

In general, it is recommended that customers use stateless Web services for several important reasons:

Stateless Web services provide more efficient resource utilization for most uses.
Stateless Web services do not impact the session limit quota.
Since customers are responsible for Web service development, stateless Web services can dramatically reduce complexity and cost of developing new integrations as resource management is performed by Oracle. For stateful Web services, this is the customer's responsibility. For example, customers do not need to code logic to log off following a stateless request/response.
Stateless Web service requests achieve a higher level of concurrency because Oracle CRM On Demand code manages sessions.
Additional error handling logic is also the customer's responsibility and must be implemented correctly with stateful Web services.

Customers must ensure stateless Web services are used for short, interactive requests where high concurrency is required.

Some characteristics of stateless Web services transactions include the following:

Support OM session pooling. Sessions are managed and pooled internally by the Oracle CRM On Demand server.
Perform a logoff (invalidation of the Java session) after processing each request unless the <SessionKeepAlive> parameter is set to true. The client application does not have to manually submit a request to log off a session.
Return a JSESSIONID value to help maintain server affinity (that is, direct subsequent requests to the same Java server), if the <SessionKeepAlive> parameter is set to true in the request.

Stateless Web services transactions must be used for Administrative Services APIs. A full login is performed for each request.

Single Sign-On

The Single Sign-On (SSO) feature of Oracle CRM On Demand allows companies to integrate the hosted Oracle CRM On Demand service with other systems that have the ability to manage user credentials and authentication.

Outbound SSO

The outbound SSO feature allows users who have signed into Oracle CRM On Demand using SSO to pass the SSO credentials from Oracle CRM On Demand to third-party sites such as corporate Web pages or intranets. This allows users to embed or access third-party sites from within Oracle CRM On Demand.

Outbound SSO in Oracle CRM On Demand uses a proprietary method to generate a hashed message authentication code (HMAC) token that is passed to the third-party site. This third-party site makes a request back to Oracle CRM On Demand with the token. Oracle CRM On Demand then validates the token and provides a username back to the third-party site, or authenticates the token and provides a session ID to the user.

For security reasons, the SSO token is only valid for a short period of time and can be used only once. Any subsequent attempts to use the same token for validation or to obtain a session ID will fail.

SSO Token Validation

The following steps are used to validate an SSO token:

The third-party application can pass the SSO token as an URL parameter called "odSsoToken" of the following URL through a POST or GET request:
```
https://server/Services/SSOTokenValidate?odSsoToken = [SSOTOKEN}
```
If successful, the server returns the username in the HTTP body.

The server returns errors if the SSO token has expired or is missing from the request.

Inbound SSO

Inbound SSO allows a company that has its own internal authentication system to validate a user and then seamlessly allow the user to log in to Oracle CRM On Demand.

The company must be set up to use SSO for Oracle CRM On Demand:

The company and optionally the user must be configured for SSO.
External Identifier for SSO must be specified.
ITS URL for SSO must be specified.

If your company has been set up to use SSO for Oracle CRM On Demand, the following steps are used to initiate a Web service request to Oracle CRM On Demand using SSO:

The Web service client makes a request with the following command specifying the SSO Company Identifier.

https://secure-ausomx[POD].crmondemand.com/Services/
Integration?command=ssoitsurl&ssoid=<SSO_Company_Identifier>

The server returns the SSO ITS URL in the "X-SsoItsUrl" HTTP header of the response.
The Web service makes a request with the ITS URL.

The identity provider might respond to requests with a prompt for authentication credentials, for example, username and password. The client application must be able to recognize this request and respond appropriately.

Note: The behavior of the identity provider is beyond the control of Oracle CRM On Demand.

Any client using Inbound SSO must be able to perform the following actions:

Follow redirects
Accept cookies

Customers are responsible for ensuring that their client applications are compatible with their chosen identity provider.

For code samples for single sign-on see: https://codesamples.samplecode.oracle.com/servlets/Scarab/action/ExecuteQuery?query=crm_on_demand