Oracle Web Services On Demand Guide > Establishing and Managing the Web Services Session > Using Stateful Web Services Requests >

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

    HTPP 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 Login with UserName and Password in the SOAP Security Header.

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