Single Sign-On for Salesforce Clients
Single Sign-On allows a user to log into an environment once, without having to login to access different services and resources in that environment. This document describes how token-based SSO can be accomplished with Salesforce desktop clients such as Outlook Edition, Lotus Notes Edition, and Office Edition.
Before using the information in this document to implement client-based Single Sign-On, you should be familiar with how to configure the Salesforce environment for Single Sign-On, as described in this How to Implementing Single Sign On with Force.com document.
Once you have read that document, this document will walk you through how to proxy requests from Force.com Windows-based client applications so that end users can either use their network passwords, or avoid passwords entirely with the client applications.
Overview
There are three main approaches to using Single Sign-On for authentication of Force.com clients.
1. Use the network password, such as the LDAP password for authentication using the clients. End users would enter their salesforce usernames and LDAP password into the login dialog box, and delegated authentication would be performed.
2. Some customers have concerns about the LDAP password being passed through Force.com. Force.com never logs this password, and clears it out of memory as soon as it has passed on in the SOAP message to the Single Sign-On service. Client applications have a registry setting that can designate where Force.com directs the login request. By making this URL an internal URL, a customer can proxy the username and password, verify it locally, and 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. Additional details are provided below.
3. This is a slight twist on the option above, except that the proxy the customer builds requires NTLM authentication. Once NTLM has passed, the proxy can send the Salesforce 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/password for all clients that are deployed. Only the registry setting needs to be changed.
Components
The SSO login process for Force.com desktop clients involves the following
components:
→SOAP message packages
→Local Microsoft Windows registry key (see sidebar). HKEY_LOCAL_MACHINE\SOFTWARE\salesforce.com\OfficeToolkit\ServerUrl
→Desktop client proxy (specified in the registry key)
→Token generator
→Single use tokens
→Token authentication proxy
SSO Login Process
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.
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 will have the ability to use authenticate to Force.com using the client applications.
Sample HTML/SOAP Login Message
As summarized in Step 1 above, login messages such as the following sample are sent to the desktop client proxy specified in the ServerUrl registry key.
POST /services/Soap/c/6.0 HTTP/1.1 Connection: timeout=1 SOAPAction: "" Accept-Encoding: gzip Content-Length: 662 User-Agent: SForceOfficeToolkit (MSIE 6.0.2800.1106; Windows NT 5.1 build 2600) Host: www.salesforce.com Cache-Control: no-cache Cookie: noAds=true <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>Offline Client/200</sfdc:client> </sfdc:CallOptions> <sfdc:QueryOptions> <sfdc:batchSize>100</sfdc:batchSize> </sfdc:QueryOptions> </soapenv:Header> <soapenv:Body> <sfdc:login> <sfdc:username xsi:type="xsd:string">growe@genwatt.com </sfdc:username> <sfdc:password xsi:type="xsd:string">21plus21 </sfdc:password> </sfdc:login> </soapenv:Body></soapenv:Envelope
Sample SOAP Response Message
As summarized in Step 8 above, responses from Force.com such as the following sample are passed by the desktop client proxy to the desktop client.
HTTP/1.1 200 OK Server: Resin/3.0.12 Connection: close Content-Type: text/xml; charset=utf-8 Connection: close Transfer-Encoding: chunked Date: Mon, 22 Aug 2005 13:39:15 GMT 04d5 <?xml version="1.0" encoding="UTF-8"?> <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"> <soapenv:Body> <loginResponse xmlns="urn:enterprise.soap.sforce.com"> <result> <passwordExpired>false</passwordExpired> <serverUrl>https://na1-api.salesforce.com/services/Soap/c/6.0</serverUrl> <sessionId>Gl8hFOI_DK8AuC97Y0ZceNvGRkZiefLO6B0fcPR95nefYenQnz5J1aNSjp2dji R27AOU9cRcRyWUsNjBux8nJhhD2wYHcrlK4SNdGN37zi4=</sessionId> <userId>00530000000cczLAAQ</userId> <userInfo> <currencySymbol xsi:nil="true"/> <organizationId>00D300000000JvcEAE</organizationId> <organizationMultiCurrency>true</organizationMultiCurrency> <organizationName>TF & S</organizationName> <userDefaultCurrencyIsoCode>USD</userDefaultCurrencyIsoCode> <userEmail>growe@salesforce.com</userEmail> <userFullName>Graham Rowe</userFullName> <userId>00530000000cczLAAQ</userId> <userLanguage>en_US</userLanguage> <userLocale>en_GB</userLocale> <userTimeZone>Europe/London</userTimeZone> </userInfo> </result> </loginResponse> </soapenv:Body> </soapenv:Envelope>
Frequently Asked Questions
Do I need to implement a proxy service to get the client applications to work?
- No. If your Single Sign On listener supports tokens and passwords, users can configure their passwords in the client application. Note that in this case, the network password will temporarily pass through the Force.com servers. This password is not logged anywhere, and cleared out of memory as soon as the outbound soap message has been sent.