Implementing Single Sign-On Across Multiple Organizations
With the rapid expansion of the cloud, more enterprises are using a number of organisations and applications built on Force.com. Often as a result of acquisition, departmental preference, or the desire for more granular control over resource utilization, large customers have deployed multiple organizations or "Orgs". While there are benefits to this deployment style, there are also costs. Users that require access to multiple Organizations may be frustrated by the need for multiple identities across these systems, and the corresponding usability challenges.
In these cases, single sign-on (SSO) technologies can come to the rescue, allowing users to authenticate at a single location, with a single set of credentials, and access multiple Orgs. Once implemented, users may move from Org to Org seamlessly, accessing records or collaborating on chatter in each org.
While this does not alleviate all the challenges related to multiple organizations, the techniques discussed in this paper can be used today to drastically simplify the end user experience in multi-org deployments.
The approach for implementing Single Sign-On across multiple Orgs can most easily be conceptualized as a "hub-and-spoke" model.
In the center of this architecture, we have an Identity Provider or "IdP". This plays the role of the centralized authentication "hub", and is responsible for validating a user's credentials and asserting the user's Identity to the "spokes", the Orgs.
When a user attempts to access an Org, and authentication is required, rather than prompting the user for authentication directly, the Org redirects the user to the Identity Provider. Once the Identity Provider has authenticated the user, it sends the user back to the requesting Org, which automatically grants access to the user based upon previously established trust between the Org and the Identity Provider.
Using this technique, the user may easily move from Org to Org; as authentication in a new Org is required, the process of redirecting to the Identity Provider is repeated. Since the Identity Provider can maintain a centralized session for the user, each time this occurs, it may not be necessary for the user to re-authenticate. The result is a seamless single sign-on experience for the user, resulting in faster and simpler access to all their resources.
Diving into the Details
In order to properly implement this technique, it is important to understand the details of both the approach, as well as the communication patterns, used between the Orgs and their Identity Provider.
As a starting point, single sign-on builds upon a feature called 'My Domain', which allows admins to select a custom host name for each of their Orgs. 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). You may configure 'My Domain' in Setup | Company Profile | My Domain; this is a mandatory step for the techniques covered in this article.
By configuring a 'My Domain', admins enable the Force.com platform to recognize the Org for which unauthenticated requests are intended, and perform customized behavior, such as redirecting to their Identity Provider. This is done using a standard known as Security Assertion Markup Language (SAML), allowing the role of the Identity Provider to be played by a wide variety of existing commercial and open source solutions.
SAML 2.0 defines several roles for parties involved in single sign-on. The user authenticates (logs in) to the Identity Provider (or IdP). The user is then able to access a resource at one or more Service Providers (abbreviated as SP, and also known as Relying Parties) such as Force.com, 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.
- 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, of allowing their browser to auto-complete.
- 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 hostname allows the user's Org to be discovered, and they are sent over the SAML protocol. Along with a SAML Request, a form parameter called RelayState is passed along to the IDP. This captures the location of the resource the user originally requested
- 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 LDAP, a web access management system, Integrated Windows Authentication, or a 2-factor system such as SecurID.
- Once authenticated, the IDP sends a SAML Response back to Force.com. This response happens via 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.
- 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 Identity Provider, 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.
Having reviewed the mechanics of single sign-on, you have all the required tools to deploy multi-org single sign-on; it is simply a matter of applying this approach to each of your Orgs, effectively tying all the Orgs to a single, trusted identity provider. The remainder of this paper will focus on a detailed description of the configuration steps required for deployment.
Configuring Single Sign-On for Multiple Orgs
In this section, we'll cover the steps required to configure single sign-on across multiple Orgs. As previously discussed, the standards-based SAML approach allows a variety of deployment options for admins, including on-premise software, or cloud-hosted solutions. In fact, even another Force.com Org may play this role thanks to its embedded SAML Identity Provider. The example in this article will illustrate the solution using a Force.com Org as the Identity Provider, but the same techniques may be employed with virtually any standards-based SAML software.
- All Orgs must be enabled with a custom hostname using 'My Domain'
- One Org must be selected to act as the Identity Provider
- A master list of all users
- A "Federated ID" for each user, unique for each person across users of all Orgs.
- The Dataloader, to bulk upload updates to usernames in the SP Orgs
The following diagram shows a high level sequence of the configuration process. Time flows from left to right, and there are 3 different areas of activity. The Desktop, the Service Provider Org, and the Identity Provider Org:
Step 1: Configure a 'My Domain' for each Org
This is a quick step, and should only take a few minutes to configure. Login as an Administrator to each of your Orgs, and browse to Setup > Company Profile > My Domain. Here you may choose a custom host name. Check for its availability, accept the terms of service, and submit. While salesforce.com is working to reduce latency of this process, it may take up-to 24 hours to complete. You'll receive an email when your change is complete.
As part of this process, consider choosing a logical naming scheme for your Orgs. Consider existing names or lines of business that users will logically relate to the resources managed in that Org, as this hostname will be visible to end-users in URLs.
For this example, the Identity Provider Org was named:
The 2 sample Service Provider Orgs were named:
Step 2: Deploy each 'My Domain' to your users:
Once you've received a confirmation email that your domains have been registered, login as the admin to that new domain name, and deploy this domain to the users:
Do this for each of your Orgs. It's important to consider that for existing orgs, this may impact existing user bookmarks, and you may wish to plan a user communication before proceeding with this step in existing production deployments.
Step 3: Enable the Identity Provider in your Identity Provider Org
Enabling an Identity Provider in your Org is as simple as pressing a button with salesforce.com's "one-click" Identity Provider. Login as an Administrator to each of your Orgs, and browse to "Setup" > "Security Controls" > "Identity Provider"
Once enabled, you'll see a new configuration screen for your Identity Provider.
Make note of the "Issuer", which is the MyDomain URL for this Org. In this case: https://edyidp-developer-edition.my.salesforce.com
Step 4: Download the Self-Signed Certificate from the IDP Org
Under "Setup" > "Security Controls" > "Certificate and Key Management", locate the new self-signed certificate that was generated for your Identity Provider. This certificate corresponds to a private key only available to your Identity Provider. Click Download Certificate to download this certificate to a file on your desktop. You will need this file in subsequent steps, as it will be used by each of your Service Provider Orgs to establish trust in the Identity Provider.
Step 5: Configure SAML in your first Service Provider Org
Login as an Administrator to the first Org you wish to configure as a Service Provider. Browse to "Setup" > "Security Controls" > "Single Sign-On Settings"
Follow these steps:
- Click 'Edit' and check the 'SAML enabled' checkbox. Doing so will reveal the next set of configuration parameters.
- Set your SAML version to "2.0"
- Enter your Identity Provider's "Issuer" that you made note of in Step 3 into the Issuer field. In this sample: https://edyidp-developer-edition.my.salesforce.com
- Click the "Choose File" button for the Identity Provider Certificate, and select the Identity Provider certificate that you downloaded to the desktop in Step 4.
- Enter the 'My Domain' URL of your Identity Provider + '/idp/endpoint/HttpPost' into the Identity Provider Login URL. In this sample you'd enter: https://edyidp-developer-edition.my.salesforce.com/idp/endpoint/HttpPost
- Change "SAML User ID Type" to "Assertion contains Federation ID from the User object"
- Change the Entity ID to the 'My Domain' URL for this Service Provider Org.
- Hit Save.
- Once complete, make note of the "Salesforce.com Login URL" You'll need it in Step 6.
Note: As of Winter 13, you must also configure your Spoke Org's Login Policy to point at your Identity Provider on the My Domain page. Browse to the Login Page Brand section on the My Domain page, and select My SAML IDP checkbox besides Authentication Service.
Step 6. Tell your Identity Provider about this Service Provider Org
Service Providers are now created via Connected Apps. Login as an Administrator to each of your Orgs, and browse to "Setup" > "Security Controls" > "Identity Provider" and follow these steps:
- Click “Service Providers are now created via Connected Apps. Click here.” under the list of "Service Providers"
- Enter a name for your first Connected App. In this case, I put SP1 Org.
- Select Enable SAML under Web App Settings.
- Enter the 'My Domain' of the Service Provider Org as the "Entity ID"
- Enter the ACS URL - this is the "Salesforce.com Login URL" you made note of in Step 5.9
- Select "Federation ID"
- Hit "Save"
- Assign this SSO configuration to any Profiles of your choosing
When complete, you will end up with a new Service Provider listed under your Identity Provider.
Step 7: Test your configuration
To test your configuration, follow these steps:
- Create a test user in your Identity Provider Org, and set their Federation ID to a unique value. Make sure you assign the user a Profile which was granted access to your Service Provider in step 6.
- Create a test user in your Service Provider Org, and set their Federation ID to the same value as your test user in the Identity Provider. This will effectively bind the two accounts together.
- Logout of both Orgs.
- Type the My Domain URL of the Identity Provider Org into your browser ( in this case: : https://edyidp-developer-edition.my.salesforce.com/ )
- Login to your Identity Provider Org as the test user
- Now, type the URL of the Service Provider Org into your browser (in this case https://edysp1-developer-edition.my.salesforce.com )
- You will immediate be redirected to the Identity Provider org. Since you're already authenticated you'll get redirected back to your Service Provider org, and presto… you should be logged in.
Step 8: Repeat steps 5 and 6 for each additional Service Provider Org
Assuming Step 7 went well and single sign-on is working for your first Service Provider Org, repeat steps 5 and 6 for any additional orgs.
These are the basic steps of establishing multi-org single sign-on. We'll now move on to a few advanced topics
Chatter and Multiple Orgs
It's important to remember that while this solution provides the ability to login to multiple Orgs with a single credential, it does not yet provide convergence of Chatter networks across these Orgs. While the Identities and their Chatter networks remain segmented, the best practice single sign-on established in previous section allows for clients such as Chatter Desktop to login with the exact same credential. And, since Chatter Desktop, and other third party clients such as Seesmic, support connecting to multiple Salesforce identities, it is possible to interact with multiple Chatter networks from a single client. The following describes the few simple steps required to connect to your multi-Org single sign-on configuration with Chatter Desktop, demonstrating the simplicity of this approach.
To connect to a Chatter Network in each of your Service Provider Orgs, follow these steps:
- When logging into Chatter Desktop for a new Service Provider Org, click "Add New Connection"
- Provide a name for the Org, and the fully qualified 'My Domain' of the Org you are attempting to access
- Click on Authenticate
- Chatter Desktop will then connect to your Service Provider Org, and using SAML, redirect the user to authenticate at your IDP. Once authenticated, the user can access Chatter in the Service Provider Org.
Once connected to multiple Orgs, users can now go to the Settings area of Chatter Desktop, and choose which Org's chatter to view as seen below
It's important to note that not all mobile and desktop clients support multiple accounts. For more information on single sign-on, and its use with various clients, consult the whitepaper Single Sign-On for Desktop and Mobile Applications using SAML and OAuth.
Note: Another effective technique employed by Chatter customers with multiple Orgs is to designate a single Org as the main Chatter network for their company. As you're designing both your Chatter and Single Sign-On deployments, consider combining your main Chatter org and your Identity Provider Org as a hub for your users.
Managing and Linking Users Across Multiple Orgs
In order to effectively manage single sign-on across multiple Orgs, it's important to be able to easily correlate the identity of each user across each Org. The IdP will need to send identifiers for each user across each Service Provider Org. As the salesforce username is globally unique, it can be difficult to use this as the identifier, as you must change the structure for each org. While it is still required that users have unique usernames, in order to simplify the problem for the IDP, a special field called "Federation ID" may be used.
A Federation IDs is an identifier that is unique within a saleforce Org. Using this, the IdP can store and send a single identifier for the user to each Service Provider Org. For Example: A "Bob Jones" user in SP1 will have the same Federation ID as the corresponding "Bob Jones" user in the SP2 Org. In short, each user will have a unique username, but a common Federation ID.
Single Sign-On can offer a huge improvement in usability and productivity for users when used across multiple Orgs. By deploying these best practice guidelines, admins can quickly and easily establish access to all their Orgs with a single credential.
Special Considerations for ADFSv2
Configuration of this solution with Microsoft's Active Directory Federation Service can be a bit tricky. Instead of having individual Relying Party configurations for each Salesforce org, ADFS will only allow a single Relying Party to be configured. Once this is configured, add your My Domain for each org as "Relying Party Identifiers" under the "Identifier" tab, and add each Salesforce Login URL as "SAML Assertion Consumer Endpoints" under the "Endpoints" tab.
- Single Sign-On for Desktop and Mobile Applications using SAML and OAuth
- Single Sign-On with Force.com and Microsoft Active Directory Federation Services
- Developer Force Security Resource Page
About the Authors
Chuck Mortimore is responsible for Identity & Security product management at Salesforce.com.
Erik Yewell is a customer facing platform architect at salesforce.com.