Using Salesforce as an Identity Provider for WSO2 Identity Server over SAML 2.0 Web SSO

This article provides all the necessary steps to be followed when configuring WSO2 Identity Server to federate user identity with Salesforce.com.

System Architecture and Message Flow

Following diagram shows the important components in this setup and shows the order of the message flow.

In a high level view, here I have a web application (travelocity.com sample app) that tries to get authenticated with WSO2 Identity Server over SAML 2.0 protocol. When the authentication request comes, Identity Server forwards the request to Salesforce by sending another SAML authentication request. Then, Salesforce prompts the user to login. Here, the end user should have an account created in Salesforce.com. After the user is logged in, Salesforce then sends the SAML response to Identity Server, which contains the SAML assertion that holds the authenticated user’s attributes (claims). Then, WSO2 Identity Server processes the response sent by Salesforce, and generates its own SAML response (claim transformation can be done during the process) and sends it to the client web application. Finally, the client web application processes the received SAML response, identifies the logged in user and completes the authentication process.

Now let’s get started setting up the above environment. First I am configuring the Salesforce, then WSO2 Identity Server and finally, the client web application.

Salesforce Configuration

The following sections below provide all necessary steps to be followed and the configuration to be created in Salesforce side.

Creating a Salesforce Account

If you do not have a Salesforce account yet, visit the Identity Platfrom of Salesforce from https://www.salesforce.com/products/platform/products/identity/  and click on ‘Try for Free’.

Then you need to fill the registration form and submit. After that, login to Salesforce Developer account on https://developer.salesforce.com/ and when it requests your permission to access your profile information, proceed with clicking ‘Allow’.

You might need to fill some additional details about you to continue.

Once above steps are done, you will see the following dashboard. Click on the Settings icon located in the top of the right hand side and then click on ‘Setup’.

Registering a Domain in Salesforce

Now, for using Salesforce as an Identity Provider, we need to have a domain registered in Salesforce. For that, in the search text box located in the left menu panel, type ‘my domain’. Then you will see ‘My Domain’ link getting listed under Company Settings. Click on that.

Fill the text box with a suitable domain and register it. The domain will follow the pattern https://<your_domain>.my.salesforce.com.

After completing the above steps, it will take around 2 minutes (or couple of more minutes) for Salesforce to publicly make the domain available. Once that is done, you will receive an email.

Creating the Identity Provider Configuration in Salesforce

For Salesforce to act as an Identity Provider, we need to setup an Identity Provider in Salesforce side. For that, in the search textbox in left menu, type ‘identity provider’ and it will suggest you the ‘Identity Provider’ link listed under ‘Identity’ settings. Click on that and then enable the Identity Provider.

Then, you can download the public certificate of this Identity Provider and the Meta Data. You need to keep the downloaded files to be used later, when configuring the Identity Provider in WSO2 Identity Server.

Creating the Service Provider Configuration in Salesforce

Next step is to create the Service Provider in Salesforce side. This is how Salesforce identifies the informing authentication requests and decide how to proceed. Inside the Identity Provider settings, in the Service Providers section, click on the link available for creating the Service Provider.

You can give a name for the Service Provider and fill the required details.

In the ‘Web App Settings’ click on ‘Enable SAML’ checkbox. Then, fill the Entity Id text box with a suitable name. Note that the same name you enter here has to be put in WSO2 Identity Server when creating the Identity Provider configuration in that later.

The ACS URL (Assertion Consumer URL) is the endpoint in WSO2 Identity Server which accepts the response sent by Salesforce. That is https://localhost:9443/commonauth (you can put the IP address if any).

The Issuer is the Domain URL you got from Salesforce after registering your domain.

As the IDP Certificate, you can select the certificate from the dropdown. The SAML responses/assertions will be signed from the same certificate.

Once completing above steps, save the settings and it will show a summary of the service provider configuration.

If you need to edit the Service Provider configuration later, in the left menu, search for ‘apps’ and it will list ‘Manage Connected Apps’ link. From there, you can see the already created applications (Service Provider Configuration is added inside an application) and edit them.

Here is the Application which I created for this usecase which lists all the configuration created.

Here, there are two important URLs to be note which are given below for your reference.

SP-Initiated POST Endpoint	https://tharinduatwso2.my.salesforce.com/idp/endpoint/HttpPost
SP-Initiated Redirect Endpoint	https://tharinduatwso2.my.salesforce.com/idp/endpoint/HttpRedirect

In Salesforce end, there are two different endpoints as above, for HTTP POST binding and HTTP Redirect Binding in SAML protocol. We need to use once appropriately (This is important when setting up the Identity Provider configuration in WSO2 Identity Server later).

Creating a User Profile

Now that the Identity Provider configuration and Service Provider configuration are created in Salesforce side, next step is to create a user profile and bind the application we created above, to that. You can use an already existing profile as you wish without creating a new profile if you wish.

Here, under ADMINISTRATION -> Users, click on Profiles and click on ‘New’ for creating a new profile.

Here I am cloning the existing ‘Standard User’ profile and creating a new profile with the name ‘Identity User’. (you can use any name as per your requirement).

Then I edit the created profile.

In the Profile configuration, under the ‘Connected App Access’ section, I click on the IdentityServer application and enable it. Here, IdentityServer is the application I created previously when creating the Service Provider configuration.

If you are not creating a new user profile, you can edit an existing user profile and enable the application for accessing as above.

Creating a User in Salesforce

Next step is to create a user in Salesforce. This is the user account that we are using when Salesforce prompts for user authentication in the this flow. If you already have users in Salesforce, you can skip creating new users.

In the search textbox in the left menu, search for ‘users’  and it will list the ‘Users’ link. From there, you can create new users.

Here I fill the user’s personal information. The important step is the select the user’s profile. The profile you select here must have the application (created previously) enabled for ‘Connected App Access’ as discussed before.

Here I click on ‘Save’ and complete user account creation. (The end user will receive an email for activating the account and resetting password).

With above, we have completed all necessary configuration in Salesforce side.

WSO2 Identity Server Configuration

The following sections below provide all necessary steps to be followed and the configuration to be created in WSO2 Identity Server side. Here I use WSO2 Identity Server 5.3.0 version (latest released GA version by the time of this writing).

Create Identity Provider Configuration

In this step, we create the configuration for letting WSO2 Identity Server know how to talk to Salesforce. Here add an Identity Provider and give the name salesforce.com. You can give any name as you wish.

Then you can give the ‘Identity Provide Public Certificate’ which you downloaded from Salesforce when configuring the Identity Provider in Salesforce. (You can skip this if you are going to create the configuration using SAML Metadata file, which I will explain in the next step).

Inside the Identity Provider configuration, expand the Federated Authenticators -> SAML2 Web SSO Configuration.

Click on the ‘Enable SAML2 Web SSO’ checkbox for enabling this SAML authenticator for this Identity Provider configuration.

Provide the Service Provider Entity Id field with the same name you defined in the Salesforce’s Service Provider’s ‘Entity Id’ field.

Then, you can either manually fill all the details and complete the configuration, or you can use the Metadata file downloaded from Salesforce Identity Provider, so it will automatically fill the details for you.

Here I am using the Metadata file downloaded from Salesforce to create the required SAML configuration.

Once you try to register the Identity Provider using the metadata file, it will show this warning. You can continue as we do not have created the configuration already. If you added the Salesforce’s Identity Provider certificate previously, it will be replaced. So, if you are creating the Identity Provider’s SAML configuration from the metadata file, adding the public certificate manually is not required.

Then I can see the required configuration is created. Alternatively you can do the same manually, without using the metadata file.

In above configuration, it is important to define the SSO URL correctly. Because, based on the HTTP Binding you are going to use, the SSO URL in Salesforce differs.

Inside the SAML configuration of the Identity Provider, it has the HTTP Binding radio buttons which you can use as per your requirement.

For HTTP-Redirect Binding, the SSO URL should be,  https://<your_domain>.my.salesforce.com/idp/endpoint/HttpRedirect   

For HTTP-POST Binding, the SSO URL should be,

https://<your_domain>.my.salesforce.com/idp/endpoint/HttpPost

Now that we have created the necessary configuration, click on ‘Update’ and complete the Identity Provider configuration creation in WSO2 Identity Server.

Create the Service Provider Configuration

Next step is to create the Service Provider configuration in WSO2 Identity Server. This is how Identity Server knows how to handle requests from client applications.

Add a Service Provider. Here I give the name ‘travelocity.com’, because I use the travelocity.com sample web application for this demonstration.

In the Service Provider’s configuration, expand Inbound Authentication Configuration -> SAML2 Web SSO Configuration and click on ‘Configure’.

Then I set the Issuer name to ‘travelocity.com’ and the Assertion Consumer URL to http://localhost:8080/travelocity.com/home.jsp (here I run the travelocity sample app in Tomcat server running on port 8080 of localhost). Once this configuration is set, click on ‘Update’.

We can see that the SAML configuration is created successfully. ‘Update’ the Service Provider configuration with this.

Now, WSO2 Identity Server can accept client web application’s requests over SAML 2.0 protocol. However, we need to redirect the flow to Salesforce, because the end user has to be authenticated with Salesforce. For making this connection work, edit the Service Provider you just created and expand the Local & Outbound Authentication Configuration. Select ‘Federated Authentication’ option and from the dropdown, select the Identity Provider you created previously for Salesforce.

Now we have completed all the configuration in WSO2 Identity Server.

Setting up the Client Web App

Here I use the travelocity.com sample webapp which is a client web application for demonstrating SAML 2.0 authentication flows. You can find the pre-built .war file from

https://github.com/thariyarox/travelocity.com/blob/master/IS5.3.0_AM2.1.0/travelocity.com.war and the source code of this application is available in WSO2 github repository https://github.com/wso2/product-is/tree/v5.3.0/modules/samples/sso/sso-agent-sample.

Here I deploy this application (war file) in Apache Tomcat server running on port 8080 in localhost.

I can access the application from the URL http://localhost:8080/travelocity.com/index.jsp.

Testing the Authentication Flow

In the travelocity.com sample client application, I click on the link available for SAML authentication. (You can select either Redirect Binding or POST binding).

Once you click the above link, it makes a SAML authentication Request to WSO2 Identity Server. Then, as we have configured Identity Server to forward the requests to Salesforce, Identity Server will make a SAML authentication request to Salesfofce. Then, Salesforce will prompt its login page and ask the end user to login.

Here I enter the user credentials (this user’s profile is already enabled with the Connected App Access) of the Salesforce user I created previously.

Then, Salesforce will send the SAML response to WSO2 Identity Server which contains the user’s attributes. Finally, Identity Server will generate it’s own SAML response and forward that to the client web application (Claim transformations can be done during the flow).

Finally, the client web application reads the received SAML response and get to know the logged in user and completes the authentication flow.

Written by: Tharindu Edirisinghe, Platform Security Team, WSO2