As resources move to the cloud, users are experiencing a proliferation of accounts and their corresponding credentials. In turn, the organizations they act on-behalf of are increasingly challenged with the maintenance and security of those accounts. Single sign-on technologies can come to the rescue, allowing users to authenticate at a single location, with a single account, and access a broad range of services. This provides a seamless experience for the end-user, and critical visibility and control for their organizations.
At the same time, the types of devices and applications used to access cloud-based services are changing. Highly capable mobile devices, tablets, and dedicated desktop applications are providing un-precedented mobility and functionality. Historically, this has been a challenging environment when combined with Single sign-on, as many of the standard technologies in-use are designed explicitly for web browsers. This creates an awkward impedance for the deployed; on one hand they require the usability and control of single-sign on, and the other, the usability and ubiquity of mobile and desktop apps.
With this in mind, Salesforce.com has embarked on a strategy of adapting the single sign-on flow traditionally used for web browsers, and applying it to desktop and mobile apps. Starting with a goal of having one single sign-on integration be applicable across all access mechanisms, a variety of server and client enhancements have been exposed to applications developers and deployers. It is now possible to configure a seamless, standards based single sign-on experience that works for both web browsers as well as a variety of desktop and mobile applications.
Since its release in 2005, the Security Assertion Markup Language (better known as SAML) version 2.0 has established itself as the dominant standard for cross-domain web single sign-on in the enterprise space. This standards based approach provides interoperable integration between Salesforce.com and a wide variety of software platforms. However, its use has traditionally been constrained to web browsers.
OAuth 2.0 is a open authorization protocol that provides an framework useful for connecting applications to user's accounts. It provides a variety of benefits including developer simplicity, improved security by not exposing user credentials un-necessarily, and an improved user-experience as actions like a password reset no longer disrupt their applications. OAuth is in the process of being standardized in the IETF, and is a critical component of Salesforce.com strategy for application developers.
The combination of these two protocols is how Salesforce.com is enabling single sign-on for desktop and mobile applications. By using OAuth to enable users to connect applications to their accounts, and leveraging SAML for the authentication of that connection, the single sign-on integration that was once only applicable for the web-browser can now service a wide variety of user applications.
This is based on the core tenants:
Since this approach is based upon the layering of two complimentary protocols, it's best to first take a look at these independently.
An Overview of SAML
SAML 2.0 defines several roles for parties involved in single sign-on. The user authenticates (logs in) to the identity provider (or IdP) which is hosted by the customer or on their behalf. The user is then able to access a resource at one or more service providers such as salesforce.com (abbreviated as SP, and also known as relying parties) without needing to log in at each service provider. The diagram below shows the process for what is known as Service Providers Initiated Single Sign-on, which is what happens when the user visits the service first, and needs to be authenticated.
This is the basic process by which SAML works and represents a best practice deployment. The support for deep-linking to a resource through a SAML Request/Response is a huge boost for end-user usability, and critical to the layering of OAuth into the process.
An Overview of OAuth
The OAuth protocol is slightly different, as it's primarily a protocol performed between the client application, and the Service Provider...in this case known in OAuth as the Authorization Server
Combining SAML and OAuth
With an understanding of these two flows, we can now look at layering them together in order to achieve SAML based single sign-on for oauth enabled desktop and mobile applications
As you can see, when layered together with SAML, the OAuth protocol is simply treated like any other bookmark or deep-link. In short, there is no additional development or deployment required to enable single sign-on for desktop and mobile apps. The only requirement is that a best practice SAML configuration is deployed as covered in the next section.
The Force.com 'My Domain' feature allows you to select a custom domain name for your application. A 'My Domain' URL looks like https://customer.my.salesforce.com/ (for a production org) or https://customer-developer-edition.my.salesforce.com/ (for a Developer Edition). A benefit of configuring 'My Domain' is that it enables support for SP-initiated single sign-on, improving the user experience, and allowing users to access 'deep links' into their environment via SSO.
You may configure 'My Domain' in Setup | Company Profile | My Domain. As users may be un-authenticated when they arrive at salesforce.com, a unique domain is the mechanism by which a specific organization's SAML configuration can be discovered. In order to take advantage of SAML for desktop and mobile apps you must deploy My Domain. In addition, this will greatly improve the user-experience for web browser based single sign-on. This is considered Best Practice for customers deploying SAML with salesforce.com
Perhaps the easiest way to illustrate the simplicity of this type of single sign-on is to walk through a detailed example. In the following example we'll demonstrate the use of Chatter Desktop with a sample single sign-on service
Behind the scenes
The following example assumes that the user's org has properly configured their Org to support SP Initiated SAML, using My Domain. In this case, the domain is 'cmort-deverloper-edition.my.salesforce.com'. In addition, their SAML configuration is properly pointing the Identity Provider Login URL at their SAML server's endpoint that handle's SP Initiated SAML, and can properly echo the 'RelayState' parameter
1. First, the user launches Chatter Desktop, and clicks on 'Add New Connection'
2. Next, the user configures their client to point at their 'My Domain'
3. The user saves the configuration, and clicks on 'Authenticate'
4. The client initiates OAuth
At this point, the Chatter Desktop client creates a tiny web browser inside the client, and attempts to load the URL of the Salesforce OAuth Authorization Service. The following illustrates what happens inside the browser as initiated by the client. (note that requests, URLs, and headers have been simplified for brevity)
GET /services/oauth2/authorize HTTP/1.1 Host: cmort-developer-edition.my.salesforce.com User-Agent: ChatterDesktop
5. The Authorization Server requires authentication and initiates SAML
As the user is first required to authenticate, the Authorization Server looks at the request, and determines that a 'My Domain' is in use. Using the custom domain, the server looks up the user's organizational metadata and fetches it's SAML configuration. In this case it finds the user should use SAML to authenticate, and sends a SAML request to the configured Identity Provider using the user's browser. A long with this request, the resource that user was originally trying to access is sent via The following illustrates what happens inside the browser automatically as directed by the server. (note that requests, URLs, and headers have been simplified for brevity)
POST /idp/SSO.saml2 HTTP/1.1 Host: sso.xmldap.org:9031 Content-Type: application/x-www-form-urlencoded Content-Length: 5521 RelayState=%2Fservices%2Foauth2/authorize&SAMLRequest=PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGl...
6. The user's Identity Provider authenticates the user
7. The Identity Provider sends the user back to Salesforce with a SAML Response.
Having authenticated the user, the Identity Provider formulates a SAML response and sends it back to Salesforce, along with the RelayState parameter indicating the user should return to the OAuth Authorization Service. The following illustrates what happens inside the browser automatically as directed by the server. (note that requests, URLs, and headers have been simplified for brevity)
POST / HTTP/1.1 Host: login.salesforce.com Content-Type: application/x-www-form-urlencoded Content-Length: 6456 SAMLResponse=PHNhbWxwOlJlc3BvbnNlIEluUmVzcG9uc2VUbz0iXzJi....&RelayState=%2Fservices%2Foauth2/authorize
8. The assertion is processed, the user is given a session, and taken to the Authorization Service
9. The user approves and is now connected to Chatter Desktop
When the user approves the application, a few critical things happen.
Using these tokens, the client can talk to the Chatter APIs and render the user's Chatter Feed. Subsequent access uses the refresh token for authentication, and does not require an additional SAML exchange
While not all Salesforce.com clients have been upgraded to support this feature, the following already support this technique.
In addition, a variety of ISV applications also support single sign-on in this manner. And because this is constructed using open standards and public APIs, this may be used for custom development as well. Developers interested in supporting this best practice should consult the section 'Advice for Application Developers'
Note: notably missing from supported clients are the Mobile CRM products. It is planned that the next generation of mobile CRM products, as well as mobile development offerings will support SAML based single sign-on. In the meantime, Delegated Authentication is the supported option.
Given the use of URLs to discover the user's Identity Provider information, one challenge with this approach is configuring the client to point at a My Domain. There are a variety of techniques used to provide this configuration, following common approaches specific to each individual platform. The following details the approach for each of the major clients:
Chatter Desktop supports the ability for the user to configure their My Domain URL directly from the initial launch screen. See the section called 'A Detailed Example' for screenshots of this process
Chatter Desktop: Managed Edition
Chatter Desktop also comes in a Managed Edition, which is designed to allow central deployment of the application by an enterprise IT group. In this version, the IT group may specify a configuration file called 'chatterdesktop.xml' which allows pre-configuration of the URL. The following is an example of that XML file configured for our example Identity Provider:
<chatterdesktop> <config> <launchOnStartup default="false" editable="false"/> <minimizeOnClose default="false" editable="true"/> <commentsInFeed default="true" editable="true"/> <notifications default="true" editable="true"/> </config> <servers> <server label="My Company's Org" serverUrl="https://cmort-developer-edition.my.salesforce.com" defaultServer="true"/> </servers> </chatterdesktop>
Chatter for iPhone and iPad
On iOS based devices, the My Domain URL may be configured under the Chatter section found in General Settings. Users should tap on the Settings app, and select Chatter Settings, at which point they must specify two settings under 'Connection'
The following is an example of a correctly configured iOS device.
Chatter for Android
TODO - INSERT TEXT FROM MOBILE TEAM
Chatter for Blackberry
To configure Chatter for Blackberry for use with SAML, follow these steps
1. Go to the Options app
2. Select Third Party Apps
3. Select Chatter
4. Under Connection: Login Host, select “Custom”. Under Custom Host: enter the the My Domain URL. Note that 'https://' is not required
5. Choose Escape > Save. Go back to the Chatter app and login.
Salesforce for Outlook
To configure Salesforce for Outlook for use with SAML, follow these steps
1. Select 'Other' from the 'Change URL' drop down menu.
2. Enter your My Domain URL and hit 'ok'
When deploying single sign-on for devices the following is best practice to be considered
When building OAuth enabled applications the following best practice should be considered
Another option for authenticating users on Mobile and Desktop devices is Delegated Authentication. If enabled for an organization and user's profile, when a user attempts to authenticate directly to Salesforce, the credential is sent back to a customer configured endpoint over a HTTPS secured web-service. Salesforce uses the following process for authenticating users using delegated authentication:
Using this process, customers can easily use their existing authentication systems to validate credentials. This approach works will all mobile and desktop clients. Once a delegated authentication service is built and enabled for a user, there is no additional configuration required. Users will login using the regular Salesforce login screens, but their credential will simply be validated remotely.
Historically, many customers of Salesforce have implemented Single Sign-On on-top of our Delegated Authentication protocol. In essence, this works as follows:
If the response is "true," then the login process continues, a new session is generated, and the user proceeds to the application.
This protocol is supported, but not recommended for new deployments, as it is a proprietary single sign-on implementation, and has long since been superseded by SAML, an industry standard. By conforming to standards, companies can easily establish single sign-on using off the shelf software.
However, if a customer has an existing deployment of single sign-on over delegated authentication, they may wish to take advantage of this with mobile or desktop clients. While Delegated Authentication deployments cannot speak SAML, they can be adapted to take advantage of these capabilities by using part of the SAML protocol. This requires small adjustments to the code on the customer’s Single Sign-On service. The process works as follows:
To paraphrase, Salesforce sends the user over SAML, but they are sent back using Delegated Authentication SSO. The RelayState is transformed into startURL to get the user where they want to go. Using this technique, mobile and desktop applications that can take advantage of SAML with Salesforce can also take advantage of SSO over Delegated Authentication.
Customers who properly configured their organization to use SAML 2.0 single sign-on, may now leverage this same capability across a variety of desktop and mobile applications. This article demonstrated how to configure the two systems to enable seamless SSO, and leverage that across devices.