Recipes by Category

App Distribution (2) Bundle logic, interface and services for distribution. App Logic (37) The Apex programming language, workflow and formulas for logic. Collaboration (6) The Salesforce Chatter collaboration platform. Database (29) Data persistence, reporting and analytics. Integration (33) Web Service APIs and toolkits for integration. Security (9) Platform, application and data security. Tools (4) Force.com tooling User Interface (36) Visualforce MVC and metadata-drive user interfaces. Web Sites (12) Public web sites and apps with optional user registration and login.
Beta Feedback
Cookbook Home » Implementing Single Sign-On for Clients

Implementing Single Sign-On for Clients

Post by Developer Force  (2010-07-16)

Status: Certified
Level: novice

Problem

You want to use single sign-on with a desktop client, such as Connect for Outlook, Connect for Lotus Notes, orConnect for Office, so that your users only have to log into an environment once—instead of having to login more than once to access different services and resources in an environment.
This recipe assumes that you are familiar with enabling single sign-on Enabling Single Sign-On with the Force.com Platform.

Solution

There are three main approaches for using single sign-on to authenticate Force.com clients:
  • Use the network password, such as an LDAP password for authentication using the clients. End users would enter their Salesforce.com usernames and LDAP password into the login dialog box, and delegated authentication would be performed.
    Force.com never logs the LDAP password, and clears it out of memory as soon as it has passed on in the SOAP message to the single sign-on service.
  • Use a client application registry setting that can designate where Force.com directs the login request. By making this URL an internal URL, a customer can provide a proxy for the username and password, verify it locally, then pass a one-time use token (such as a SAML token) to Force.com for verification. This is then passed back to the customer for validation.
  • Use a customer-built proxy that requires NT Lan Manager (NTLM) authentication. Once NTLM has passed, the proxy can send the Salesforce.com username and a one-time use token to Force.com, which gets passed back to the customer for validation. This approach has the benefit of not having to configure a username and password for all clients that are deployed. Only the registry setting needs to be changed.
You do not need to implement a proxy service to make client applications work if your single sign-on listener supports tokens and passwords. Users can configure their passwords in the client application. In this case, the network password temporarily passes through the Force.com servers. This password is not logged anywhere, and is cleared out of memory as soon as the outbound SOAP message has been sent.

Discussion

The single sign-on login process for Force.com desktop clients involves the following components:
  • SOAP message packages
  • Local Microsoft® Windows registry key HKEY_LOCAL_MACHINE\SOFTWARE\salesforce.com\OfficeToolkit\ServerUrl
  • Desktop client proxy (specified in the registry key)
  • Token generator
  • Single use tokens
  • Token authentication proxy
Single Sign-On Login Process from a Client
  1. The desktop client sends a login request to the desktop client proxy as a SOAP message package.
  2. The desktop client proxy extracts the username and password and sends them to the token generator.
  3. The token generator validates the credentials and replies to the desktop client proxy with a single-use token.
  4. The desktop client proxy modifies the SOAP message package by replacing the corporate password in the login request with the token and sends a secure login call to Force.com at https://www.salesforce.com/services/Soap/c/API_version_number.

    Different clients require different API version numbers. For example, Connect for Outlook and Connect for Lotus Notes require version 10.0, Connect for Office requires version 2.5, and Connect Offline requires version 13.0.

  5. Force.com sends a request to the authentication proxy to validate the token.
  6. The authentication proxy replies to Force.com.
  7. Force.com replies to the desktop client proxy.
  8. The desktop client proxy passes the response back to the desktop client, authenticating the user.
This process occurs only if the registry key has a value.

When the desktop client proxy is not exposed to the public Internet, only users inside the network or with VPN access have the ability to use authenticate to Force.com using the client applications.

Sample Messages

The following is an example of a HTML/SOAP login message. As summarized in the first step above, login messages such as the following sample are sent to the desktop client proxy specified in the ServerUrl registry key.
<soapenv:Envelope 
   xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
   xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
   xmlns:sfdc="urn:enterprise.soap.sforce.com" 
   xmlns:sf="urn:sobject.enterprise.soap.sforce.com">
   <soapenv:Header>
      <sfdc:CallOptions>
         <sfdc:client>Outlook/33101</sfdc:client>
         <sfdc:remoteApplication>outlook</sfdc:remoteApplication>
      </sfdc:CallOptions>
      <sfdc:QueryOptions>
         <sfdc:batchSize>100</sfdc:batchSize>
      </sfdc:QueryOptions>
   </soapenv:Header>
   <soapenv:Body>
      <sfdc:login>
         <sfdc:username xsi:type="xsd:string">b.lake@salesforce.com
         </sfdc:username>
         <sfdc:password xsi:type="xsd:string">proxy1234
         </sfdc:password>
      </sfdc:login>
   </soapenv:Body>
</soapenv:Envelope>
The following is an example of a SOAP response message. As summarized in the last step above, responses from Force.com such as the following sample are passed by the desktop client proxy to the desktop client.
<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope 
   xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
   xmlns="urn:enterprise.soap.sforce.com" 
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <soapenv:Body>
   <loginResponse>
   <result>
   <metadataServerUrl>https://na1-api.salesforce.com/services/Soap
       /m/10.0/00D30000000Kc5B</metadataServerUrl>
   <passwordExpired>false</passwordExpired>
   <serverUrl>https://na1-api.salesforce.com/services/Soap
       /c/10.0/00D30000000Kc5B</serverUrl>
   <sessionId>00D30000000Kc5B!ARkAQPsowlYLaw8G_Y1AgnUG9mZ3Z1mSi
       NCKislQ69ltrluugmUqstbFdLUCddq2PFTFZRxsXRXx0aBS82XJME6x
       MP_4Xut6</sessionId>
   <userId>00530000001Yx3rAAC</userId>
   <userInfo><accessibilityMode>false</accessibilityMode>
         <currencySymbol>$</currencySymbol>
         <organizationId>00D30000000Kc5BERS</organizationId>
         <organizationMultiCurrency>false
            </organizationMultiCurrency>
         <organizationName>San Francisco Coffee Supply
            </organizationName>
         <profileId>00e30000000w2Z8AAI</profileId>
         <roleId xsi:nil="true"/>
         <userDefaultCurrencyIsoCode xsi:nil="true"/>
         <userEmail>bjmark@salesforce.com</userEmail>
         <userFullName>Blake J Mark</userFullName>
         <userId>00530000001Yx3rAAC</userId>
         <userLanguage>en_US</userLanguage>
         <userLocale>en_US</userLocale>
         <userName>blake@desktopclientsdemo.com</userName>
         <userTimeZone>America/Los_Angeles</userTimeZone>
         <userType>Standard</userType>
         <userUiSkin>Theme2</userUiSkin>
   </userInfo>
   </result>
   </loginResponse>
   </soapenv:Body>
</soapenv:Envelope>

Share

Recipe Activity - Please Log in to write a comment

This article does not details out integration with Salesforce for Outlook using SAML.  Thanks.

by Hari Sharma  (2011-06-22)

X

Vote to Verify a Recipe

Verifying a recipe is a way to give feedback to others and broaden your own understanding of the capabilities on Force.com. When you verify a recipe, please make sure the code runs, and the functionality solves the articulated problem as expected.

Please make sure:
  • All the necessary pieces are mentioned
  • You have tested the recipe in practice
  • Have sent any suggestions for improvements to the author

Please Log in to verify a recipe

You have voted to verify this recipe.