With the proliferation of SaaS and other web-based applications, identity management is becoming a major concern for businesses. Just think about the number of usernames and password you regularly type each day. You probably log into your company's network, portal, webmail, benefits system, Google Apps, bespoke applications and of course Force.com applications. Now multiply this by the number of users in your company and think about the support and security implications. You need dedicated resources to manage your identity store, respond to password reset requests, provision new users for each system and deactivate users that no longer need access. Just think of the number of man hours you could save if you could eliminate 25-50% of your passwords and their associated costs!

Implementing a Single Sign-On (SSO) infrastructure enables users to sign in once and have access to all authorized resources. In this article, we'll look at the different methods of implementing SSO with Force.com, how to set up your own open source identity management system for federated authentication using SAML 2, and how to configure the Force.com platform to utilize your new identify provider. We'll also provide some troubleshooting techniques and outline some best practices to help you avoid common roadblocks, getting you up and running fast.

Benefits of Implementing SSO

Implementing SSO provides not only time-saving benefits for end users but financial benefits for your company. Major benefits of SSO include:

  • Improved productivity - It takes an average of 20 seconds for a user to log into a resource. Not having to enter a password each time a user needs to access a resource saves time and makes users more productive.
  • Reduce frustration of multiple log-on events and forgotten passwords - Users only have one password to remember and update, and only one set of password rules to remember. Their initial login provides them with access to all resources, typically for the entire day.
  • Increased adoption - SSO reduces the barriers of use for resources. Since it is easier to access applications, users will start using them more.
  • Centralized user access control - A single registry of user identities with a centralized management interface allows quick and easy provisioning and deactivating of users.
  • Improved reporting and monitoring - A single repository for auditing and logging access to resources provides streamlined regulatory compliance.
  • Increased security - A secure, enterprise-wide infrastructure with common password and security policies that can be centrally managed and secured. Users are also less likely to write down their passwords when there is only one to remember.
  • Uniform security layer - SAML is platform agnostic allowing enterprise architects to implement a uniform security layer with existing assets.
  • Reduced helpdesk costs - Fewer helpdesk calls for password resets relates directly to bottom-line savings.

In other words, there are substantial benefits to implementing SSO. Let's now turn to the options available on Force.com, before delving into a SAML implementation.

Options for Implementing SSO on Force.com

Force.com supports both delegated and federated authentication for SSO. Since federated authentication is the default form of single sign-on, we will be covering it in detail in the rest of this article. However, for the sake of completeness, we'll briefly cover delegated authentication first.

Delegated authentication

Using delegated authentication, Force.com does not validate passwords but instead uses an external Web service to validate user credentials. When a user attempts to login, the platform checks the user's profile to see if they are enabled for SSO. If so, it makes a Web services call to the the endpoint specified for the organization (environment), asking it to validate the username and password. The Web services checks the credentials against an identity store (for example LDAP or OpenID) and either returns "true" or "false". If true, the user is granted access to the application and proceeds normally. If false, the user is informed that their credentials are invalid.

Delegated authentication has a few drawbacks with respect to federated authentication. First, delegated authentication is inherently less secure than federated authentication. Even if encrypted, delegated authentication still sends the username and password (possibly even your network password) over the internet to Force.com. Some companies have policies that preclude a third party for handling their network passwords. Second, delegated authentication requires much more work for the company implementing it. The Web services endpoint configured for the org must be developed, hosted, exposed on the Internet, and integrated with the company's identity store.

Federated Authentication

As with delegated authentication, federated authentication does not validate the user's actual password on the Force.com platform either. Instead, the platform receives a SAML assertion in an HTTP POST request. The SAML assertion has a limited validity period, contains a unique identifier, and is digitally signed. If the assertion is still within its validity period, has an identifier that has not been used before, and has a valid signature from a trusted identity provider, the user is granted access to the application. If the assertion fails validation for any reason, the user is informed that their credentials are invalid. The rest of this article shows how to set this up.

Some Background: How Federated Authentication Works

Security Assertion Markup Language (SAML) provides a secure, XML-based solution for exchanging user security information between an identity provider (your company) and a service provider (Force.com). SAML 2 is a major revision from the SAML 1.1 standard and now supports, among other things, W3C XML encryption and service provider initiated web single sign-on exchanges. This allows service providers like Force.com to query the identity provider for authentication. SAML 2 also adds a useful feature called "single logout", which defines a mechanism for logging out of all service providers quickly and easily. Some of the major features of SAML 2 include:

  • Platform neutrality - abstracts the security framework away from particular vendor implementations and architectures
  • Loosely coupled - SAML does not require user credentials to be maintained and synchronized between directories
  • Flexibility - it is metadata-driven, allowing identity providers to determine agreements and configurations for multiple service providers

There are three roles involved in a SAML transaction:

  • an identity provider (the asserting party),
  • a service provider (the relying party relying on the assertion), and
  • a user (the subject of the assertion).

The identity provider is the authority system that provides the user information. We will be setting up our identity provider shortly. The service provider is the system, in this case Force.com, that trusts the identity provider's user information, and uses the data to provide access to the service or application. The user and their identity combined are known as the subject.

The transaction from our identity provider to Force.com is called a SAML assertion. Force.com assumes that all data contained in the assertion from our identity provider is valid. The structure of the SAML assertion is defined by an XML schema that is specified by the OASIS SAML standard and contains header information, the subject and statements about the subject in the form of attributes and conditions such as a start and logout URL. In our examples, our SAML assertions will contain a Federated ID from the identity provider which is guaranteed to be unique within the Force.com org.

Web browser SSO is SAML's most widely used feature and is typically used in conjunction with the HTTP POST binding and authentication request protocol. Web browser SSO may be initiated by the identify provider or by Force.com if a user's session has not been established. If initiated by the identity provider, the assertion is signed. With the web browser SSO profile, Force.com receives all of the assertion information at once using any of the HTTP bindings and protocols. Force.com checks the message integrity using the contained signature against the identity provider certificate defined in our org. Next, it parses the SAML XML statements and gathers any attributes that were passed (for example Force.com username, employeeId), and then attempts the login process.

There are two important use cases for SAML -- Identity Provider Initiated Login, where a user starts directly at their identity provider, logs in, and is then redirected to a landing page at the service provider; and Service Provider Initiated Login, where a user starts by clicking a link to the the service provider (e.g. a bookmark, mailed link, etc) and temporarily redirected to the identity provider for authentication, then returned to the link they initially requested. Force.com supports both of these use cases.

Saml 1.png

With the theory out of the way, let's get down to business and create an implementation.

Implementing our own Identify Provider

There are a number of open source identity solutions that support federated authentication using SAML. OpenSAML, a widely-used open source Java and C++ toolkit, is available to develop solutions with SAML. Notable projects using SAML 2 include Shibboleth, JOSSO and JBoss Federated SSO. Your company may already have an identity provider in place, but for our example, we'll be setting up an identity provider using OpenSSO, the open source version of OpenSSO Enterprise from Sun Microsystems. Sun has gone to great lengths to make the configuration process as painless as possible and even has a specialized configuration process for Force.com. Thanks Sun! OpenSSO runs on a large number of Java EE servers but we'll be using Sun's GlassFish open source application server as it is OpenSSO's preferred container.

To set up federated authentication, we need to configure a local entity, a partner entity (your Force.com environment) and then establish an association between the two in the Force.com administrative interface which forms a federation. To manually configure our local entity, we need to first determine what will be the unique identifier that will be passed to Force.com as part of the assertion. Typically with SSO this value is an employee number or corporate email address that is guaranteed to be unique for each users. To tie into a company's existing security infrastructure, these values typically originate from data sources such as LDAP, a corporate HR system or even identity service such as OpenID. In our example we are going to use a simple phone number.

Installing the GlassFish Application Server

You can download GlassFish v2.1 here along with documentation. Use the installation guide to set the server up (I used the jar installer) and the quick start guide to start the server. The installation process is fairly straightforward and should only take about 10-15 minutes to get the server up and running. Make sure the server you install GlassFish on is accessible to Force.com and not hidden behind a firewall. Also, you'll have to run the server on a fully qualified domain name. In the example below, we use dev.bluemethod.com - choose your own. For OpenSSO to work properly it cannot run on an IP address or localhost.

Installing and Configuring OpenSSO

The OpenSSO download is quite large, +300MB, so be prepared for a wait. There is a really great article that walks you through the entire installation and configuration process. You can accept most of the defaults during the configuration process but pay attention to the selection in step #4. This is the step where you select a data store that holds your users. By default, the "Other User Data Store" option is selected allowing you to configure your LDAP connection. Select the "OpenSSO User Data Store" instead (the screenshot in the article displays it as "Embedded"). You should see a warning that states the OpenSSO user data store is only for development purposes and is not supported for production environments. When you eventually put this solution into production you'll need to circle-back to this screen and configure your production data store.

Once OpenSSO is configured properly it's time to configure our identity and service providers. Log into the OpenSSO Administration Console, click "Create Hosted Identity Provider" and then create a new Circle of Trust. Choose the "test" signing key and enter a name for the Circle of Trust. You do not need to specify any Attribute Mappings at this time.

Saml 2.png

After your identify provider has been configured click the link to "Configure Salesforce CRM". This is the crucial step. We are going to create the mapping for the values that will be passed to Force.com in the SAML assertion. For our example we are going to send the value of the identity providers user's telephone number in the assertion so that the Force.com platform can use this in conjunction with the Force.com user's matching Federation ID value.

Type "ATTR_PHONE" in the first input. This is the attribute in the assertion that contains the identity provider's telephone number. Type "telephonenumber" in the second input and click the Add button.

Saml 3.png

After clicking the Create button a screen that looks like the one below displays. This screen contains important information that you need for Force.com so we are going to leave it open for a while. Sun has done a good job of providing step-by-step instructions but we are going to go through them in a little different order. The last item, #18, is a little confusing so we'll discuss that during the Force.com setup.

First, download the Verification Certificate to your local machine in a plain text file. We'll need this file when setting up SSO in Force.com. Also, notice the "Salesforce Login URL" at the bottom. This URL will be generated for us by Force.com when setting up SSO so do not close this screen or click finish at this time. After configuring Force.com we will paste the Force.com Login URL into this field.

Saml 4.png

Configuring Force.com for SSO

Now that we have our identity provider built it's time to configure Force.com to use SSO. Fortunately this is the easiest part of the entire process. Login into your Force.com org and click Setup -> Security Controls -> Single Sign-On Settings. The screen should initially look like the following.

Saml 5.png

Click the Edit button and then check the SAML Enabled checkbox to display the input fields for the SAML. Upload your Verification Certificate file and set up your organization to look like the screen below. This configuration tells the Force.com platform that the attribute, ATTR_PHONE, is being mapped to the Force.com user's Federation ID attribute.

Saml 6.png

After saving the settings your screen should look like this the following. This screen contains the Force.com Login URL that OpenSSO requires. Copy this URL and paste it into the "Salesforce Login URL" in OpenSSO. You can now click the Finish button on the OpenSSO screen.

Be careful if you make changes to these SSO settings as it may generate a new Force.com Login URL. If it does, you will need to update the Force.com URL in OpenSSO.

Saml 7.png

Configure the Identity Provider User

To test the SSO configuration we need to configure a user in the identity provider's user data store. For this example, we'll use the default user OpenSSO has already created - demo. In the OpenSSO Administration Console, click Access Control -> Top Level Realm -> Subjects -> demo. Enter a telephone number for the user (copy it to your clipboard) and Save the user.

Configure the Force.com User

Configuring users for federated authentication is a little different than delegated authentication. With delegated authenticated you enable a profile to use SSO, and all users in that profile have access to Force.com using SSO. Federated authentication is simpler and more straightforward as everything is done at the user level.

Either select an existing user or setup a new one. Since SSO is enabled you'll see a new field on the user details page called, "Federation ID". Edit the user details and enter the same phone number you used for the identity provider's user. The value should still be on your clipboard. Once you save the user, setting up federated authentication is complete and we are ready to test our SSO solution.

Saml x.png

Testing Single Sign-On

To test the SSO solution, sign out of both OpenSSO and your Force.com environment. Modify the URL below for your server and enter it into your browser.


Since you are not logged in to OpenSSO, the OpenSSO login screen should now display. Enter your demo user's credentials for access ("demo" and "changeit" by default). Once you submit the login form, the SAML assertion is passed to the Force.com platform and, if everything is configured correctly, you should be logged into your Force.com org and viewing your user's home page.

Troubleshooting Single Sign-On

If SSO is not working for you there are a few ways you can troubleshoot the issue.

  1. Check the Force.com login history for errors by going to Setup -> Manage Users -> Login History. If you do not see a failed login attempt then you probably have something misconfigured with the Federation ID. The Force.com platform cannot match your user from the SAML assertion so the failed login attempt in not even recorded. Check the Force.com help for details on SSO error messages.
  2. You can paste your SAML assertion into the SAML Assertion Validator on the Single Sign-On Settings page. This gives you a good view of what's going on and can possibly point you in the right direction.
  3. Try downloading the Firefox add-on, Live HTTP Headers, so that you can easily view the packets that are being sent during the login process.

Best Practices for Federated SSO=

Consider the following best practices when implementing federated single sign-on for your organization:

  • Develop a clear rollout strategy and end user communication policy to reduce confusion during the SSO cutover process.
  • For larger, global organizations consider an identity provider in each region to minimize network latency and support and administration costs.
  • System Administrators should not be SSO-enabled as they will be locked out during outages.
  • Determine how your company will handle outages when the identity provider or user data store goes down.
  • Notify users that password resets for Force.com applications are no longer done from the Salesforce interface.
  • Inform users how SSO will impact Force.com applications such as Outlook plugin, Excel Connector, Force.com IDE and any other third-party applications.
  • If your identity provider requires you to set the Service Provider's Audience URL, set it to https://saml.salesforce.com.
  • Ensure you are running GlassFish from a fully qualified domains. Running it from http://localhost:8080 or even an external IP address will not work.
  • Determine how your organization will map your organization’s internal usernames to Force.com usernames. You may choose to add a unique identifier to the Federation ID field of each Force.com user, or extend your user database schema (for example, Active Directory) to include the Force.com username as an attribute of a user account. Be careful if you assume that all corporate email addresses map directly to Force.com usernames. Users may have inadvertently used their corporate email address in an different org (i.e., free or developer org).


This tutorial demonstrates how an SSO infrastructure can be beneficial to users and companies. It compares the different SSO methods available with the Force.com platform and provides a quick overview of how federated authentication works with SAML 2. The meat of the article lies in setting up an identity provider with OpenSSO and GlassFish, and walking you through the process of setting up the Force.com platform for SSO.

This tutorial is meant to get you up and running with SSO on the Force.com platform. In a production deployment of SAML and SSO, be sure to consult your security and network infrastructure teams on the configuration of your identity provider solution.


Background Material


About the Author

Jeff Douglas is a Senior Technical Consultant at Appirio where he creates cutting-edge applications on the Force.com platform for some of the best companies in the world. He is a foster and adoptive parent and actively tries to work the word "chartreuse" into everyday technical conversations. He actively blogs about cloud computing - especially Force.com.