Single Sign-On for Desktop and Mobile Applications using SAML and OAuth

Abstract

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 a concrete example (the Chatter application). The article ends with advice on deploying and developing applications using this technology.

Overview

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.

Core Tenets of SSO for 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:

• Desktop and mobile applications are being re-written to use OAuth to connect to user accounts. Users must authenticate and authorize the application. Once this is complete, a high-entropy (long, random) token is issued to the device and used in lieu of a password the next time the application is used. This credential is unique to the combination of user and application, and can be monitored, managed, and revoked independently.
• These applications are now using web browsers to authenticate instead of native code. By using web browsers, the applications are able to participate in single sign-on protocols written for the web. Previously this was not possible, as each application would be hard coded to ask the user for a username and password.
• Authentication is separated from Authorization. By separating these two functions, the application can now more easily adapt to changes in either. For instance, while normally a client may prompt the user to login using a web page served from one of its servers, SAML can easily be performed instead. It's also simple to perform adaptive risk-based authentication techniques, obviating the need for cumbersome security techniques such as the Salesforce API token ( a second credential historically used with applications )
• Deployment must be simple and standard. Organizations deploying single sign-on should do so once and have it work everywhere. Complex decisions and custom deployments should not be required when deploying mobile and desktop apps.

Let's make this a little more concrete by diving into SAML and OAuth.

Combining 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.

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 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.

1. The user makes a request to Force.com for a specific resource. This request may happen in a variety of ways for a variety of reasons. For example, the user may be following a bookmark, clicking on a link from an email, or allowing their browser to auto-complete.
2. Force.com detects the user needs to authenticate and redirects the user to their SAML Identity Provider. Since the user doesn't present a session cookie, they need to authenticate. An organization-specific host name allows the user's org to be discovered, and they are sent over the SAML protocol. Along with a SAML Request, an HTTP parameter called RelayState is passed along to the IdP. This captures the location of the resource the user originally requested
3. The user accesses their IdP and authenticates. This authentication is performed by the IdP giving the customer complete control over the authentication process. A variety of popular techniques may be used, such as a LDAP, a web access management system, Integrated Windows Authentication, or a 2-factor system such as SecurID.
4. Once authenticated, the IDP sends a SAML Response back to Salesforce.com. This response happens through the user's browser, and includes the RelayState originally sent by the Service Provider. The echoing of RelayState is critical to the success of the protocol, as this is what allows the user to be returned to the originally requested resource.
5. Force.com processes the SAML assertion and logs the user in. The digital signature applied to the SAML Response allows verification that the message is from the customer, at which point the user is authenticated. They are granted a session and redirected to their original request

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, which, in the case of OAuth is known as the Authorization Server.

1. The OAuth Client makes an authorization request. Since the client wants to connect to the user's account, it must ask for authorization to do so. In the case of Force.com clients, they open an embedded web browser and attempt to open a URL to the Force.com Authorization Server.
2. The Authorization Server authenticates the user. It's essential that the user is authenticated so that the client is connected to the proper account. In normal use cases this is simply done using a web page served by Force.com, similar to a normal login. If the user is already authenticated, they may not even be prompted, as authentication can be determined via the user's session cookie.
3. The user authorizes the application. Once authenticated, the user is prompted to approve the application connecting to their account. This is a simple web page showing the user information about the application and what it's requesting
4. The application is issued an OAuth token. If the user approves the application, the application is issued a high-entropy token that can be used to establish a session for the user by the application. Subsequent usage of the application does not require the user re-enter their credentials.

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

1. The OAuth Client makes an authorization request to a hostname you specify. Using an embedded browser, the client asks for authorization from the user, but does so to the custom URL ( using a feature called 'My Domain' which is detailed in the next section ).
2. The Authorization Server detects the user needs to authenticate and redirects the user to their SAML Identity Provider. The URL for the Authorization Server is passed via the RelayState parameter.
3. The user accesses their IDP and authenticates. This authentication is performed by the IDP giving you complete control over the authentication process.
4. Once authenticated, the IDP sends a SAML Response back to Force.com. This response happens though the user's browser, and includes the RelayState indicating the user should eventually return to the OAuth Authorization Server.
5. Force.com processes the SAML assertion and logs the user in. The digital signature applied to the SAML Response allows verification that the message is from your system, and which point the user is authenticated and redirected to the authorization server.
6. The user authorizes the application. Once authenticated the user is prompted to approve the application connecting to their account. This is a simple web page showing the user information about the application and what it's requesting
7. The application is issued an OAuth token. If the user approves the application, the application is issued a high-entropy token that can be used to establish a session for the user by the application. Subsequent usage of the application does not require the user re-enter their credentials.

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.

Enabling Bookmarks And Deep-Linking With 'My Domain'

The Force.com 'My Domain' feature allows you to select a custom domain name for your application. A 'My Domain' URL looks likehttps://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.

A Detailed Example

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-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)

1	GET /services/oauth2/authorize HTTP/1.1

2	Host: cmort-developer-edition.my.salesforce.com

3	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)

1	POST /idp/SSO.saml2 HTTP/1.1

2	Host: sso.xmldap.org:9031

3	Content-Type: application/x-www-form-urlencoded

4	Content-Length: 5521

5

6	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)

1	POST / HTTP/1.1

2	Host: login.salesforce.com

3	Content-Type: application/x-www-form-urlencoded

4	Content-Length: 6456

5

6	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.

• The application becomes connected to the account. This approval can be revoked at any time by the user, severing the tie to the application
• The application is issues a session to access APIs on the user's behalf. In OAuth this is called an 'access token'
• The application is issued a secret that can be used to obtain more sessions. This functions much like a password, but is specific to the user and application.

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

Supported Clients

While not all Force.com clients have been upgraded to support this feature, the following already support this technique.

• Chatter Desktop
• Chatter for iPhone
• Chatter for iPad
• Chatter for Android
• Chatter for Blackberry
• Salesforce for Outlook

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.

Client Specific Configuration

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

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:

01

>

02

>

03	default="false" editable="false"/>

04	default="false" editable="true"/>

05	default="true" editable="true"/>

06	default="true" editable="true"/>

07

>

08

>

09	label="My Company's Org"

10	serverUrl="https://cmort-developer-edition.my.salesforce.com"

11	defaultServer="true"/>

12

>

13

>

Complete details on the format of this file and its deployment can be found in the Chatter Desktop Release Notes.

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'

1. The 'Login Host' must be changed from 'Production' to 'Custom Host'
2. The 'Custom Host' must be set 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

The following is an example of a correctly configured iOS device.

Chatter for Android

To configure Chatter for Android for use with SAML, follow these steps:

1. Launch the Chatter 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'

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'

Advice for Deploying Applications

When deploying single sign-on for devices the following is best practice to be considered

• Confirm that SP-initiated SAML is working properly. Often deployments may have difficulty properly propagating the 'RelayState' parameter through a SAML Request and Response. While this is a standards based approach, you should verify that you are using the specific endpoints with your IdP for SP-initiated SAML, that the 'RelayState' parameter's URL encoding is properly maintained, and that the exact value that is sent to the IdP is echoed back to Force.com. The returned value must match what is sent *exactly*.
• Clearly communicate your My Domain to users and provide client specific instructions. With the exception of Chatter Desktop: Managed Edition, users bear the responsibility of properly configuring their clients. Make sure and educate your users on their URL and the proper means of configuring as you roll out the applications.
• Consider the impact of IP restrictions. If you have deployed IP restrictions, consider the impact on Mobile devices. VPN and BES servers may help alleviate issues. In addition, the mobile Chatter clients support sending activation emails to clients in order to enable the bypass of IP restrictions. See the documentation for more on this.
• Assess the design of your Identity Provider's login page. Both the size and performance characteristics of mobile clients may impact the user's experience. While the Force.com login services can dynamically adapt to a variety of devices, when hosting your own Identity Provider you must consider the size and speed of your login page. Consider sniffing user-agents and providing tailored or simplified authentication interfaces to less capable clients. This is especially important when authenticating older Blackberries.

Advice for Application Developers

When building OAuth enabled applications the following best practice should be considered

• Allow users to specify their My Domain. When deploying your application, it's important that users be able to specify the login service they want to authenticate with. It is best practice to allow the user to choose 'Production', 'Sandbox' (or 'Test'), and 'Custom'. In order to use single sign-on users must be able to specify this custom host. Also consider techniques to simplify this configuration, such as allowing an enterprise IT group to centrally manage configuration on the user's behalf.
• Consider the size of your login window. Given the wide variety of Identity Providers, it is difficult to predict the look and feel of the page you may be presented when users login over SAML. While some platforms such as Android and iOS can gracefully adapt to a variety of pages, other platforms may be more problematic. In these scenarios, consider using a reasonably large authentication interface, and/or allowing the user to resize or scroll the interface.

Using Delegated Authentication

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:

1. When a user tries to log in, Force.com validates the username and checks the user’s profile settings.
2. If the user’s profile has the Is Single Sign-On Enabled user permission, then Force.com does not validate the username and password. Instead, a web services call is made to the user’s organization, asking it to validate the username and password. Note Force.com doesn't store, log, or view the password in any way. It is disposed of immediately once the process is complete.
3. The web services call passes the username, password, and IP address of the user to the a web service that you host.
4. Your implementation of the web service validates the passed information and returns either true or false.
5. If the response is true, then the login process continues, a new session is generated, and the user proceeds to the application. If false is returned, then the user is informed that the username and password combination is invalid.

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.

Adapting Existing Delegated Authentication Based Single Sign-On

Historically, many customers of salesforce.com have implemented Single Sign-On on-top of our Delegated Authentication protocol. In essence, this works as follows:

1. Users would start at a Single Sign-On page, perhaps on their corporate intranet.
2. The user logs in locally to their own authentication system
3. The Single Sign-On page generates some sort of cryptographic token.
4. The Force.com username and token are automatically posted to our login page. In addition a “startURL” indicating a page to take the user to next may be included
5. Based upon the user’s profile having the "Uses Single Sign-on" user permission enabled, Force.com makes a web Services call to your custom single sign-on service, asking it to validate the username and token.
6. The service validates the cryptographic token and and returns either "true" or "false."

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:

1. Configure ‘My Domain’ and SAML for your organization. Dummy values can be configured for the SAML settings for everything except their Identity Provider Login URL. This must be a URL that receives the SAML Authentication Request from Force.com, but it need not actually process the SAML
2. A user requests a resource in their org, for example: https://customer.my.salesforce.com/001/o
3. Force.com notices that the user does not have a session for that org, and sends a SAML Authentication Request to the org’s Single Sign-On service. This includes a parameter called “RelayState” that is the URL the user was requesting ( in this example “/001/o” )
4. The Single Sign-On service receives both the “SAMLRequest“ and “RelayState” as HTTP parameters via a POST. The service ignores the SAMLRequest, but picks up the RelayState
5. The Single Sign-On service authenticates the user and generates a cryptographic token
6. The Force.com username and token are automatically posted to our login page. In addition a “startURL” parameter is echoed back with the value obtained from the RelayState parameter
7. Based upon the user’s profile having the "Uses Single Sign-on" user permission enabled, Force.com makes a Web Services call to the single sign-on service, asking it to validate the username and token.
8. The service validates the cryptographic token and and returns either "true" or "false."
9. If the response is "true," then the login process continues, a new session is generated, and the user proceeds to the page they originally requested

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.

A note about ADFS

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.

Summary

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.

References

• Single Sign-On with SAML on Force.com
• Single Sign-On with Force.com and Microsoft Active Directory Federation Services
• Digging Deeper into OAuth 2.0 on Force.com
• Using OAuth to Authorize External Applications