This article provides an overview of how Force.com uses a combination of OAuth and SAML functionality to provide seamless SSO facilities for applications. It looks at each of the technologies in turn, and shows how they are used in some concrete examples such as:
The article ends with advice on deploying and developing applications using this technology.
As applications and data 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 unprecedented mobility and functionality. Historically, this has been a challenging environment when combined with single sign-on, as many of the standard technologies are designed explicitly for web browsers. This creates an awkward tension for the deployer; 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 Force.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 a framework useful for connecting applications to users' accounts. It provides a variety of benefits including developer simplicity, improved security by not exposing user credentials unnecessarily, 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 Force.com enables 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 tenets:
Let's make this a little more concrete by diving into SAML and OAuth.
Since our approach is based upon the layering of two complementary protocols, it's best to first take a look at these independently.
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 you would typically host. 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 Provider 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.
The OAuth protocol is slightly different, as it's primarily a protocol performed between the client application, and the Service Provider, which, in the case of OAuth is known as the Authorization Server.
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 Force.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 a best practice if you deploy SAML with Force.com.
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.
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-developer-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 Force.com 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 its 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. Along with this request, the resource that user was originally trying to access is sent via XXX.
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 Force.com with a SAML Response.
Having authenticated the user, the Identity Provider formulates a SAML response and sends it back to Force.com, 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 Force.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. 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 previous section 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>
Complete details on the format of this file and its deployment can be found in the Chatter Desktop Release Notes.
To configure Salesforce1 for iOS or Android based devices, the My Domain URL may be configured under the Connection Settings. Follow these steps:
1. Launch the Salesforce1 mobile app and tap the gear icon at the top right of the Login page
2. Tap the '+' icon to add new login host and hit 'Done' to save
3. Set the new connection to the My domain URL for the user's org. Note that for simplicity 'https://' is implicit and should not be provided by the user
4. Select the connection that you have just created
5. You will be taken to your user's org Single Sign-on provider service. You can now enter your SSO credential and login to Salesforce1
Note that if your Org's user uses more than one authentication service you will be taken to the Login page. In the following example the My Domain Login Page is configured to work with both the standard Login page and the SSO authentication service of Pacifica organization.
SalesforceA for iOS
To configure SalesforceA for iOS for use with SAML, the My Domain URL may be configured under the SalesforceA section in General Settings. Users should tap on the Settings app, and select SalesforceA settings, at which point they must specify two settings under 'CONNECTION'
The following is an example of a correctly configured iOS device.
SalesforceA for Android
To configure SalesforceA for Android for use with SAML, follow these steps:
1. Launch the SalesforceA app, access the menu, and select 'Change Server'
2. Select 'Add Connection'
3. Enter your My Domain URL and touch 'Apply'
4. Make sure your URL is selected and touch 'Apply'
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 Force.com, the credential is sent back to a custom configured endpoint over a HTTPS secured web-service. Salesforce uses the following process for authenticating users using delegated authentication:
Using this process, you can easily use your existing authentication systems to validate credentials. This approach works with 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 Force.com login screens, but their credential will simply be validated remotely by your web service.
Historically, many customers of salesforce.com 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.
How to Implement Single Sign-On with Force.com provides a full overview of this technique.
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 you have an existing deployment of single sign-on over delegated authentication, then you 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 in your Single Sign-On service. The process works as follows:
To paraphrase, Force.com 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 Force.com can also take advantage of SSO over Delegated Authentication.
When using ADFS v2, configure "HTTP Redirect" for the "Service Provider Initiated Request Binding" option in Single Sign-On settings, made available in Winter 13.
Additionally, ADFS Rollup 2 needs to be applied to ADFS - without it, ADFS does not properly handle RelayState.
If you properly configure organizations to use SAML 2.0 single sign-on, then you can 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.