Salesforce is a popular business software platform with many functions and features – not just a CRM For B2B applications. Allowing users to log in with their Salesforce credentials is necessary functionality, but working with SAML is often a developer’s least favorite task. That’s where Single Sign-On with the Stormpath Java SDK and Spring Boot integration come in.

In this tutorial, I’ll walk you through how simple it is to configure SAML single sign-on with Stormpath and connect it to Salesforce.

Setup Salesforce to Connect to Stormpath

To begin, we have to enable SAML on both the Stormpath and Salesforce sides and then connect the two. We do this via the Salesforce front-end and the Stormpath Admin Console screens. To connect Salesforce to our Stormpath tenant we need to modify three parts of the global settings from Salesforce — the Identity Provider, Single Sign-On, and the Connected App.

All of these settings can be found under Setup Home when clicking on the gear icon on the top-right.

Identity Provider

SAML breaks authentication into three parts – the User, the Service Provider, and the Identity Provider. The identity provider provides access to the service. The most common identity providers are Facebook and Google. You probably have seen the ‘Login with Google’ buttons on various sign-in pages.

We need to set our Salesforce instance up as an Identity Provider. The screen for this is under Settings > Identity > Identity Provider.

Just click on Enable Identity Provider. Then click Save and download both the Certificate and Metadata (which we will use in a moment).

Single Sign-On

The term Single Sign-On (SSO) encapsulates what SAML allows — users accessing various sites and resources with one credential. We enable this on Salesforce by going to Settings > Identity > Single Sign-On Settings. Click Edit, check ‘SAML Enabled’, and then click Save. Finally, click ‘New from Metadata File’, select the metadata we just downloaded and click Create. Don’t worry about filling in details.

Connected App

The last part of our three-part Salesforce configuration is Apps. Apps are how Salesforce enables functionality. Go to Platform Tools > Apps > Apps. Scroll down to the Connected Apps section and click New. Type in a name and email (anything will do), scroll down to the Web App Settings and check Enable SAML. Type anything you like into the Entity ID (like ‘changeme’) and ACS URL (like ‘http://example.com’), we’ll be filling these in with details from Stormpath shortly, then set the Name ID Format to emailAddress, and click Save.
Salesforce connected apps

Click on Manage and make a note of the SP-Initiated Redirect Endpoint. We’ll be using these details in our Stormpath configuration.

Setup Your SAML Integration in Stormpath

The second half of our setup tasks happen in your Stormpath Admin Console. Primarily this involves three things — creating a SAML Directory, linking your Application, and configuring Mapping Attributes.

Create a SAML Directory

In the Directories tab, click on Create Directory, select SAML from the Directory Type, and give it a name. Enter in the endpoint we just mentioned into both URL fields (Login/Logout) and copy the contents of the certificate we downloaded into the Cert box. Make sure the Algorithm is RSA-SHA256 and click the create button. Your new directory should be shown in the directories list.

Stormpath SAML Admin Console

Before we move on to the Stormpath Application, we need to link the directory we just created to our Salesforce Application. We’ll use fields Entity ID and ACS URL. For each, enter the directory HREF (you can see it on click) and the Assertion Consumer Service URL (seen in the Identity Provider tab, and the bottom of the directory page), respectively. Just click on Edit, change the fields, and click Save.
Salesforce WebApp Settings

Configure Your Account Store

Now we need to set up the application you link to when authenticating via Stormpath. Open up the application you intend to use via the Applications tab. Make sure the Authorized Callback URIs contains the URL of your user interface. (If you are running the app locally, the callback should be http://localhost:8080/stormpathCallback).

Click on the Account Stores navigation button and then Add Account Store. You should be in the Directories tab from which you can select the directory we created above. Click Create Mappings. A mapping should appear in the list of stores for your application.
SAML Account Store Config

Booting with Spring Boot

To determine if our initial setup has been successful, we need an application that is linked to Stormpath. We have a sample setup here for this tutorial. You will need to update the application.properties file in src/main/resources to point to your application and use the right keys.

Note: In production, you shouldn’t put your application href and keys into application.properties. It’s better to use environment variables instead of baking this into code.

You should now be able to boot up directly using Maven.

Browsing to localhost:8080 should show you a simple homepage.

Local Host -- Salesforce / Spring Boot WebApp

Clicking on the Restricted button will show the login screen which now has a Salesforce login button.
Stormpath Login Screen with Salesforce

Clicking on the Salesforce button should take you to a Salesforce login page.

Salesforce Login

Once you log in, you will be taken back to the Spring Boot Application page, but now with a hello message displayed.

Restricted View

The reason we’re seeing NOT_PROVIDED is because we haven’t set up our attribute mappings.

Configure Attribute Mappings

So far all we’ve set up is how we identify the user, and that’s via username. (We set it using the Name ID Format in Salesforce when we created our application). However, if we look at the template used to generate our logged-in homepage we can see it uses the fullName on the account, which we haven’t mapped yet.

In Stormpath the account fullname is built from the given and last names. See this explanation from the Stormpath documentation to learn more about account fields.

For now, we need to map those values onto the SAML data from Salesforce, and then from the SAML data to the relevant Stormpath values.

From Salesforce

Inside of your application, at the bottom, is a section called Custom Attributes.

Salesforce Custom Attributes

Click on the New button. This will bring up a dialogue with Key and Value fields. Inside Key put ‘firstname’. Then click on Insert Field, click on $User > and then First Name, and then click Insert. This will put the correct string into the Value field which is the user’s first name. Click Save.

Do this again for the user’s last name and you should have two custom attributes defined.
Salesforce Custom Attributes

To Stormpath

In the Stormpath Admin click the Directories tab, select the directory we created above and scroll down to the the Attribute Mappings tab. When you click into that tab you should see three columns – Attribute Name, Attribute Name Format, and Stormpath Field Names. For the first column put in firstname and for the last put in givenName (the middle field is optional). Then for another row put in lastname and surname, respectively.
Stormpath SAML Admin Console

Click save!

Restart Your Application = Success!

Now if we restart our local application and login again, we should see the user’s (in this case my) first and last name pulled in from Salesforce.
Salesforce SAML Login Screen

Learn More

As you’ve hopefully seen from this tutorial, setting up single sign-on with Stormpath and Salesforce makes working with SAML a breeze! To learn more about authentication with Stormpath, or our SAML integration, check out these resources:

  • Watch: No-Code SAML Support for SaaS Applications
  • Build a No-Database Spring Boot Application with Stormpath Custom Data
  • Add Google Login to Your Java Single Sign-On Setup