Salesforce SSO integration

Ticket 0003361

Note: The term Salesforce and SF have been used interchangeably below.

Currently Learnexa provides a separate UI that can be shown in Salesforce by adding a Custom Tab. Steps documented @ https://tracker.exphosted.com/view.php?id=2665#c3415

One of the draw back of the current implementation is the way a Learnexa user is logged in to the application. Right now, when a SF user clicks on Learnexa tab in SF we present a Learnexa login screen where the user has to enter authentication details of Learnexa to login. The whole purpose of implementing SSO with salesforce is to provide seamless login between Salesforce and Learnexa.

The final goal of SF SSO integration is to build a feature which allows below mentioned use cases (assume that the initial step of setting up SSO configuration is already done)

Pre conditions:

• Initial SSO configuration is done in SF and the corresponding Learnexa site
• User has Salesforce account
• User has an account in Learnexa with same email as in Salesforce

Steps and Expected behavior

• User logs in to Salesforce via some email address. e.g. amit.rawal@gmail.com
• Clicks on Learnexa tab
• User is not asked for learnexa password but is directly logged in and gets redirected to My Learning page inside the Learnexa tab of Salesforce
• Now if the user opens the Learnexa site directly in another browser tab, he should also be automatically logged in to learnexa site.

Pre Conditions

• Initial SSO configuration is done in SF and the corresponding Learnexa site
• User has Salesforce account
• User does not have account in Learnexa

Steps and Expected behavior

• User logs in to Salesforce via some email address. e.g. amit.rawal@gmail.com and clicks on Learnexa tab
• We figure that there is no user in Learnexa with the given email ID.
• User is shown a screen(from learnexa) which can accept First Name and Last Name. The email field should be auto populated based on SF email. Note that the password field will not be present.
• User submits the data.
• Normally a new user registration requires the user to activate his account via the activation link sent to his his email account. However, when signing up via Salesforce, this activation step will be skipped. The user will directly be activated. Note that the user registration approval flow will still be executed (if the site admin has set the flag to approve all new registrations).
• Since we do not accept password from the user when his Learnexa account gets created via Salesforce, the user cannot directly login into the Learnexa Site. As a remedy for this, once the user registration is complete, we will send a mail to the customer indicating that currently he can visit the Learnexa site only via the “Learnexa” tab in Salesforce. If he wishes to login directly to Learnexa then he needs to set a password first. The password can be set via the forgot password flow. i.e. User will click on forgot password link, enter his email and submit the information. He receives a forgot password email with a link to reset the password. Clicking on this link will allow the user to set password for Learnexa account.

SSO with Salesforce will implemented using SAML. Security Assertion Markup Language (SAML) provides a secure, XML-based solution for exchanging user security information between an identity provider and a service provider. In our case, Salesforce will be an Identity Provider and Learnexa will be Service provider/relying partner. i.e. In other words Learnexa will use SF to authenticate a user. More information on how to setup SF as identity provider and what information is required for exchanging information between Identity provider and service provider can be found at

http://ap1.salesforce.com/help/doc/en/identity_provider_about.htm

http://ap1.salesforce.com/help/doc/en/identity_provider_enable.htm

https://onelogin.zendesk.com/entries/20186386

https://onelogin.zendesk.com/entries/165434-saml-toolkit-for-ruby-on-rails (Integration with ROR)

Each company can configure SSO settings (currently we support only SF).

sso_settings

users

After configuring SF as identity provider the Learnexa admin will have to configure SSO settings in the learnexa site. Below is how the UI will look like.

Create an account @ https://login.salesforce.com/?lt=de (Developer edition) Salesforce account details: amit.r@yopmail/test1234

Also create a new site in learnexa

1. sfssotesting.dev01.exphosted.com
2. Site admin info amit.r@yopmail.com/password
3. Ensure that the super site admin enables Salesforce feature for the newly created site (By default it is enabled)

1)Login to salesforce

2) In the left panel go to Security Controls → Identity Provider (click on Identity provider link)

3) If the salesforce domain is not configured then it needs to be done. Click on 'Configure the Domain', enter valid domain and Submit the form. e.g. https://sfssotesting-dev-ed.my.salesforce.com

4) After domain creation it takes a while for salesforce to activate it. Once activate you will get a mail in the email account that was registered with Salesforce.

5) Login again from the new SF url i.e. https://sfssotesting-dev-ed.my.salesforce.com

6) Go to Security Controls → Identity Provider

7) Click on “Enable Identity Provider”

8) Once enabled, click on Download Certificate to download the certificate provided by SF and save it to your local system.

9) Now Setup a service provider in Salesforce (by following steps below)

10) On the same screen Click on “Service Providers are now created via Connected Apps. Click here.” link next to “Service Providers” and enter following values for the input boxes

Basic Information

Connected App Name: Learnexa (can give any name)

Api Name: Will be auto filled by SF. Leave it as it is. Usually will be the same value as put in “Connected App Name” field.

Contact Email:: give any valid email address.

Leave reset of the fields in Basic Information Section as it is.

Go to “Web App Settings” section and check the “Enable SAML” check box option. Enter following values in the fields

Start URL: Leave empty

Entity ID: Enter some value (will have to be changed later)

ACS URL: http://sfssotesting.dev01.exphosted.com/saml/callback i.e. <learnexa site url>/saml/callback

Subject Type: keep “Username” radio button selected

Name ID Format: keep default selection selected i.e. 'urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified'

Issuer: Would have been auto populated. Leave it as it is.

Service Provider Certificate: Keep unchecked

11) Click on Save

12) Navigate to “Connected Apps” list page. i.e. In the side bar look for “Connected Apps” section and expand it (by clicking on the expand icon next to “Connected Apps” link).

13) In the Apps listing, click on the link which shows the name of the app you just created. (Note: click on the name and not the “Edit” link). This will show the Connected App Detail Screen.

14) Note down the value in “SP-Initiated Redirect Endpoint” field. (in Login Information section)

15) Switch back to Your learnexa site (in other browser tab)

15) Go to Manage Site → Single Sign-On screen and enter following values in the fields

Name: Some unique value e.g. Salesforce SSO

SSO Target Url: Enter the value that was noted from Salesforce on step 14) e.g. https://sfssotesting-dev-ed.my.salesforce.com/idp/endpoint/HttpRedirect

Certificate: Select the certificate file that was downloaded on step 8

16) Click on Save. On successful save, the UI will show the value of Entity ID. Note down that value and switch back to Salesforce's Connected App Tab

17) Click on “Edit” button (on top of the screen) and Update the value of “Entity ID” field with the value that was given by Learnexa and click Save.

18) Clicking save will bring you back to “Connected App” Detail screen.

19) Go to Manage Apps → Connected apps and click on “Manage Profile” button.

20) Select all the checkboxes and click Save.

Setup the Learnexa Tab in Salesforce.

21) Follow the steps mentioned in Bug#2665

22) After adding Learnexa Tab in Salesforce, it should now be visible in Salesforce. Click on it. Learnexa's My learning Page should appear (without asking the user for logging in)

Steps to Setup Learnexa tab in SF

In the upper right portion of the screen, click your name, and click “Setup”

• In the left navigation, click App Setup > Create > Tabs
• In the Web Tabs section of the Custom Tabs page, click “Edit” next to the Learnexa label.
• Advance through the tab properties pages and make desired adjustments.
• In the step 3 i.e. “Step 3. Enter the URL Details” enter the site url that matches examples given below. e.g

http://sfssotesting.dev01.exphosted.com/saml/index

   http://methodyoga.com/saml/index
   In short append "/saml/index" to the Site's hostname. 

Note on self signed certificate provided by Salesforce. (The one you downloaded in Step 8)

I found that the certificate that is available for download from SF sometimes is invalid. Check following

1) Open the certificate file in notepad or any other text editor.

2) If you see a carriage return between the certificate data and —–END CERTIFICATE—– line then the certificate is not valid. Get rid of the carriage return and save it. Use the modified certificate to upload in Learnexa's SSO page.

Example of invalid Certificate

Example of a valid Certificate