SSO Salesforce Setup

The following instructions set up an identity provider in Salesforce.

Introduction

Salesforce is a Single Sign-On (SSO) Provider and application portal. Tehama can be integrated with Salesforce through SAML and presented as a managed application alongside other Salesforce integrated applications.

Once enabled, authentication to Tehama must be made through Salesforce - local authentication through https://app.tehama.io is no longer possible except by using the Tehama Admin account. Unless you enabled user provisioning, Salesforce/Tehama Integration is limited to authentication only.

A user account is required for Salesforce.

If you do not enable user provisioning, then a user account is also required for Tehama. Both the Salesforce account and the Tehama account must be configured with the same email address for SSO to work, and the user must accept the Tehama Welcome email before they will be able to launch a connection via Salesforce SSO.

Create a connected application

Create a Developer Salesforce account

  1. In a browser tab, go to the address developer.salesforce.com.

    developer.salesforce.com

    Click on the Sign Up > button at the top right to sign up for a Salesforce Developer account.

    developer.salesforce.com/signup

    Follow the instructions provided. When completed, Salesforce will send you a "Welcome" email.

    developer.salesforce.com/signup/success

  2. Login using the email sent to you in the last step.

    developer salesforce welcome email

    Click on the Verify Account link in the email. If asked to change your password, go ahead and do so.


Configure a Developer Salesforce Domain

Now that you are logged in to your Salesforce Developer Account, you need to configure a Domain.

  1. Go to the Setup page.

    developer salesforce setup page

  2. Scroll down the left side-bar menu and Select Identity > Identity Provider

    developer salesforce identity provider page

  3. Click on Configure a Domain Name, found under "Identity Provider Setup".

    developer salesforce domain page

  4. Enter a domain name into the url line. Click Check Availability to make sure it is unique.

    developer salesforce domain page filled out

  5. Click Register Domain to set up your new domain.

    developer salesforce domain registering page

  6. Wait for a confirmation email to arrive.

    developer salesforce domain email

  7. Click on the link in the email to sign in with your new domain.

    developer salesforce domain signin

    You may be asked to register your mobile phone with your new domain. Proceed if desired or click on one of "Remind Me Later" or "I Don't Want to Register My Phone".

    developer salesforce domain loggedin

    You are now logged in to your new Domain in your Salesforce Developer account.

Set up an Identity Provider in your new Developer Salesforce Domain

Now that you are logged in to your new Domain in your Salesforce Developer Account, you need to set up an Identity Provider (at last!).

  1. As before, starting from the Setup page, navigate to Identity > Identity Provider.

    developer salesforce domain identity_provider

  2. Click on Enable Identity Provider.

    developer salesforce domain identity_provider

  3. From the dropdown, select the proposed SelfSigned certificate, then click Save.

    developer salesforce domain enabled identity_provider

    You will now be back on the Identity Provider page with additional details.

    developer salesforce domain configured identity_provider

Add your Tehama Organization to the Identity Provider as a new Connected App

Now that you have an identity provider enabled, add your Tehama Organization's details to it to set it up as a new Connected App.

  1. Still viewing the Identity Provider page in your Developer Salesforce domain, click on Service Providers are now created via Connected Apps. Click here.

    developer salesforce domain manage new app

  2. In the "New Connected App" form, enter the following, leave the rest blank or default:

    • Connected App Name: tehama
    • API Name: tehama
    • Contact Email: {your email address that you used to sign up for Salesforce}
    • Start URL: {The "Entity ID" from the Tehama tab}
    • Enable SAML: {enabled}
    • Entity Id: {The "Entity ID" from the Tehama tab}
    • ACS URL: {The "Callback URL (Assertion Consumer Service URL)" from the Tehama tab}
    • Subject Type: Persistent ID
    • Idp Certificate: SelfSignedCert_XXXX
  3. Click Save.

    developer salesforce domain new app page

  4. Click on the Manage button at the top of the page.

    developer salesforce domain manage app page

  5. Click on Download Metadata button found under the "SAML Login Information" section.
  6. Copy the XML contents of this downloaded file (you will need it to finish the Tehama SAML configuration back in the Authentication page).
  7. Now go to on Users > Users page.

    developer salesforce domain users page

    In the list of users, find the user that you are signed in with. It should have the Profile "System Administrator".

  8. Click on the profile link "System Administrator".

    developer salesforce domain sysadmin user profile

  9. Click Edit.

    developer salesforce domain edit sysadmin user profile

  10. Go down to "Connected App Access" and check "tehama".

    developer salesforce domain sysadmin user access app

  11. Press Save.

Enable SAML User Provisioning

Now that you have a Connected App to Tehama, you can configure it to provide user provisioning.

User provisioning sets up a relationship, a mapping, between the Salesforce user profile and the Tehama user profile that enables the following 'auto-provisioning' behaviour:

  • Your organization's users can join Tehama without an explicit invitation link.
    i.e.: A Tehama user account is automatically created for a user the first time they attempt to log in to Tehama using the credentials of their Salesforce account. Their Tehama account's user profile is populated using values from their Salesforce account's user profile.

  • Your organization's users can manage their Tehama account's user profile through their Salesforce account.
    i.e.: Update the user's information in their Salesforce account's user profile, and it will be automatically updated in their Tehama account's user profile (only for those user profile attributes that are mapped).

  • Your organization's users can (optionally) be proposed for membership in your organization's Rooms through their Salesforce account.
    i.e.: A Tehama-specific attribute can be added to your Salesforce user profile where you can specify Tehama Room ids for Rooms in your Tehama organization for the user to be added to.

There are four parts to setting up user provisioning:

  1. User Provisioning Part One: Add Custom Attributes to Salesforce's User Profile
  2. User Provisioning Part Two: Add Values for Custom Attributes in a Salesforce User Account
  3. User Provisioning Part Three: Add Custom Attributes to your Connected App for Tehama in Salesforce
  4. User Provisioning Part Four: Map the Connected App's Custom Attributes to the Tehama User Profile in Tehama

User Provisioning Part One: Add Custom Attributes to Salesforce's User Profile

Reason for completing this section (and the next):

This section and the next one show you:

  • how to add custom attributes to Salesforce's user profile (this section, Part One) and
  • how to assign values to them for individual users (the next section, Part Two)

so you can auto-provision the following Tehama-specific attributes found on the Tehama user profile:

  • Tehama Role: the role taken by the user in Tehama, one of MANAGER or STAFF
  • Tehama Default Room IDs: the IDs of the Tehama Rooms the user is automatically put up for membership in 1,2

Auto-provisioning of these two Tehama user attributes is optional.

Without auto-provisioning:

  • the Tehama Role attribute will default to STAFF and any changes must be done through Tehama's Web UI; and
  • the Tehama Default Room IDs attribute will default to an empty list (e.g.: the user will not be put up for membership in any Rooms.) and Room membership must be managed through Tehama's Web UI.

If you DO NOT want to auto-provision Tehama Role or Tehama Default Room IDS, then skip ahead to User Provisioning Part Three and Part Four.

Otherwise, if you DO want to auto-provision these Tehama user attributes, follow the steps here in Part One and in Part Two first.


Footnotes

  1. Tehama Default Room IDs is only looked at when the user's Tehama account is first created. For example, if this attribute has value '2,7' when the user's Tehama account is created, then the user will be added to the Room with ID 2 and the Room with ID 7 within your organization.

  2. Tehama Default Room IDs is used to propose the user for Room memberships. If a Room has auto-approvals enabled, then the user will be added to that Room automatically. Otherwise, the user's proposed membership must be manually approved by the connected organization for the Room from the Tehama Web UI before the user is added to the Room.  

Steps for part one:

Log into your Salesforce account and go into Setup. Select Objects and Fields from the sidebar menu. Then select Object Manager.

Object Manager in Sidebar Menu

This will bring you to the Object Manager page. (The sidebar menu will disappear.)

Object Manager

Click on the User object, then click on Fields & Relationships.

User Fields and Relationships

From here you can add your custom attributes, Tehama Role and Tehama Default Room IDs.

Tehama Role:

Click New and then select Picklist.

User new field of type picklist

Click NEXT. You will see the Enter the details page.

  • Enter "Tehama Role" in the Field Label field.
  • Select the "Enter values, with each value separated by a new line" option and enter STAFF and MANAGER, on separate lines, in that order, in the text box.
  • Disable "Display values alphabetically, not in the order entered".
  • Enable "Use first value as default value".
  • Enable "Restrict picklist to the values defined in the value set".
  • Enter "Tehama_Role" in the Field Name field.
  • Optionally enter a description in the Description field.
  • Optionally enter help text in the Help Text field.
  • Disable "Always require a value in this field in order to save a record".
  • Leave the Default Value field blank.

User new field of type picklist enter-the-details

Click Next.

User new field of type picklist establish-security

Ensure that the new field will be visible to the Standard User. (Make sure checkbox under the Visible column for the "Standard User" row is checked.)

Click Next.

User new field of type picklist add-to-page-layout

Enable "User Layout".

Click Save. You have now added the Tehama_Role attribute to Salesforce's user profile.

Tehama Default Room IDs:

(From the Fields and Relationships page)

Click New and then select Text.

User new field of type text

Click NEXT. You will see the Enter the details page.

  • Enter "Tehama RoomIDs" in the Field Label field.
  • Enter "255" in the Length field.
  • Enter "Tehama_RoomIDs" in the Field Name field.
  • Optionally enter a description in the Description field.
  • Optionally enter help text in the Help Text field.
  • Disable "Always require a value in this field in order to save a record".
  • Disable "Do not allow duplicate values".
  • Disable "Set this field as the unique record identifier from an external system".
  • Leave the Default Value field blank.

The value of the Tehama RoomIDs attribute is a comma separated values (CSV) list of IDs of Rooms in your Tehama organization.

User new field of type text enter-the-details

Click Next.

User new field of type text establish-security

Ensure that the new field will be visible to the Standard User. (Make sure checkbox under the Visible column for the "Standard User" row is checked.)

Click Next.

User new field of type text add-to-page-layout

Enable "User Layout".

Click Save. You have now added the Tehama_RoomIDs attribute to Salesforce's user profile.

User Provisioning Part Two: Add Values for Custom Attributes in a Salesforce User Account

Reason for completing this section:

This section shows you how to assign values to custom attributes in Salesforce's user profile for individual users - namely, the custom attributes Tehama Role and Tehama Room IDs.

See the reason for completing Part One. Only complete this section if you completed Part One. Otherwise move on to Part Three.

Steps for part two:

Log into your Salesforce account and go into Setup. Select Users from the sidebar menu. Then select Users. This will bring you to the Users page.

Users Page

Click Edit next to the name of the user you wish to edit. Scroll down until you see the Additional Information section, which contains the "Tehama Role" and "Tehama RoomIDs" attributes.

Users Edit Page

Add values to those attributes.

  • For "Tehama Role", this is simply selecting either "MANAGER" or "STAFF" from the picklist.
  • For "Tehama RoomIDs", this requires you to compose a comma separated value string (CSV) of Tehama Rooms ids. See the section entitled Find Room IDs in User Provisioning Part Four below.

Click Save.

To see the values of those attributes, click on the Full Name of the user.

Users User Page

User Provisioning Part Three: Add Custom Attributes to your Connected App for Tehama in Salesforce

Reason for completing this section:

This part is where you make the link between Salesforce's user profile attributes and your connected app for Tehama.

Add custom attributes to your connected app for Tehama, mapping them to the attributes in the Salesforce User Profile.

Steps for part three:

Log into your Salesforce account and go into Setup. Select Connected Apps from the sidebar menu. Then select Manage Connected Apps. This will bring you to the Manage Connected Apps page.

Manage Connected Apps Page

Click on the Master Label of your connected app for Tehama.

Tehama Connected App Page

Scroll to the Custom Attributes section. Click New. This will bring you to the Create Custom Attribute page.

  • Enter the name of your new custom attribute in the Attribute key field.
  • Beside the Attribute value field, click Insert Field. A dialog will pop up with a list of the various Salesforce objects.
  • Select $User >.
  • Scroll through the list of user profile attributes and select the appropriate one for your new custom attribute. See the list below for pairings.
    Tehama Connected App New Custom Attribute Page
  • Click Insert. Your selection now shows up in the Attribute value field.
  • For most attributes, you would now be done. But if your attribute is complex, e.g. based on a picklist like the "Tehama Role" attribute, you can now edit the Attribute value field appropriately. See the list below for the text that should be in this field for each such complex attribute.
    Tehama Connected App New Custom Attribute Page
  • Click Save
    Tehama Connected App New Custom Attribute Page

Repeat the above steps for the attributes you intend to auto-provision.

"Email", "First Name" and "Last Name" are mandatory. Optional attributes that not auto-provisioned will be given default values when the user is created and must be managed through the Tehama Web UI.

You will end up with a subset of the following custom attributes:

Tehama Connected App New Custom Attribute Page

List of custom connected app attributes paired to the Salesforce user profile attributes:

  • Email -> $User.Email mandatory
  • FirstName -> $User.FirstName mandatory
  • LastName -> $User.LastName mandatory
  • Title -> $User.Title
  • PhoneNumber -> $User.Phone
  • StreetAddress -> $User.Street
  • City -> $User.City
  • StateProvince -> $User.State
  • Country -> $User.Country
  • ZipPostalCode -> $User.PostalCode
  • TehamaRole -> IF(ISPICKVAL($User.Tehama_Role__c,"MANAGER"), "MANAGER", "STAFF")
  • TehamaRoomIDs -> $User.Tehama_RoomIDs__c

User Provisioning Part Four: Map the Connected App's Custom Attributes to the Tehama User Profile in Tehama

Reason for completing this section:

This part is where you make the link between the attributes in your connected app for Tehama in Salesforce and Tehama's user profile.

Map the custom attributes you created in Part Three to the attributes in Tehama's user profile in the Tehama Web UI.

Steps for part four:

Login to Tehama using the Admin Account and click on the SETTINGS tab in the navigation bar.

Select the AUTHENTICATION tab. Scroll down to the USER PROVISIONING section (visible when the "Enable SAML Single-Sign on" checkbox is checked). Select "SAML" from the dropdown list of user provisioning options.

Tehama Authentication User Provisioning

Add/remove attributes from the table as follows:

  • Add: Select an optional attribute from the dropdown list and then click on the ADD button to add it to the table.
  • Remove: Click on the 'X' in the row of an optional attribute to remove it from the table.

Enter the attribute names of the custom attributes you added to your Salesforce connected app for Tehama against the related Tehama account user attributes as follows:

  • Email -> Email
  • First Name -> FirstName
  • Last Name -> LastName
  • Role -> TehamaRole
  • Default Room Ids -> TehamaRoomIDs
  • Title -> Title
  • Phone Number -> PhoneNumber
  • Address -> StreetAddress
  • City -> City
  • State/Province -> StateProvince
  • Country -> Country
  • Zip/Postal Code -> ZipPostalCode
  • Country of Citizenship -> Country

Click SAVE.

You have now set up user provisioning for your organization from your Salesforce connected app.

Find Room Ids

Notice the button FIND ROOM IDS in the Possible Values column for the entry for "Default Room Ids". Click FIND ROOM IDS to bring up a dialog from which you can select Tehama Rooms from your organization. This produces a copyable comma separated value (CSV) string that you can use to populate the value of the custom attribute you added to the Salesforce user profile for Tehama Room ids above in Part Two.