Salesforce SSO in 5 Bullets

For my own edification, I want to summarize single sign-on options with Salesforce as succinctly as possible.

Using non-Salesforce credentials to get into Salesforce

This scenario can be simplified like this: A user already has a username + password combination stored in another system. The user wants to log into Salesforce using that existing username and password, instead of maintaining a separate username and password that's used only to log into Salesforce.

To achieve this, Salesforce allows:

• Delegated Authentication
• Federated Authentication using SAML 2.0
• External authentication providers: Facebook, Google, Janrain, LinkedIn, Microsoft Access Control Service, another Salesforce org, Twitter, any service provider who implements the OpenID Connect protocol

Using Salesforce credentials to get into another app

This scenario can be simplified like this: A user is already logged into Salesforce. The user wants to launch another app without having to authenticate again. Instead, the other app should recognize the user and respond accordingly, based on the the user's Salesforce session.

To facilitate this, Salesforce offers:

• SAML 2.0 Identity Provider
• OAuth 2.0 Authorization Server

Closing thoughts

A company can mix the two approaches above, so that Salesforce becomes an intermediate link in a chain that allows access to a third-party app using credentials maintained in a non-Salesforce system.

Login with Facebook for a community with Visualforce

Adding an auth provider (e.g., Login with Facebook) to a Salesforce Communities instance is pretty easy.

The Login with ... button is pretty magical: It knows what community you're logging into, and it knows what URL you're trying to access upon authentication. Based on that information when you click the button, you're taken to the correct authentication URL based on the Auth Provider configuration in Salesforce.

But... for orgs that have customized their login pages with Visualforce, how do you add this button? Luckily, adding the same magical button to a custom Visualforce login page doesn't require you to manually reconstruct the OAuth authentication endpoint. Instead, you can just use the AuthConfiguration.getAuthProviderSsoUrl() method.

Simply put, you need just three things:

• Your community's base URL
• The relative path after the base URL to which the user should be taken upon successful authentication. This is also known as the startUrl.
• The URL Suffix (a.k.a. DeveloperName) of your auth provider (e.g., Facebook) as configured in Salesforce

Once you have this information, all you need to do is create an action in your Apex controller that returns a PageReference object, constructed from the URL returned by AuthConfgiuration.getAuthProviderSsoUrl().

This same approach can be applied to other auth providers as well, such as Twitter or Google.

AuthConfiguration.getAuthProviderSsoUrl(String, String, String) explained

Curious about AuthConfiguration.getAuthProviderSsoUrl(String, String, String)? Here are some notes about the parameters that may not be apparent the first time you read the documentation.

String cUrl

You'll want this to match exactly what you see when you're looking at your community's Administration Settings. Don't add any extra trailing slashes!

String startUrl

This should be the URL relative to the value you put for cUrl, including the leading forward-slash ('/'). For example, if you want to land the user at the Home tab, startUrl should be set to "/home/home.jsp" (again, note the inclusion of the leading forward-slash).

Think about it this way: If you concatenate cUrl and startUrl, exactly as written, you should end up with a valid URL to the desired page or resource within your community.

String developerName

This is the DeveloperName field from the AuthProvider object. Or, you can find the value by looking at the URL Suffix field on the Auth Provider detail page.

You can find this value dynamically by querying the AuthProvider object.

Faraday::SSLError certificate verify failed

Faraday::SSLError
SSL_connect returned=1 errno=0 state=SSLv3 read server certificate B: certificate verify failed

In recent memory, this is easily the most frustrating error I've had to troubleshoot. I needed SSL to work so that I could establish secure communication between Salesforce and my Rails app on Heroku. Unfortunately, neither Heroku's sample Ruby (off Rails) app nor general OmniAuth documentation seemed to give any insight into the error or how to resolve it.

Piecing together bits of knowledge gleaned from Google searches, I eventually arrived at the following solution for Rails development on Windows 8:

• Download root certificates in PEM format
• Set an environment variable called CA_FILE, pointing to the downloaded PEM file
• Create an omniauth.rb initializer file, as suggested by OmniAuth
• Specify the :client_options hash value for the :salesforce provider, as shown below

I know I'm going to run into this error again in the future, and hopefully this blog post will help me and hopefully others resolve the problem in the most secure and supportable means available.

SAML 2.0 Single Sign-On (SSO) Tutorial for Salesforce

Conceptually understanding single sign-on (SSO) is great, but actually implementing SSO can be a tricky business. Especially if you don't do it very often. Or if you have no experience with SSO at all. While there are many modes of SSO available for consumer apps, such as OAuth, SAML is still very prevalent in the enterprise applications space.

Salesforce is amazing in that with no hassle and for free (read $0.00), you can set up a SAML SSO environment with two DE orgs, one as a service provider and one as an identity provider. This should give you a fine test bed for exploring the protocol and also for testing integrations with other systems. Unfortunately the best tutorial previously available is now outdated, presenting a challenge to new SSO admins trying to wrap their heads around SAML 2.0 and Salesforce.

To bridge the gap, I consolidated a day's worth of tinkering and re-learning into a single SAML 2.0 SSO Tutorial for Salesforce. I hope that other developers and admins can benefit from this guided exploration of both sides of SAML 2.0, using Salesforce both as an identity provider and as a service provider.

UPDATED April 15, 2014: Thank you, Chuck Mortimore for sharing a link to a more in-depth walkthrough on Developer Force for implementing SAML 2.0 SSO using Salesforce.